Schema-nozzle NPM

schema-nozzle

schema-nozzle generates json-schema in the TypeScript interface, type alias, class and enum.

Why schema-nozzle?

json-schema good solution for that validate request, response DTO
share code documentation with jsdoc or typedoc
swagger.io documentation from json-schema using @fastify/swagger, Don't need any effort!

Strict JSON data validations are need many effort. You can reduce effort using schema-nozzle and Feel free 🤩!

Getting Started

npx schema-nozzle init
npx schema-nozzle refresh

You can create configuration and list file using init command. And you can run refresh command, schema-nozzle generate json-schema from interface, type alias, class and enum.

You can see this mechanics!

demo

Installation

npm install schema-nozzle --save-dev

How it works?

schema-nozzle using TypeScript Compiler API. So schema-nozzle exactly know interface, type alias, class and enum.

graph LR

INP_TI[interface] --> SN[schema-nozzle]
INP_TT[type alias] --> SN[schema-nozzle]
INP_TC[class] --> SN[schema-nozzle]
INP_TE[enum] --> SN[schema-nozzle]
SN --> |exported| DB[db.json]
SN --> |not exported| IG[ignored]

schema-nozzle generate json-schema using ts-json-schema-generator
.nozzlefiles file follow gitignore spec.
only generated exported interface, type alias, class and enum

Here is real example,

TypeScript interface

This is input source file.

export interface I18nDto {
  /** i18n resource id */
  id: string;

  /**
   * iso639-1 language code
   *
   * @minLength 2
   * @maxLength 5
   * */
  language: string;

  /** i18n resource content */
  content: string;

  /**
   * i18n resource use on
   *
   * @minItems 1
   * @maxItems 10
   * */
  used?: string[];
}

json-schema

This is output json-schema.

{
  "I18nDto": {
    "id": "I18nDto",
    "filePath": "I18nDto.ts",
    "dependency": {
      "import": {
        "name": "I18nDto",
        "from": []
      },
      "export": {
        "name": "I18nDto",
        "to": [
          "IForeginStudentDto33",
          "IForeginStudentDto",
          "IReqReadStudentQuerystring",
          "IStudentDto",
          "IProfessorDto"
        ]
      }
    },
    "schema": {
      "$id": "I18nDto",
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "i18n resource id"
        },
        "language": {
          "type": "string",
          "description": "iso639-1 language code",
          "minLength": 2,
          "maxLength": 5
        },
        "content": {
          "type": "string",
          "description": "i18n resource content"
        },
        "used": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "i18n resource use on",
          "minItems": 1,
          "maxItems": 10
        }
      },
      "required": ["id", "language", "content"],
      "additionalProperties": false
    }
  }
}

You can use this schema like that,

// use ajv schema store
import Ajv from 'ajv';

const ajv = new Ajv();
const db = JSON.parse((await fs.readFile('db.json')).toString());
Object.values(db).forEach((item) => ajv.addSchema(item.schema));

const validator = ajv.compile({ $ref: 'I18nDto' });

// don't use schema store
import Ajv from 'ajv';

const ajv = new Ajv();
const db = JSON.parse((await fs.readFile('db.json')).toString());
const validator = ajv.compile(db['I18nDto'].schema);

Usage

You can see help from --help option.

# display help for each commands
npx schema-nozzle --help

# display help for add commands
npx schema-nozzle add --help

# display help for del commands
npx schema-nozzle del --help

# display help for refresh commands
npx schema-nozzle refresh --help

# display help for truncate commands
npx schema-nozzle truncate --help

# display help for watch commands
npx schema-nozzle watch --help

Also you can see detail option here.

Performance

0.19.0 version enhance performance. Now remove pain point from mass schema generation.

benchmark

This image is result of 388 schema extraction using M1 macbook pro(16GB RAM, 1TB SSD, 10core). schema-nozzle spent only 6.14 second! 🙌 🙆

Example using fastify.js

A complete example of using schema-nozzle to create a swagger.io document and use json-schema to process input-output value verification can be found at Ma-eum. See the example of how DTO type declaration handles swagger.io document creation, json-schema creation, and typedoc document creation all at once!

fastify with schema-nozzle example

Recommand option

extraTags and additionalProperties options enable in .nozzlerc

{
  "tsconfig": "./tsconfig.json",
  "list-file": "./.nozzlefiles",
  "cli-logo": true,
  "generatorOption": {
    "additionalProperties": true,
    "extraTags": ["example"]
  }
}

additionalProperties option permit additional properties in request object. And extraTags option can add to example field for swagger.io document.