{"id":14973786,"url":"https://github.com/floedelmann/vue-ts-types","last_synced_at":"2025-04-07T14:15:02.873Z","repository":{"id":37088021,"uuid":"486774121","full_name":"FloEdelmann/vue-ts-types","owner":"FloEdelmann","description":"Lightweight TypeScript-first Vue prop type definitions","archived":false,"fork":false,"pushed_at":"2024-11-19T14:32:56.000Z","size":2046,"stargazers_count":8,"open_issues_count":6,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-24T19:55:57.410Z","etag":null,"topics":["hacktoberfest","prop-types","props","proptype-validators","proptypes","typescript","vue","vue2","vue3","vuejs","vuejs2","vuejs3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FloEdelmann.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-28T23:10:57.000Z","updated_at":"2024-11-19T14:35:03.000Z","dependencies_parsed_at":"2024-02-09T14:29:54.037Z","dependency_job_id":"403bd14a-fb8b-4341-ae23-594e504cd3d7","html_url":"https://github.com/FloEdelmann/vue-ts-types","commit_stats":{"total_commits":715,"total_committers":6,"mean_commits":"119.16666666666667","dds":"0.16503496503496506","last_synced_commit":"9b7a7486c2fb6fac28fd58c676c1b3b7f23a43b4"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloEdelmann%2Fvue-ts-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloEdelmann%2Fvue-ts-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloEdelmann%2Fvue-ts-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FloEdelmann%2Fvue-ts-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FloEdelmann","download_url":"https://codeload.github.com/FloEdelmann/vue-ts-types/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247666015,"owners_count":20975788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","prop-types","props","proptype-validators","proptypes","typescript","vue","vue2","vue3","vuejs","vuejs2","vuejs3"],"created_at":"2024-09-24T13:49:24.615Z","updated_at":"2025-04-07T14:15:02.819Z","avatar_url":"https://github.com/FloEdelmann.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vue-ts-types\n\n\u003e Lightweight TypeScript-first [Vue prop type](https://vuejs.org/guide/components/props.html#prop-validation) definitions\n\n[![npm][badge-npm]][npm] [![GitHub][badge-github]][github] [![GitHub tests workflow][badge-actions]][actions]\n\n[npm]: https://www.npmjs.com/package/vue-ts-types\n[github]: https://github.com/FloEdelmann/vue-ts-types\n[actions]: https://github.com/FloEdelmann/vue-ts-types/actions/workflows/test.yaml?query=branch%3Amain\n[badge-npm]: https://img.shields.io/npm/v/vue-ts-types?logo=npm\u0026logoColor=white\u0026color=red\n[badge-github]: https://img.shields.io/github/package-json/v/FloEdelmann/vue-ts-types?logo=github\u0026color=blue\n[badge-actions]: https://img.shields.io/github/actions/workflow/status/FloEdelmann/vue-ts-types/test.yaml?logo=github\u0026label=Tests\n\n## Example\n\n```ts\nimport { defineComponent } from 'vue';\nimport {\n  arrayProp,\n  booleanProp,\n  functionProp,\n  isPositive,\n  numberProp,\n  oneOfProp,\n  stringProp,\n} from 'vue-ts-types';\n\ndefineComponent({\n  props: {\n    disabled: booleanProp().withDefault(false),\n    // resulting prop type: boolean\n\n    title: stringProp().optional,\n    // resulting prop type: string | undefined\n\n    description: stringProp().nullable,\n    // resulting prop type: string | null\n\n    items: arrayProp\u003cstring\u003e().required,\n    // resulting prop type: string[]\n\n    callback: functionProp\u003c() =\u003e void\u003e().optional,\n    // resulting prop type: (() =\u003e void) | undefined\n\n    color: oneOfProp(['red', 'green', 'blue'] as const).withDefault('red'),\n    // resulting prop type: 'red' | 'green' | 'blue'\n\n    timeout: numberProp(isPositive).required,\n    // resulting prop type: number\n  },\n});\n```\n\n## Motivation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProp declarations are verbose\u003c/strong\u003e\u003c/summary\u003e\n\nDeclaring props is quite verbose, especially if you are using TypeScript and want to annotate more complex types (with `PropType`).\n\n```ts\noptions: {\n  type: Object as PropType\u003cOptions\u003e,\n  required: true,\n}\n\n// with vue-ts-types:\noptions: objectProp\u003cOptions\u003e().required\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAnnotating optional complex props is error-prone\u003c/strong\u003e\u003c/summary\u003e\n\nIt's easy to forget using a union type with `undefined` or `null` when the prop is not required.\n\n```ts\noptions: {\n  type: Object as PropType\u003cOptions\u003e, // wrong, it should be `Options | undefined`\n  required: false,\n}\n\n// with vue-ts-types:\noptions: objectProp\u003cOptions\u003e().optional // automatically typed as `Options | undefined`\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSpecifying both \u003ccode\u003edefault\u003c/code\u003e and \u003ccode\u003erequired\u003c/code\u003e can be contradictory\u003c/strong\u003e\u003c/summary\u003e\n\nBy specifying a prop's default value, the prop is automatically optional, even when `required` is set to `true`. See also the [`vue/no-required-prop-with-default` ESLint rule](https://eslint.vuejs.org/rules/no-required-prop-with-default.html).\n\n```ts\ndisabled: {\n  type: Boolean,\n  required: true,\n  default: false, // contradictory to `required: true`\n}\n\n// with vue-ts-types:\ndisabled: booleanProp().required // either required without default\ndisabled: booleanProp().withDefault(false) // or optional with default\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCustom validation errors are not helpful\u003c/strong\u003e\u003c/summary\u003e\n\nSince prop validators return only a boolean validation result, the reason why a value failed to validate is not printed in the console error.\n\n```ts\nage: {\n  type: Number,\n  required: true,\n  validator: (age: unknown) =\u003e {\n    return typeof age === 'number' \u0026\u0026 Number.isInteger(age) \u0026\u0026 age \u003e= 18\n  },\n}\n\n// with vue-ts-types:\nage: integerProp((age: unknown) =\u003e {\n  if (typeof age !== 'number' || age \u003c 18) {\n    return 'age should be a number of at least 18'\n  }\n  return undefined\n}).required\n```\n\n\u003c/details\u003e\n\n## Installation\n\n```bash\nnpm install vue-ts-types\n```\n\n`vue-ts-types` has no dependencies and is tested to be compatible with [Vue.js](https://vuejs.org/) `v2.6`, `v2.7` and `v3.2`.\n\n## Usage\n\nEach of the prop functions returns an object with the following properties:\n\n- `.optional`: Use this to mark the prop as not required with a default value of `undefined`. Also includes `undefined` in the resulting prop type.\n- `.nullable`: Use this to mark the prop as not required with a default value of `null`. Also includes `null` in the resulting prop type.\n- `.required`: Use this to mark the prop as required without a default value.\n- `.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.\n\n\u003e ℹ️ **Note:**  \n\u003e Due to the way Vue props work, a prop's default value will only be used when passing `undefined`, not for `null`.  \n\u003e See [issue #3135 in vuejs/vue](https://github.com/vuejs/vue/issues/3135).\n\n### Custom validator functions\n\nCustom 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.\n\n```ts\nimport { numberProp } from 'vue-ts-types';\n\ntype Validator = (value: unknown) =\u003e string | undefined;\n\nconst isPositive: Validator = (value) =\u003e {\n  if (typeof value !== 'number' || value \u003c= 0 || Number.isNaN(value)) {\n    return 'value should be a positive number';\n  }\n  return undefined;\n};\n\nnumberProp(isPositive).optional;\n// → prop type: number | undefined\n```\n\nFor convenience, some common validator functions are included in the library and can be imported just like prop types:\n\n- `isNegative`: only allows negative numbers (`\u003c 0`)\n- `isPositive`: only allows positive numbers (`\u003e 0`)\n- `isNonNegative`: only allows non-negative numbers (`\u003e= 0`)\n- `isNonPositive`: only allows non-positive numbers (`\u003c= 0`)\n\n### `stringProp\u003cT\u003e(validator?: Validator)`\n\nAllows any string. No further runtime validation is performed by default.  \nType parameter `T` can be used to restrict the type at compile time with a union type. (Consider using [`oneOfProp`](#oneofproptallowedvalues-readonly-any-validator-validator) in this case.)\n\n```ts\nstringProp().optional;\n// → prop type: string | undefined\nstringProp().nullable;\n// → prop type: string | null\nstringProp().required;\n// → prop type: string\nstringProp().withDefault('foo');\n// → prop type: string\n\ntype Foo = 'a' | 'b' | 'c';\n\nstringProp\u003cFoo\u003e().optional;\n// → prop type: Foo | undefined\nstringProp\u003cFoo\u003e().nullable;\n// → prop type: Foo | null\nstringProp\u003cFoo\u003e().required;\n// → prop type: Foo\nstringProp\u003cFoo\u003e().withDefault('a');\n// → prop type: Foo\n```\n\n### `booleanProp(validator?: Validator)`\n\nAllows any boolean (validated at runtime and compile time).\n\n```ts\nbooleanProp().optional;\n// → prop type: boolean | undefined\nbooleanProp().nullable;\n// → prop type: boolean | null\nbooleanProp().required;\n// → prop type: boolean\nbooleanProp().withDefault(false);\n// → prop type: boolean\n```\n\n### `numberProp\u003cT\u003e(validator?: Validator)`\n\nAllows any number (validated at runtime and compile time).\nType parameter `T` can be used to restrict the type at compile time with a union type. (Consider using [`oneOfProp`](#oneofproptallowedvalues-readonly-any-validator-validator) in this case.)\n\n```ts\nnumberProp().optional;\n// → prop type: number | undefined\nnumberProp().nullable;\n// → prop type: number | null\nnumberProp().required;\n// → prop type: number\nnumberProp().withDefault(3.1415);\n// → prop type: number\n\ntype Foo = 1 | 2 | 3;\n\nnumberProp\u003cFoo\u003e().optional;\n// → prop type: Foo | undefined\nnumberProp\u003cFoo\u003e().nullable;\n// → prop type: Foo | null\nnumberProp\u003cFoo\u003e().required;\n// → prop type: Foo\nnumberProp\u003cFoo\u003e().withDefault(1);\n// → prop type: Foo\n```\n\n### `integerProp(validator?: Validator)`\n\nAllows any integer (validated at runtime).\n\n```ts\nintegerProp().optional;\n// → prop type: number | undefined\nintegerProp().nullable;\n// → prop type: number | null\nintegerProp().required;\n// → prop type: number\nintegerProp().withDefault(42);\n// → prop type: number\n```\n\n### `dateProp(validator?: Validator)`\n\nAllows any `Date` object (validated at runtime and compile time).\n\n```ts\ndateProp().optional;\n// → prop type: Date | undefined\ndateProp().nullable;\n// → prop type: Date | null\ndateProp().required;\n// → prop type: Date\ndateProp().withDefault(() =\u003e new Date());\n// → prop type: Date\n```\n\n### `symbolProp(validator?: Validator)`\n\nAllows any symbol (validated at runtime and compile time).\n\n```ts\nsymbolProp().optional;\n// → prop type: symbol | undefined\nsymbolProp().nullable;\n// → prop type: symbol | null\nsymbolProp().required;\n// → prop type: symbol\nsymbolProp().withDefault(Symbol('foo'));\n// → prop type: symbol\n```\n\n### `vueComponentProp(validator?: Validator)`\n\nAllows any Vue component instance, name or options object. No built-in runtime validation is performed by default.\n\n```ts\nvueComponentProp().optional;\n// → prop type: VueComponent | undefined\nvueComponentProp().nullable;\n// → prop type: VueComponent | null\nvueComponentProp().required;\n// → prop type: VueComponent\nvueComponentProp().withDefault('close-icon');\n// → prop type: VueComponent\n```\n\n\u003e ℹ️ **Note:**  \n\u003e 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.\n\u003e If you are able to narrow the type without pulling in heavy dependencies, please open an issue or pull request!\n\n### `anyProp\u003cT\u003e(validator?: Validator)`\n\nAllows any type. No built-in runtime validation is performed by default.  \nType parameter `T` can be used to restrict the type at compile time.\n\n```ts\nanyProp().optional;\n// → prop type: any\nanyProp().nullable;\n// → prop type: any\nanyProp().required;\n// → prop type: any\nanyProp().withDefault('foo');\n// → prop type: any\n\nanyProp\u003cstring\u003e().optional;\n// → prop type: string | undefined\nanyProp\u003cstring\u003e().nullable;\n// → prop type: string | null\nanyProp\u003cstring\u003e().required;\n// → prop type: string\nanyProp\u003cstring\u003e().withDefault('foo');\n// → prop type: string\n```\n\n### `arrayProp\u003cT\u003e(validator?: Validator)`\n\nAllows any array. No further runtime validation is performed by default.  \nType parameter `T` can be used to restrict the type of the array items at compile time.\n\n```ts\narrayProp().optional;\n// → prop type: unknown[] | undefined\narrayProp().nullable;\n// → prop type: unknown[] | null\narrayProp().required;\n// → prop type: unknown[]\narrayProp().withDefault(() =\u003e []);\n// → prop type: unknown[]\n\narrayProp\u003cstring\u003e().optional;\n// → prop type: string[] | undefined\narrayProp\u003cstring\u003e().nullable;\n// → prop type: string[] | null\narrayProp\u003cstring\u003e().required;\n// → prop type: string[]\narrayProp\u003cstring\u003e().withDefault(() =\u003e ['foo', 'bar']);\n// → prop type: string[]\n```\n\n### `objectProp\u003cT\u003e(validator?: Validator)`\n\nAllows any object. No further runtime validation is performed by default.  \nType parameter `T` can be used to restrict the type at compile time.\n\n```ts\nobjectProp().optional;\n// → prop type: object | undefined\nobjectProp().nullable;\n// → prop type: object | null\nobjectProp().required;\n// → prop type: object\nobjectProp().withDefault(() =\u003e ({}));\n// → prop type: object\n\ninterface User {\n  name: string;\n}\n\nobjectProp\u003cUser\u003e().optional;\n// → prop type: User | undefined\nobjectProp\u003cUser\u003e().nullable;\n// → prop type: User | null\nobjectProp\u003cUser\u003e().required;\n// → prop type: User\nobjectProp\u003cUser\u003e().withDefault(() =\u003e ({ name: 'John' }));\n// → prop type: User\n```\n\n### `functionProp\u003cT\u003e(validator?: Validator)`\n\nAllows any function. No further runtime validation is performed by default.  \nType parameter `T` can be used to restrict the type to a specific function signature at compile time.\n\n\u003e ℹ️ **Note:**  \n\u003e There is no `.withDefault()` function for this prop type.\n\n```ts\nfunctionProp().optional;\n// → prop type: Function | undefined\nfunctionProp().nullable;\n// → prop type: Function | null\nfunctionProp().required;\n// → prop type: Function\n\ntype MyFunc = (a: number, b: string) =\u003e boolean;\n\nfunctionProp\u003cMyFunc\u003e().optional;\n// → prop type: MyFunc | undefined\nfunctionProp\u003cMyFunc\u003e().nullable;\n// → prop type: MyFunc | null\nfunctionProp\u003cMyFunc\u003e().required;\n// → prop type: MyFunc\n```\n\n### `oneOfProp\u003cT\u003e(allowedValues: readonly any[], validator?: Validator)`\n\nAllows any of the specified allowed values (validated at runtime and compile time).  \nType parameter `T` can be used to adjust the inferred type at compile time, this is usually not necessary.\n\n\u003e ℹ️ **Note:**  \n\u003e Proper type checking is only possible if the allowed values are readonly, usually through `as const`.\n\n```ts\noneOfProp(['foo', 'bar'] as const).optional;\n// → prop type: 'foo' | 'bar' | undefined\noneOfProp(['foo', 'bar'] as const).nullable;\n// → prop type: 'foo' | 'bar' | null\noneOfProp(['foo', 'bar'] as const).required;\n// → prop type: 'foo' | 'bar'\noneOfProp(['foo', 'bar'] as const).withDefault('foo');\n// → prop type: 'foo' | 'bar'\n```\n\n### `oneOfObjectKeysProp\u003cT\u003e(object: object, validator?: Validator)`\n\nAllows any of the keys of the specified object (validated at runtime and compile time).  \nType parameter `T` can be used to adjust the inferred type at compile time, this is usually not necessary.\n\n```ts\noneOfObjectKeysProp({ foo: 1, bar: 2 }).optional;\n// → prop type: 'foo' | 'bar' | undefined\noneOfObjectKeysProp({ foo: 1, bar: 2 }).nullable;\n// → prop type: 'foo' | 'bar' | null\noneOfObjectKeysProp({ foo: 1, bar: 2 }).required;\n// → prop type: 'foo' | 'bar'\noneOfObjectKeysProp({ foo: 1, bar: 2 }).withDefault('foo');\n// → prop type: 'foo' | 'bar'\n```\n\n### `oneOfTypesProp\u003cT\u003e(type: PropType\u003cT\u003e, validator?: Validator)`\n\nAllows any of the passed constructor types (validated at runtime).  \nType parameter `T` has to be used to adjust the type at compile time.\n\n```ts\noneOfTypesProp\u003cnumber | string\u003e([Number, String]).optional;\n// → prop type: string | number | undefined\noneOfTypesProp\u003cnumber | string\u003e([Number, String]).nullable;\n// → prop type: string | number | null\noneOfTypesProp\u003cnumber | string\u003e([Number, String]).required;\n// → prop type: string | number\noneOfTypesProp\u003cnumber | string\u003e([Number, String]).withDefault(42);\n// → prop type: string | number\n```\n\n### `instanceOfProp\u003cT\u003e(parent: T, validator?: Validator)`\n\nAllows instances of the given constructor (validated at runtime and compile time).  \nType parameter `T` can be used to adjust the inferred type at compile time.\n\n```ts\ninstanceOfProp(Date).optional;\n// → prop type: Date | undefined\ninstanceOfProp(Date).nullable;\n// → prop type: Date | null\ninstanceOfProp(Date).required;\n// → prop type: Date\ninstanceOfProp(Date).withDefault(() =\u003e new Date());\n// → prop type: Date\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Similar packages\n\n- [vue-types](https://www.npmjs.com/package/vue-types/), which this project took heavy inspiration from\n- [vue-prop](https://www.npmjs.com/package/vue-prop)\n- [vuept](https://www.npmjs.com/package/vuept)\n\n## License\n\nUnless otherwise noted, all source code is licensed under the MIT License.  \nCopyright (c) 2022 Flo Edelmann\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloedelmann%2Fvue-ts-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloedelmann%2Fvue-ts-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloedelmann%2Fvue-ts-types/lists"}