@amritk/generate-parsers 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+<div align="center">
+
+# @amritk/generate-parsers
+
+**Programmatic API for generating TypeScript parsers and type definitions from JSON Schemas.**
+
+![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square)&nbsp;
+![version](https://img.shields.io/badge/version-v0.1.0-6366f1?style=flat-square&logo=npm&logoColor=white)&nbsp;
+![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)&nbsp;
+![JSON Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-f97316?style=flat-square)&nbsp;
+![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white)&nbsp;
+![vibe coded](https://img.shields.io/badge/vibe%20coded-84%25-a855f7?style=flat-square)
+
+</div>
+
+---
+
+## Overview
+
+`@amritk/generate-parsers` is the core code-generation engine behind [mjst](../../README.md). 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`](../cli). Use this package directly when you want to embed schema-to-TypeScript generation inside another build step or tool.
+
+---
+
+## Installation
+
+```bash
+npm install @amritk/generate-parsers
+# or
+pnpm add @amritk/generate-parsers
+# or
+yarn add @amritk/generate-parsers
+# or
+bun add @amritk/generate-parsers
+```
+
+---
+
+## Usage
+
+```ts
+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`:
+
+```ts
+type GeneratedFile = {
+  filename: string
+  content: string
+}
+```
+
+Write them to disk however you like.
+
+---
+
+## API
+
+### `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?)`
+
+| 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. |
+
+Returns: `Promise<GeneratedFile[]>`.
+
+---
+
+## Options
+
+<!-- config-table-start -->
+| | 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. |
+<!-- config-table-end -->
+
+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) — CLI wrapping this generator
+- [`@amritk/generate-validators`](../generate-validators) — predicate-style validators (sister package)
+- [`@amritk/generate-markdown`](../generate-markdown) — markdown documentation generator
+- [`@amritk/helpers`](../helpers) — shared schema-traversal utilities
+
+---
+
+## License
+
+[MIT](../../LICENSE)

package/dist/generators/build-schema.d.ts

@@ -0,0 +1,62 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { SchemaExtensions } from '#types/schema-extensions';
+/**
+ * Represents a generated file with its filename and content.
+ */
+export type GeneratedFile = {
+    filename: string;
+    content: string;
+};
+/**
+ * Builds all TypeScript files from a JSON Schema by traversing
+ * all $ref references recursively.
+ *
+ * Starting from the root schema, this function:
+ * 1. Generates a TypeScript file for the root type
+ * 2. Extracts all $ref references from the schema
+ * 3. Extracts all definitions with $dynamicAnchor (JSON Schema 2020-12 feature)
+ * 4. Resolves each ref and generates a TypeScript file for it
+ * 5. Recursively processes nested refs until all are handled
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g., "Document")
+ * @param extensions - Optional map of custom extension properties to add to specific definitions.
+ *   Keys are definition names (matching $defs keys), values are records of extension property
+ *   names to their JSON Schema definitions. Extensions are merged as optional properties before
+ *   type and parser generation.
+ * @param typesOnly - When true, only generate TypeScript type definitions without parser functions.
+ * @param logWarnings - When true, the generated parsers emit a console.warn for every input key
+ *   that is not declared in the schema's properties.
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: "object",
+ *   properties: {
+ *     info: { $ref: "#/$defs/info" }
+ *   },
+ *   $defs: {
+ *     info: {
+ *       type: "object",
+ *       properties: {
+ *         title: { type: "string" }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const files = buildSchema(schema, "Document");
+ *
+ * // Types-only mode — no parser functions or runtime helpers included:
+ * const typesFiles = buildSchema(schema, "Document", undefined, true);
+ *
+ * // With extensions:
+ * const filesWithExtensions = buildSchema(schema, "Document", {
+ *   info: {
+ *     'x-internal': { type: 'boolean' },
+ *   },
+ * });
+ * ```
+ */
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean) => Promise<GeneratedFile[]>;

package/dist/generators/generate-default-from-pattern.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a best-guess default value from a regex pattern.
+ * Recognizes common patterns and returns appropriate defaults.
+ */
+export declare const generateDefaultFromPattern: (pattern: string) => string | null;

package/dist/generators/generate-discriminated-union-validation.d.ts

@@ -0,0 +1,6 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates a discriminated union validation expression.
+ * Uses a discriminator property to efficiently choose the correct schema.
+ */
+export declare const generateDiscriminatedUnionValidation: (accessor: string, schemas: readonly JSONSchema[], discriminatorKey: string, defaultValue: string, isRequired: boolean) => string;

package/dist/generators/generate-enum-check.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates an enum validation check expression.
+ * Returns a string that checks if the value is in the allowed enum values.
+ */
+export declare const generateEnumCheck: (accessor: string, enumValues: readonly unknown[]) => string;

package/dist/generators/generate-files.d.ts

@@ -0,0 +1,58 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling what gets generated in a file.
+ */
+type GenerateFileOptions = {
+    /**
+     * When true, only emit the TypeScript type definition and skip the parser function.
+     * Imports will be type-only as well, since there are no parsers to call.
+     */
+    readonly typesOnly?: boolean;
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/encoding`).
+     * When provided, any $ref that resolves to the same filename is excluded from
+     * the import list, preventing a file from importing itself.
+     */
+    readonly selfRef?: string;
+    /**
+     * The root schema document. When provided, URI refs that cannot be resolved
+     * within the root schema's $defs are excluded from the import list.
+     */
+    readonly rootSchema?: Record<string, unknown>;
+    /**
+     * When true, the generated parser emits a console.warn for every input key
+     * that is not declared in the schema's properties.
+     */
+    readonly logWarnings?: boolean;
+};
+/**
+ * Generates a complete TypeScript file from a JSON Schema.
+ *
+ * The generated file contains imports, type definition, and parser function.
+ * When typesOnly is true, only the type definition is emitted without any parser.
+ *
+ * @param schema - The JSON Schema to generate code from
+ * @param typeName - The name to use for the generated TypeScript type
+ * @param options - Optional settings to control what gets generated
+ * @returns The complete TypeScript code
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" },
+ *     age: { type: "number" }
+ *   },
+ *   required: ["name"]
+ * };
+ *
+ * const result = generateFile(schema, "User");
+ * // result contains imports, type User, and parseUser function
+ *
+ * const typesOnly = generateFile(schema, "User", { typesOnly: true });
+ * // typesOnly contains only type-only imports and type User (no parser)
+ * ```
+ */
+export declare const generateFile: (schema: JSONSchema, typeName: string, options?: GenerateFileOptions) => string;
+export {};

package/dist/generators/generate-non-discriminated-union-validation.d.ts

@@ -0,0 +1,6 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates a non-discriminated union validation expression.
+ * Tries each schema in order until one matches.
+ */
+export declare const generateNonDiscriminatedUnionValidation: (accessor: string, schemas: readonly JSONSchema[], defaultValue: string, isRequired: boolean) => string;

package/dist/generators/generate-parser-function.d.ts

@@ -0,0 +1,47 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling parser function generation behavior.
+ */
+type GenerateParserOptions = {
+    /**
+     * When true, properties with $ref will call the imported parser function
+     * instead of inlining the validation logic. This is used when generating
+     * files where each ref has its own separate file with a parser.
+     */
+    readonly useRefImports?: boolean;
+    /**
+     * When true, the generated parser emits a console.warn for every input key
+     * that is not declared in the schema's properties.
+     */
+    readonly logWarnings?: boolean;
+};
+/**
+ * Generates a safe parser as an arrow function that never throws.
+ * The parser provides default values for all missing or invalid fields.
+ *
+ * When useRefImports is enabled, properties with $ref will call the imported
+ * parser function (e.g., parseContact(input?.contact)) instead of inlining
+ * the resolved schema's validation logic. Array properties whose items are a
+ * $ref will map each element through the imported parser.
+ */
+export declare const generateParserFunction: (schema: JSONSchema, typeName: string, options?: GenerateParserOptions) => string;
+/**
+ * Returns the predicate function name for a generated shape validator.
+ * @example shapeValidatorFunctionName('CustomerObject') // 'validateCustomerObjectShape'
+ */
+export declare const shapeValidatorFunctionName: (typeName: string) => string;
+/**
+ * Generates a `validate{TypeName}Shape(input)` predicate that returns true
+ * iff `input` already matches the shape produced by the parser's fast path —
+ * i.e. the parser would return `{ ...input } as TypeName` without coercion.
+ *
+ * Parents call this predicate to fast-path through nested ref properties
+ * (and arrays of refs) without recursing into their parser.
+ *
+ * Returns a stub that always returns `false` for schemas that cannot be
+ * predicated (composition, conditionals, pattern properties, complex refs
+ * in additionalProperties). The stub is safe: parents calling it will fall
+ * through to the slow path, matching the pre-deep-fast-path behavior.
+ */
+export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean) => string;
+export {};

package/dist/generators/generate-schema-checks.d.ts

@@ -0,0 +1,5 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates validation checks for a single schema (used in union validation).
+ */
+export declare const generateSchemaChecks: (accessor: string, schema: JSONSchema) => string[];

package/dist/generators/generate-validation-expression.d.ts

@@ -0,0 +1,7 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates a validation expression that checks if a value matches the expected type.
+ * Returns the value if valid, coerces to the correct type if invalid, or uses default if required and missing.
+ * Supports type checking, pattern validation, enum validation, union types, and $ref resolution.
+ */
+export declare const generateValidationExpression: (key: string, schema: JSONSchema, defaultValue: string, isRequired: boolean, rootSchema?: Record<string, unknown>, visitedRefs?: Set<string>, accessorOverride?: string, knownNotUndefined?: boolean) => string;

package/dist/helpers/apply-schema-extensions.d.ts

@@ -0,0 +1,35 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { SchemaExtensions } from '#types/schema-extensions';
+/**
+ * Merges custom extension properties into a schema's properties based on the
+ * definition name. Extension properties are added as optional (not included
+ * in the required array) since they are custom additions that may not always
+ * be present.
+ *
+ * If the schema is not an object, has no matching extensions, or the
+ * extensions record is empty, the original schema is returned unchanged.
+ *
+ * @param schema - The JSON Schema to extend
+ * @param definitionName - The name of the definition (e.g., "parameter")
+ * @param extensions - The extensions configuration mapping definition names to properties
+ * @returns A new schema with extension properties merged in, or the original if unchanged
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   properties: { name: { type: 'string' } },
+ *   required: ['name'],
+ * }
+ *
+ * const extensions = {
+ *   parameter: {
+ *     'x-enabled': { type: 'boolean' },
+ *   },
+ * }
+ *
+ * const extended = applySchemaExtensions(schema, 'parameter', extensions)
+ * // extended.properties now includes 'x-enabled' alongside 'name'
+ * ```
+ */
+export declare const applySchemaExtensions: (schema: JSONSchema, definitionName: string, extensions: SchemaExtensions) => JSONSchema;

package/dist/helpers/collect-helpers.d.ts

@@ -0,0 +1,2 @@
+/** A more foolproof way to generate imports from the parserFunction */
+export declare const collectHelpers: (parserFunction: string) => string[];

package/dist/helpers/collect-imports.d.ts

@@ -0,0 +1,64 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling how imports are collected.
+ */
+type CollectImportsOptions = {
+    /**
+     * When true, only generate type-only imports (no parser function imports).
+     * Use this when generating types-only files that do not include parser functions.
+     */
+    readonly typesOnly?: boolean;
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/encoding`).
+     * When provided, any $ref that resolves to the same filename is excluded from
+     * the import list, preventing a file from importing itself.
+     */
+    readonly selfRef?: string | undefined;
+    /**
+     * The root schema document. When provided, URI refs that cannot be resolved
+     * within the root schema's $defs are excluded from the import list, preventing
+     * imports for external schemas that were never generated as files.
+     */
+    readonly rootSchema?: Record<string, unknown> | undefined;
+};
+/**
+ * Collects all import statements needed for a schema by finding $ref references
+ * that are directly used in the type definition (from properties, items, etc.).
+ * Does not include refs from nested schema definitions.
+ *
+ * Generates both type imports and parser function imports for each $ref.
+ * The parser imports allow validators to delegate validation to the referenced
+ * schema's parser instead of inlining the validation logic.
+ *
+ * Also detects when helper functions (isObject) and validators (validateRecord,
+ * validateArray) are needed based on the schema structure.
+ *
+ * @param schema - The JSON Schema to collect imports from
+ * @param options - Optional settings to control import generation
+ * @returns An array of import statements
+ *
+ * @example
+ * ```ts
+ * const schema = {
+ *   type: 'object',
+ *   properties: {
+ *     contact: { $ref: '#/$defs/contact' },
+ *     server: { $ref: '#/$defs/server' }
+ *   }
+ * }
+ * const imports = collectImports(schema)
+ * // imports = [
+ * //   "import { type Contact, parseContact } from './contact';",
+ * //   "import { type Server, parseServer } from './server';"
+ * // ]
+ *
+ * // With typesOnly, only type imports are generated:
+ * const typeImports = collectImports(schema, { typesOnly: true })
+ * // typeImports = [
+ * //   "import type { Contact } from './contact';",
+ * //   "import type { Server } from './server';"
+ * // ]
+ * ```
+ */
+export declare const collectImports: (schema: JSONSchema, options?: CollectImportsOptions) => string[];
+export {};

package/dist/helpers/find-discriminator.d.ts

@@ -0,0 +1,6 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Attempts to find a discriminator property that can be used to distinguish between union types.
+ * Returns the property name if a suitable discriminator is found, otherwise null.
+ */
+export declare const findDiscriminator: (schemas: readonly JSONSchema[]) => string | null;

package/dist/helpers/get-default-value.d.ts

@@ -0,0 +1,7 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Returns the default value for a JSON Schema property.
+ * Priority order: explicit default > first enum value > first example > union first schema > pattern-based > type-based.
+ * These defaults ensure that parsing never fails, even with missing data.
+ */
+export declare const getDefaultValue: (schema: JSONSchema) => string;

package/dist/helpers/get-discriminator-value.d.ts

@@ -0,0 +1,6 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Gets the discriminator value for a specific schema.
+ * Returns the const value or single enum value if available.
+ */
+export declare const getDiscriminatorValue: (schema: JSONSchema, discriminatorKey: string) => unknown | null;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { buildSchema } from './generators/build-schema';