@amritk/generate-parsers

Programmatic API for generating TypeScript parsers and type definitions from JSON Schemas.

Overview

@amritk/generate-parsers is the core code-generation engine behind mjst. Given a JSON Schema (Draft 2020-12), it produces an array of { filename, content } records — TypeScript type definitions plus optional runtime parser functions that validate and coerce unknown input.

If you want a CLI, use @amritk/mjst. Use this package directly when you want to embed schema-to-TypeScript generation inside another build step or tool.

Installation

npm install @amritk/generate-parsers
# or
pnpm add @amritk/generate-parsers
# or
yarn add @amritk/generate-parsers
# or
bun add @amritk/generate-parsers

Usage

import { buildSchema } from '@amritk/generate-parsers'
import type { JSONSchema } from 'json-schema-typed/draft-2020-12'

const schema: JSONSchema = {
  type: 'object',
  properties: {
    info: { $ref: '#/$defs/info' },
  },
  $defs: {
    info: {
      type: 'object',
      properties: { title: { type: 'string' } },
    },
  },
}

const files = await buildSchema(schema, 'Document')
// → [{ filename: 'document.ts', content: '...' }, { filename: 'info.ts', content: '...' }, ...]

Each entry in files is a GeneratedFile:

type GeneratedFile = {
  filename: string
  content: string
}

Write them to disk however you like.

API

buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?)

| Parameter | Type | Description | |:---|:---|:---| | rootSchema | JSONSchema | The root schema to traverse. $ref and $dynamicRef are resolved recursively. | | rootTypeName | string | Name used for the root type (e.g. "Document"). | | extensions | SchemaExtensions (optional) | Map of definition name → extra optional properties to merge in before generation. | | typesOnly | boolean (optional) | When true, only emit .ts type definitions — skip parser functions and runtime helpers. | | logWarnings | boolean (optional) | When true, generated parsers emit a console.warn for every input key not declared in the schema's properties. | | strict | boolean (optional) | When true, generated parsers throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. |

Returns: Promise<GeneratedFile[]>.

Options

| | Property | CLI Flag | Type | Required | Default | Description | |:---:|:---|:---|:---:|:---:|:---:|:---| | 🏷️ | typesOnly | — | boolean | — | false | Generate only TypeScript type definitions without parser functions. Runtime helper files (validators, isObject) are also omitted since they are only needed for parsers. | | ⚠️ | logWarnings | — | boolean | — | false | Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime. | | 🚫 | strict | — | boolean | — | false | Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. Unknown extra keys are still allowed. |

The generator handles:

• $ref and $dynamicRef resolution, including JSON Schema 2020-12 $dynamicAnchor
• Discriminated and non-discriminated unions (oneOf / anyOf)
• Enums and const values
• Nested objects, arrays, records, and tuples
• Pattern-based default values

Related packages

• @amritk/mjst — CLI wrapping this generator
• @amritk/generate-validators — predicate-style validators (sister package)
• @amritk/generate-markdown — markdown documentation generator
• @amritk/helpers — shared schema-traversal utilities

License

MIT