type-predicates-generator

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