Awesome
type-predicates-generator
type-predicates-generator is a tool to automatically generate type predicates functions from type definitions.
Requires TypeScript v4.4.4 or higher.
Getting started
It is available directly from npx.
$ npx type-predicates-generator -f 'types/**/*/ts' -o predicates.ts -a
$ npx type-predicates-generator -f 'types/**/*/ts' -o predicates.ts -a -w # watch mode
or install locally.
$ yarn add -D type-predicates-generator # or npm
$ yarn run type-predicates-generator 'types/**/*/ts' -o predicates.ts -a
When executed, it will generate a type predicate functions that does a runtime check for type definitions exported from files that match the specified glob pattern(types/**/*.ts).
Examples of the automatically generated functions can be found at example/type-predicates.ts.
Usage
Basic Usage: make non-type-safe API calls type-safe.
Basic usage of this tool is to safely type values received from the outside world, such as through API communication.
import type { Task } from 'path/to/your-declare'
import { assertIsTask } from 'path/to/type-predicates' // generated function
fetch("path/to/api/task").then(async (data) => {
- const json: Task = await data.json() // non-type-safe
+ const json = await data.json()
+ assertIsTask(json) // Check with generated function and throw an exception if the data is not valid
json /* :Task */
})
By passing the assertIs${typeName} function, you can raise an exception if the data is incorrect.
Since there is no mechanism in typescript to check whether the implementation of type predicates functions is correct, manually defined type predicates may be implemented incorrectly, or the type definition may be changed later and the implementation becomes inappropriate, etc.
These problems can be avoided by generating type predicates functions mechanically.
Working with auto-generated type definitions
Type definitions generated by tools such as openapi-generator tend to be huge. It is possible to re-export only the type declarations you want to use.
export { Category } from "../typescript-axios/api"
If typescript-axios/api is not included in the target glob, only Category type can be generated.
Whether to check all array elements
Runtime type checking tends to affect performance. You can specify whether to check only the first element of each array or to check all elements properly. The default value is specified by the cli option.
import { isArrStr } from "path/to/type-predicates"
isArrStr(["hello", "world"], "all") // check all element
isArrStr(["hello", "world"], "first") // only check first element
Cli Options
| Option | Default | Description |
|---|---|---|
| -p, --project | tsconfig.json | Path for project tsconfig.json |
| -f, --file-glob | **/*.ts | file glob pattern that original types are defined for generated. |
| -o, --output | type-predicates.ts | output file path |
| -b, --base-path | ./ | project base path |
| -a, --asserts | false | generate assert functions or not |
| -w, --watch | false | watch or not |
| --default-array-check-option | all | how to check child element type. 'all' or 'first' |
| -c, --comment | false | generate JSDoc comments or not |
| --whitelist | false | not allow non listed properties |
Unsupported
Basically, only JSON serializable data structures are supported. In other words, functions, data structures with circular references, Promise, etc. are not supported.
However, there is no restriction on the type operation, and it can be generated from complex types using advanced types such as Intersection Types, Union Types, Mapped Types and so on.
License
MIT
Contributing
Welcome.
$ yarn install
$ yarn patch # fix types compiler API