@amritk/generate-validators 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+<div align="center">
+
+# @amritk/generate-validators
+
+**Programmatic API for generating predicate-style TypeScript validators 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-100%25-a855f7?style=flat-square)
+
+</div>
+
+---
+
+## Overview
+
+`@amritk/generate-validators` produces lightweight runtime **validators** from a JSON Schema. Where [`@amritk/generate-parsers`](../generate-parsers) coerces and parses unknown input into a typed value, this package emits cheaper predicate-style functions that simply tell you whether a value matches a schema (and where it doesn't).
+
+Each generated file exports:
+
+- A TypeScript `type` definition for the schema
+- A `validateFoo(input: unknown, _path?: string): ValidationResult` function
+
+A shared `validation-result.ts` template and an `index.ts` barrel are emitted alongside the generated files.
+
+---
+
+## Installation
+
+```bash
+npm install @amritk/generate-validators
+# or
+pnpm add @amritk/generate-validators
+# or
+yarn add @amritk/generate-validators
+# or
+bun add @amritk/generate-validators
+```
+
+---
+
+## Usage
+
+```ts
+import { buildValidatorSchema } from '@amritk/generate-validators'
+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' } },
+      required: ['title'],
+    },
+  },
+}
+
+const files = await buildValidatorSchema(schema, 'Document')
+// → [{ filename: 'document.ts', content: '...' }, { filename: 'info.ts', ... }, { filename: 'validation-result.ts', ... }, { filename: 'index.ts', ... }]
+```
+
+Write the resulting files to disk and import the validators where you need them:
+
+```ts
+import { validateDocument } from './generated'
+
+const result = validateDocument(input)
+if (!result.valid) {
+  console.error(result.errors)
+}
+```
+
+---
+
+## API
+
+### `buildValidatorSchema(rootSchema, rootTypeName)`
+
+| Parameter | Type | Description |
+|:---|:---|:---|
+| `rootSchema` | `JSONSchema` | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. Draft-07 schemas are upgraded to 2020-12 automatically. |
+| `rootTypeName` | `string` | Name used for the root type (e.g. `"Document"`). |
+
+Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
+
+---
+
+## Related packages
+
+- [`@amritk/generate-parsers`](../generate-parsers) — type definitions plus parsers that coerce input
+- [`@amritk/mjst`](../cli) — CLI wrapper around the generators
+- [`@amritk/helpers`](../helpers) — shared schema-traversal utilities
+
+---
+
+## License
+
+[MIT](../../LICENSE)

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

@@ -0,0 +1,30 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Represents a generated TypeScript file with its filename and content.
+ */
+export type GeneratedFile = {
+    filename: string;
+    content: string;
+};
+/**
+ * Builds all TypeScript validator files from a JSON Schema by traversing
+ * all $ref references recursively, mirroring the generate-parsers pipeline.
+ *
+ * Each generated file exports:
+ * - A TypeScript type definition
+ * - A `validateFoo(input: unknown, _path?: string): ValidationResult` function
+ *
+ * A `validation-result.ts` file containing the `ValidationResult` and `ValidationError`
+ * runtime contract is always emitted. An `index.ts` re-exports everything.
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g. "Document")
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const files = await buildValidatorSchema(schema, 'Document')
+ * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'info.ts', ... }, ...]
+ * ```
+ */
+export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string) => Promise<GeneratedFile[]>;

package/dist/generators/collect-validator-imports.d.ts

@@ -0,0 +1,29 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling how validator imports are collected.
+ */
+type CollectValidatorImportsOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/encoding`).
+     * Prevents a file from importing itself.
+     */
+    readonly selfRef?: string | undefined;
+    /**
+     * The root schema document. URI refs that cannot be resolved within it
+     * are excluded from the import list (they were never generated as files).
+     */
+    readonly rootSchema?: Record<string, unknown> | undefined;
+};
+/**
+ * Collects import statements for all $ref dependencies of a schema.
+ * Each import brings in both the generated TypeScript type and validator function.
+ *
+ * @example
+ * ```typescript
+ * const schema = { properties: { contact: { $ref: '#/$defs/contact' } } }
+ * collectValidatorImports(schema)
+ * // ["import { type ContactObject, validateContactObject } from './contact-object'"]
+ * ```
+ */
+export declare const collectValidatorImports: (schema: JSONSchema, options?: CollectValidatorImportsOptions) => string[];
+export {};

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

@@ -0,0 +1,39 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling what gets generated in a validator file.
+ */
+type GenerateValidatorFileOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/info`).
+     * Prevents the file from importing itself.
+     */
+    readonly selfRef?: string;
+    /**
+     * The root schema document. Used to filter out unresolvable refs.
+     */
+    readonly rootSchema?: Record<string, unknown>;
+};
+/**
+ * Generates a complete TypeScript validator file from a JSON Schema.
+ *
+ * The file contains:
+ * - Imports for the ValidationResult/ValidationError types
+ * - Imports for any $ref types and their validator functions
+ * - The exported TypeScript type definition
+ * - The exported validator function
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   properties: { title: { type: 'string' } },
+ *   required: ['title'],
+ * }
+ * generateValidatorFile(schema, 'Info')
+ * // import type { ValidationResult, ValidationError } from './validation-result'
+ * // export type Info = { title: string }
+ * // export const validateInfo = (input: unknown, _path = ''): ValidationResult => { ... }
+ * ```
+ */
+export declare const generateValidatorFile: (schema: JSONSchema, typeName: string, options?: GenerateValidatorFileOptions) => string;
+export {};

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

@@ -0,0 +1,24 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates a TypeScript validator function from a JSON Schema.
+ *
+ * The generated function accepts `unknown` input and returns `true` if valid,
+ * or `{ valid: false, errors }` with a list of errors if not.
+ *
+ * Object schemas check that required properties are present and that all
+ * provided properties match their declared types. Non-object schemas (strings,
+ * numbers, enums, $refs) emit an inline type check.
+ *
+ * @example
+ * ```typescript
+ * generateValidatorFunction({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
+ * // export const validateInfo = (input: unknown, _path = ''): ValidationResult => {
+ * //   if (typeof input !== 'object' || ...) return { valid: false, ... }
+ * //   const errors: ValidationError[] = []
+ * //   const obj = input as Record<string, unknown>
+ * //   if (!('name' in obj)) { errors.push(...) } else if (typeof obj['name'] !== 'string') { errors.push(...) }
+ * //   return errors.length > 0 ? { valid: false, errors } : true
+ * // }
+ * ```
+ */
+export declare const generateValidatorFunction: (schema: JSONSchema, typeName: string) => string;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { GeneratedFile } from './generators/build-schema';
+export { buildValidatorSchema } from './generators/build-schema';