vue-ts-types

Lightweight TypeScript-first Vue prop type definitions

Example

1import { defineComponent } from 'vue';
2import {
3  arrayProp,
4  booleanProp,
5  functionProp,
6  isPositive,
7  numberProp,
8  oneOfProp,
9  stringProp,
10} from 'vue-ts-types';
11
12defineComponent({
13  props: {
14    disabled: booleanProp().withDefault(false),
15    // resulting prop type: boolean
16
17    title: stringProp().optional,
18    // resulting prop type: string | undefined
19
20    description: stringProp().nullable,
21    // resulting prop type: string | null
22
23    items: arrayProp<string>().required,
24    // resulting prop type: string[]
25
26    callback: functionProp<() => void>().optional,
27    // resulting prop type: (() => void) | undefined
28
29    color: oneOfProp(['red', 'green', 'blue'] as const).withDefault('red'),
30    // resulting prop type: 'red' | 'green' | 'blue'
31
32    timeout: numberProp(isPositive).required,
33    // resulting prop type: number
34  },
35});

Motivation

1options: {
2  type: Object as PropType<Options>,
3  required: true,
4}
5
6// with vue-ts-types:
7options: objectProp<Options>().required

1options: {
2  type: Object as PropType<Options>, // wrong, it should be `Options | undefined`
3  required: false,
4}
5
6// with vue-ts-types:
7options: objectProp<Options>().optional // automatically typed as `Options | undefined`

1disabled: {
2  type: Boolean,
3  required: true,
4  default: false, // contradictory to `required: true`
5}
6
7// with vue-ts-types:
8disabled: booleanProp().required // either required without default
9disabled: booleanProp().withDefault(false) // or optional with default

1age: {
2  type: Number,
3  required: true,
4  validator: (age: unknown) => {
5    return typeof age === 'number' && Number.isInteger(age) && age >= 18
6  },
7}
8
9// with vue-ts-types:
10age: integerProp((age: unknown) => {
11  if (typeof age !== 'number' || age < 18) {
12    return 'age should be a number of at least 18'
13  }
14  return undefined
15}).required

Installation

1npm install vue-ts-types

vue-ts-types has no dependencies and is tested to be compatible with Vue.js v2.6, v2.7 and v3.2.

Usage

Each of the prop functions returns an object with the following properties:

• .optional: Use this to mark the prop as not required with a default value of undefined. Also includes undefined in the resulting prop type.
• .nullable: Use this to mark the prop as not required with a default value of null. Also includes null in the resulting prop type.
• .required: Use this to mark the prop as required without a default value.
• .withDefault(value): Use this to set a default value for the prop. Note that the value has to fit the prop type. For non-primitive types, the value has to be a function that returns the default value.

ℹ️ Note:
Due to the way Vue props work, a prop's default value will only be used when passing undefined, not for null.
See issue #3135 in vuejs/vue.

Custom validator functions

Custom validator functions can be passed to any of the prop types. They are called with the value of the prop (type unknown) and should return a validation error message, or undefined if the value is valid. Validator functions do not influence type inference.

1import { numberProp } from 'vue-ts-types';
2
3type Validator = (value: unknown) => string | undefined;
4
5const isPositive: Validator = (value) => {
6  if (typeof value !== 'number' || value <= 0 || Number.isNaN(value)) {
7    return 'value should be a positive number';
8  }
9  return undefined;
10};
11
12numberProp(isPositive).optional;
13// → prop type: number | undefined

For convenience, some common validator functions are included in the library and can be imported just like prop types:

• isNegative: only allows negative numbers (< 0)
• isPositive: only allows positive numbers (> 0)
• isNonNegative: only allows non-negative numbers (>= 0)
• isNonPositive: only allows non-positive numbers (<= 0)

stringProp<T>(validator?: Validator)

Allows any string. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type at compile time with a union type. (Consider using oneOfProp in this case.)

1stringProp().optional;
2// → prop type: string | undefined
3stringProp().nullable;
4// → prop type: string | null
5stringProp().required;
6// → prop type: string
7stringProp().withDefault('foo');
8// → prop type: string
9
10type Foo = 'a' | 'b' | 'c';
11
12stringProp<Foo>().optional;
13// → prop type: Foo | undefined
14stringProp<Foo>().nullable;
15// → prop type: Foo | null
16stringProp<Foo>().required;
17// → prop type: Foo
18stringProp<Foo>().withDefault('a');
19// → prop type: Foo

booleanProp(validator?: Validator)

Allows any boolean (validated at runtime and compile time).

1booleanProp().optional;
2// → prop type: boolean | undefined
3booleanProp().nullable;
4// → prop type: boolean | null
5booleanProp().required;
6// → prop type: boolean
7booleanProp().withDefault(false);
8// → prop type: boolean

numberProp<T>(validator?: Validator)

Allows any number (validated at runtime and compile time). Type parameter T can be used to restrict the type at compile time with a union type. (Consider using oneOfProp in this case.)

1numberProp().optional;
2// → prop type: number | undefined
3numberProp().nullable;
4// → prop type: number | null
5numberProp().required;
6// → prop type: number
7numberProp().withDefault(3.1415);
8// → prop type: number
9
10type Foo = 1 | 2 | 3;
11
12numberProp<Foo>().optional;
13// → prop type: Foo | undefined
14numberProp<Foo>().nullable;
15// → prop type: Foo | null
16numberProp<Foo>().required;
17// → prop type: Foo
18numberProp<Foo>().withDefault(1);
19// → prop type: Foo

integerProp(validator?: Validator)

Allows any integer (validated at runtime).

1integerProp().optional;
2// → prop type: number | undefined
3integerProp().nullable;
4// → prop type: number | null
5integerProp().required;
6// → prop type: number
7integerProp().withDefault(42);
8// → prop type: number

symbolProp(validator?: Validator)

Allows any symbol (validated at runtime and compile time).

1symbolProp().optional;
2// → prop type: symbol | undefined
3symbolProp().nullable;
4// → prop type: symbol | null
5symbolProp().required;
6// → prop type: symbol
7symbolProp().withDefault(Symbol('foo'));
8// → prop type: symbol

vueComponentProp(validator?: Validator)

Allows any Vue component instance, name or options object. No built-in runtime validation is performed by default.

1vueComponentProp().optional;
2// → prop type: VueComponent | undefined
3vueComponentProp().nullable;
4// → prop type: VueComponent | null
5vueComponentProp().required;
6// → prop type: VueComponent
7vueComponentProp().withDefault('close-icon');
8// → prop type: VueComponent

ℹ️ Note:
The type VueComponent is defined to be object | string. It has to be so broad to allow Vue 2 and Vue 3 component options or instances. If you are able to narrow the type without pulling in heavy dependencies, please open an issue or pull request!

anyProp<T>(validator?: Validator)

Allows any type. No built-in runtime validation is performed by default.
Type parameter T can be used to restrict the type at compile time.

1anyProp().optional;
2// → prop type: any
3anyProp().nullable;
4// → prop type: any
5anyProp().required;
6// → prop type: any
7anyProp().withDefault('foo');
8// → prop type: any
9
10anyProp<string>().optional;
11// → prop type: string | undefined
12anyProp<string>().nullable;
13// → prop type: string | null
14anyProp<string>().required;
15// → prop type: string
16anyProp<string>().withDefault('foo');
17// → prop type: string

arrayProp<T>(validator?: Validator)

Allows any array. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type of the array items at compile time.

1arrayProp().optional;
2// → prop type: unknown[] | undefined
3arrayProp().nullable;
4// → prop type: unknown[] | null
5arrayProp().required;
6// → prop type: unknown[]
7arrayProp().withDefault(() => []);
8// → prop type: unknown[]
9
10arrayProp<string>().optional;
11// → prop type: string[] | undefined
12arrayProp<string>().nullable;
13// → prop type: string[] | null
14arrayProp<string>().required;
15// → prop type: string[]
16arrayProp<string>().withDefault(() => ['foo', 'bar']);
17// → prop type: string[]

objectProp<T>(validator?: Validator)

Allows any object. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type at compile time.

1objectProp().optional;
2// → prop type: object | undefined
3objectProp().nullable;
4// → prop type: object | null
5objectProp().required;
6// → prop type: object
7objectProp().withDefault(() => ({}));
8// → prop type: object
9
10interface User {
11  name: string;
12}
13
14objectProp<User>().optional;
15// → prop type: User | undefined
16objectProp<User>().nullable;
17// → prop type: User | null
18objectProp<User>().required;
19// → prop type: User
20objectProp<User>().withDefault(() => ({ name: 'John' }));
21// → prop type: User

functionProp<T>(validator?: Validator)

Allows any function. No further runtime validation is performed by default.
Type parameter T can be used to restrict the type to a specific function signature at compile time.

ℹ️ Note:
There is no .withDefault() function for this prop type.

1functionProp().optional;
2// → prop type: Function | undefined
3functionProp().nullable;
4// → prop type: Function | null
5functionProp().required;
6// → prop type: Function
7
8type MyFunc = (a: number, b: string) => boolean;
9
10functionProp<MyFunc>().optional;
11// → prop type: MyFunc | undefined
12functionProp<MyFunc>().nullable;
13// → prop type: MyFunc | null
14functionProp<MyFunc>().required;
15// → prop type: MyFunc

oneOfProp<T>(allowedValues: readonly any[], validator?: Validator)

Allows any of the specified allowed values (validated at runtime and compile time).
Type parameter T can be used to adjust the inferred type at compile time, this is usually not necessary.

ℹ️ Note:
Proper type checking is only possible if the allowed values are readonly, usually through as const.

1oneOfProp(['foo', 'bar'] as const).optional;
2// → prop type: 'foo' | 'bar' | undefined
3oneOfProp(['foo', 'bar'] as const).nullable;
4// → prop type: 'foo' | 'bar' | null
5oneOfProp(['foo', 'bar'] as const).required;
6// → prop type: 'foo' | 'bar'
7oneOfProp(['foo', 'bar'] as const).withDefault('foo');
8// → prop type: 'foo' | 'bar'

oneOfObjectKeysProp<T>(object: object, validator?: Validator)

Allows any of the keys of the specified object (validated at runtime and compile time).
Type parameter T can be used to adjust the inferred type at compile time, this is usually not necessary.

1oneOfObjectKeysProp({ foo: 1, bar: 2 }).optional;
2// → prop type: 'foo' | 'bar' | undefined
3oneOfObjectKeysProp({ foo: 1, bar: 2 }).nullable;
4// → prop type: 'foo' | 'bar' | null
5oneOfObjectKeysProp({ foo: 1, bar: 2 }).required;
6// → prop type: 'foo' | 'bar'
7oneOfObjectKeysProp({ foo: 1, bar: 2 }).withDefault('foo');
8// → prop type: 'foo' | 'bar'

oneOfTypesProp<T>(type: PropType<T>, validator?: Validator)

Allows any of the passed constructor types (validated at runtime).
Type parameter T has to be used to adjust the type at compile time.

1oneOfTypesProp<number | string>([Number, String]).optional;
2// → prop type: string | number | undefined
3oneOfTypesProp<number | string>([Number, String]).nullable;
4// → prop type: string | number | null
5oneOfTypesProp<number | string>([Number, String]).required;
6// → prop type: string | number
7oneOfTypesProp<number | string>([Number, String]).withDefault(42);
8// → prop type: string | number

instanceOfProp<T>(parent: T, validator?: Validator)

Allows instances of the given constructor (validated at runtime and compile time).
Type parameter T can be used to adjust the inferred type at compile time.

1instanceOfProp(Date).optional;
2// → prop type: Date | undefined
3instanceOfProp(Date).nullable;
4// → prop type: Date | null
5instanceOfProp(Date).required;
6// → prop type: Date
7instanceOfProp(Date).withDefault(() => new Date());
8// → prop type: Date

Contributing

Please see CONTRIBUTING.md.

Similar packages

• vue-types, which this project took heavy inspiration from
• vue-prop
• vuept

License

Unless otherwise noted, all source code is licensed under the MIT License.
Copyright (c) 2022 Flo Edelmann