azu / create-validator-ts

Create JSON Schema validator from TypeScript.

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

Structure

.
└── 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:

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

api-types.validator.ts (generated):

// @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

"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: ["<ajv-plugin-extra-tag>"] // 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

Can not parse new TypeScript syntax

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<T>
  • 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