create-validator-ts

Create JSON Schema validator from TypeScript.

Motivation

- Generate JSON Schema Validator functions from TypeScript code
- Make TypeScript the Single source of truth

$3

``
.
└── src/
├── hello/
│ ├── api-types.ts
│ ├── api-types.validator.ts <- Generated
│ └── index.ts
└── status/
├── api-types.ts
├── api-types.validator.ts <- Generated
└── index.ts
`

Install

Install with npm:

npm install create-validator-ts

Usage


Usage
$ create-validator-ts [file|glob*]

Options
--watch [Boolean] If set the flag, start watch mode
--check [Boolean] If set the flag, start test mode
--cwd [Path:String] current working directory
--tsconfigFilePath [Path:String] path to tsconfig.json
--generatorScript [Path:String] A JavaScript file path that customize validator code generator
--verbose [Boolean] If set the flag, show progressing logs

ts-json-schema-generator options
--sortProps [Boolean] Enable sortProps
--no-sortProps
--strictTuples [Boolean] Enable strictTuples
--no-strictTuples
--encodeRefs [Boolean] Enable encodeRefs
--no-encodeRefs
--skipTypeCheck [Boolean] Enable skipTypeCheck. true by default
--no-skipTypeCheck
--additionalProperties [Boolean] Enable additionalProperties. false by default
--no-additionalProperties


Examples
$ create-validator-ts "src/**/api-types.ts"
# use cache
$ create-validator-ts --cache "src/**/api-types.ts"
# custom tsconfig.json
$ create-validator-ts "src/**/api-types.ts" --tsconfigFilePath ./tsconfig.app.json
# custom validator code
$ create-validator-ts "src/**/api-types.ts" --generatorScript ./custom.js

Example

You can generate validator code via following command

$ create-validator-ts "src/**/api-types.ts"

Default validator require ajv, and you need to install ajv into your project.

$ npm install ajv

Structure:

`
.
├ tsconfig.json
└── src/
└─── api/
├── api-types.ts
└─── api-types.validator.ts <- Generated
`

api-types.ts:

`ts
// Example api-types
// GET /api
export type GetAPIRequestQuery = {
id: string;
};
export type GetAPIResponseBody = {
ok: boolean;
};
`

api-types.validator.ts (generated):

`ts
// @ts-nocheck
// eslint-disable
// This file is generated by create-validator-ts
import Ajv from 'ajv';
import * as apiTypes from './api-types';

const SCHEMA = {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"GetAPIRequestQuery": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
},
"GetAPIResponseBody": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"additionalProperties": false
}
}
};
const ajv = new Ajv({ removeAdditional: true }).addSchema(SCHEMA, "SCHEMA");
export function validateGetAPIRequestQuery(payload: unknown): apiTypes.GetAPIRequestQuery {
if (!isGetAPIRequestQuery(payload)) {
const error = new Error('invalid payload: GetAPIRequestQuery');
error.name = "ValidatorError";
throw error;
}
return payload;
}

export function isGetAPIRequestQuery(payload: unknown): payload is apiTypes.GetAPIRequestQuery {
/ Schema is defined in {@link SCHEMA.definitions.GetAPIRequestQuery } /
const ajvValidate = ajv.compile({ "$ref": "SCHEMA#/definitions/GetAPIRequestQuery" });
return ajvValidate(payload);
}

export function validateGetAPIResponseBody(payload: unknown): apiTypes.GetAPIResponseBody {
if (!isGetAPIResponseBody(payload)) {
const error = new Error('invalid payload: GetAPIResponseBody');
error.name = "ValidatorError";
throw error;
}
return payload;
}

export function isGetAPIResponseBody(payload: unknown): payload is apiTypes.GetAPIResponseBody {
/ Schema is defined in {@link SCHEMA.definitions.GetAPIResponseBody } /
const ajvValidate = ajv.compile({ "$ref": "SCHEMA#/definitions/GetAPIResponseBody" });
return ajvValidate(payload);
}
`

Check generated code

When You can check if your generated codes are match with api-types.ts, you can run it via --check flag.

$ create-validator-ts "src/**/api-types.ts"
# $? → 0 or 1

It is useful for testing on CI.

Custom Validator

You can create custom validator using --generatorScript flag.

$ create-validator-ts "src/**/api-types.ts" --generatorScript ./custom.js

custom.js

`js
"use strict";
const path = require("path");
const generator = ({ apiFilePath, apiFileCode, schema }) => {
const apiFileName = path.basename(apiFilePath, ".ts");
const isExportedTypeInApiTypes = (apiName) => {
return (apiFileCode.includes(export type ${apiName} =) ||
apiFileCode.includes(export interface ${apiName} {));
};
const banner = // @ts-nocheck
// eslint-disable
// This file is generated by create-validator-ts
import Ajv from 'ajv';
import logger from 'logger';
import * as apiTypes from './${apiFileName}';
;
// define SCHEMA to top, and we can refer it as "SCHEMA".
// Note: { "$ref": "SCHEMA#/definitions/${apiName}" }
const schemaDefinition = const SCHEMA = ${JSON.stringify(schema, null, 4)};
const ajv = new Ajv({ removeAdditional: true }).addSchema(SCHEMA, "SCHEMA");;
const code = Object.entries(schema.definitions || {})
.filter(([apiName]) => {
return isExportedTypeInApiTypes(apiName);
})
.map(([apiName, _schema]) => {
return export function validate${apiName}(payload: unknown): apiTypes.${apiName} {
if (!is${apiName}(payload)) {
const error = new Error('invalid payload: ${apiName}');
error.name = "ValidatorError";
throw error;
}
return payload;
}

export function is${apiName}(payload: unknown): payload is apiTypes.${apiName} {
/ Schema is defined in {@link SCHEMA.definitions.${apiName} } /
const ajvValidate = ajv.compile({ "$ref": "SCHEMA#/definitions/${apiName}" });
return ajvValidate(payload);
};
})
.join("\n\n");
return ${banner}
${schemaDefinition}
${code}
;
};
exports.generator = generator;
exports.generatorOptions = {
extraTags: [""] // optional
};
`

Ignore generated Code

If you have used Prettier, you should add *.validator.ts to .prettierignore

`
*.validator.ts
`

- Ignoring Code · Prettier

Compares

- create-validator-ts
- It generate TypeScript validator from TypeScript types
- ts-to-zod uses same approach
- OpenAPI
- It generate TypeScript validator from Schema file
- TypeScript Validation library like Zod
- Is allow to share TypeScript code and types, but it need to use builder function

FAQ

$3

It related to vega/ts-json-schema-generator.
Please report the issue to vega/ts-json-schema-generator.

Changelog

See Releases page.

Running tests

Install devDependencies and Run npm test:

npm test

Contributing

Pull requests and stars are always welcome.

For bugs and feature requests, please create an issue.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Author

- azu: GitHub, Twitter

License

MIT © azu

Prior art

- ForbesLindesay/typescript-json-validator

Differences:

- create-validator-ts support multiple types in a single file
- create-validator-ts support more TypeScript that includes Utility types like Pick
- typescript-json-validator uses YousefED/typescript-json-schema
- create-validator-ts uses vega/ts-json-schema-generator
- See also Future of schema generators · Issue #101 · vega/ts-json-schema-generator
- create-validator-ts is minimal and support customization of validation code using --generatorScript`