@amritk/validation 0.2.0

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

@@ -0,0 +1,111 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { HelpersMode } from '../helpers/collect-helpers.js';
+import type { ImportExtension } from '../helpers/collect-imports.js';
+import type { SchemaExtensions } from '../types/schema-extensions.js';
+/**
+ * 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 its entire
+ * `$ref` / `$dynamicRef` graph (via the shared `@amritk/helpers/walk-ref-graph`
+ * walker, which also seeds `$dynamicAnchor` definitions and rewrites
+ * `$dynamicRef` to `$ref`).
+ *
+ * For the root schema and each reachable definition this function generates a
+ * TypeScript file, then emits an `index.ts` barrel re-exporting them all.
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g., "Document"). Must be a TypeScript
+ *   identifier: it is emitted verbatim as `export type <name>` and, lowercased, becomes the
+ *   output filename, so a name derived from an untrusted document is refused rather than
+ *   written outside the output directory.
+ * @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.
+ * @param strict - When true, the 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.
+ * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
+ *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
+ *   as additional `GeneratedFile` entries so the output directory is self-contained.
+ * @param helpersImportPrefix - Relative path prefix to the `_helpers/` directory in
+ *   embedded mode. Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
+ *   `'../../'`, etc. so nested parsers can import from a single shared `_helpers/`
+ *   directory while the helper sources are emitted once at the output root.
+ * @param readonly - When true, every property, array, and record in the generated type
+ *   definitions is emitted as `readonly`.
+ * @param stripUnknown - When true, the generated parsers build their result from declared
+ *   properties only, silently dropping undeclared input keys at every nesting level (zod's
+ *   `.strip()`) without treating extras as a validation error. Composes with `strict` and
+ *   yields to `additionalProperties: false` (which rejects rather than strips in strict mode).
+ * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
+ *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
+ *   is used verbatim and is not affected by this suffix.
+ * @param importExt - Extension used on every relative import specifier in the generated
+ *   output (cross-file `$ref` imports, the index barrel, and embedded-helper imports).
+ *   `'js'` (this function's default) is the standard TS NodeNext form; `'ts'` emits the
+ *   literal on-disk paths so the generated sources run directly under Node's type
+ *   stripping. Note the `mjst` CLI defaults this to `'ts'` (falling back to `'js'` only
+ *   under `--build`, where tsc must compile the sources) so generated output runs under
+ *   Node without a build step; direct callers of `buildSchema` opt in explicitly.
+ * @param caseInsensitive - When true, the generated coercing parsers normalize a mis-cased
+ *   string to the exact casing of a declared `enum`/`const` member it matches
+ *   case-insensitively (e.g. `hElLo` → `hello`) instead of coercing to the default. Coerce
+ *   mode only — strict parsers still reject a casing mismatch. The normalization lives on
+ *   the coercion failure branch, so correctly-cased input keeps the exact-match fast path
+ *   and the hot path is unaffected.
+ * @param schemas - Other schema documents you have **already loaded**, keyed by the absolute
+ *   URI a `$ref` names them by. Supplying them makes those URIs resolvable, so the schema can
+ *   reference a document that is not itself — each one becomes a resource of the generated
+ *   document, with its own `$id`, anchors and nested resources all resolvable, and a `$ref`
+ *   from one registered document into another resolving too. Nothing is fetched here: loading
+ *   is yours to do (or `@amritk/resolve-refs`'), and a `$ref` to a URI nobody registered still
+ *   stops generation. Only the documents actually referenced get files, so registering more
+ *   than the schema uses costs nothing in the output.
+ * @param unknownKeys - How the generated fast paths prove a closed object
+ *   (`additionalProperties: false`, or a `stripUnknown` build) carries no undeclared key:
+ *   `'count-keys'` (the default) compares `Object.keys(input).length` behind a plain-prototype
+ *   guard, `'count-enumerable'` counts with `for…in`. The first is the faster form on
+ *   JavaScriptCore (Bun), the second on V8 (Node) — see the README for the measurements.
+ * @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, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension, caseInsensitive?: boolean, schemas?: Readonly<Record<string, unknown>>, unknownKeys?: UnknownKeysStrategy) => Promise<GeneratedFile[]>;

package/dist/parsers/generators/build-schema.js

@@ -0,0 +1,74 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, resolve as resolvePath } from "node:path";
+import { foldNullable } from "@amritk/helpers/fold-nullable";
+import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
+import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
+import { applySchemaExtensions } from "../helpers/apply-schema-extensions.js";
+import { generateFile } from "./generate-files.js";
+const readHelperSource = async (helper, importExt) => {
+  const require2 = createRequire(import.meta.url);
+  const helpersRoot = dirname(require2.resolve("@amritk/helpers/package.json"));
+  try {
+    const source = await readFile(resolvePath(helpersRoot, "src", `${helper}.ts`), "utf-8");
+    return { ext: "ts", content: source.replace(/\bfrom '(\.\/[^'".]+)'/g, `from '$1.${importExt}'`) };
+  } catch {
+    const compiled = await readFile(resolvePath(helpersRoot, "dist", `${helper}.js`), "utf-8");
+    if (importExt === "ts") {
+      return { ext: "ts", content: compiled.replace(/\bfrom '(\.\/[^'"]+)\.js'/g, "from '$1.ts'") };
+    }
+    return { ext: "js", content: compiled };
+  }
+};
+const ROOT_TYPE_NAME = /^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u;
+const assertRootTypeName = (rootTypeName) => {
+  if (ROOT_TYPE_NAME.test(rootTypeName))
+    return;
+  throw new Error(`Invalid root type name ${JSON.stringify(rootTypeName)}: expected a TypeScript identifier. The name is emitted as \`export type <name>\` and, lowercased, used as the output filename, so anything else either fails to compile or escapes the output directory. Derive it with @amritk/helpers' \`deriveRootTypeName\`, which always produces one.`);
+};
+const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false, schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
+  assertRootTypeName(rootTypeName);
+  const files = [];
+  const usedHelpers = /* @__PURE__ */ new Set();
+  const foldedSchema = foldNullable(rootSchema);
+  walkRefGraph(foldedSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
+    if (node.filename === "index")
+      return;
+    const extended = extensions ? applySchemaExtensions(node.schema, node.filename, extensions) : node.schema;
+    const result = generateFile(extended, node.typeName, {
+      selfFilename: node.filename,
+      typesOnly: typesOnly ?? false,
+      rootSchema: node.rootSchema,
+      helpersMode,
+      helpersImportPrefix,
+      readonly,
+      typeSuffix,
+      importExt,
+      isRoot: node.isRoot,
+      ...node.ref !== void 0 ? { selfRef: node.ref } : {},
+      ...logWarnings !== void 0 ? { logWarnings } : {},
+      ...strict !== void 0 ? { strict } : {},
+      ...stripUnknown ? { stripUnknown } : {},
+      ...caseInsensitive ? { caseInsensitive } : {},
+      unknownKeys
+    });
+    files.push({ filename: `${node.filename}.ts`, content: result.content });
+    for (const helper of result.usedHelpers)
+      usedHelpers.add(helper);
+  });
+  if (helpersMode === "embedded" && !typesOnly) {
+    for (const helper of usedHelpers) {
+      const { ext, content } = await readHelperSource(helper, importExt);
+      files.push({ filename: `_helpers/${helper}.${ext}`, content });
+    }
+  }
+  files.push({
+    filename: "index.ts",
+    content: generateIndexBarrel(files, { typesOnly: typesOnly ?? false, importExt })
+  });
+  return files;
+};
+export {
+  buildSchema
+};

package/dist/parsers/generators/generate-deep-equal-check.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Builds a boolean expression that is TRUE when `accessor` is structurally equal
+ * to `value` — a literal known at generation time (an `enum` member, a `const`).
+ *
+ * Why not `===` / `.includes` / `JSON.stringify`, the three forms this replaced:
+ *
+ * - `.includes(x)` is SameValueZero, i.e. *reference* equality for objects and
+ *   arrays. `{ enum: [{ a: 1 }] }` could therefore never match a freshly parsed
+ *   `{ a: 1 }`, so the strict parser threw on a document Ajv accepts and the fast
+ *   path never fired.
+ * - `JSON.stringify(x) !== '{"a":1,"b":2}'` is key-order sensitive, so a
+ *   reordered-but-equal `{ b: 2, a: 1 }` was rejected — and it serialized the
+ *   whole value on every call just to answer a yes/no question.
+ *
+ * Because the literal is known up front the comparison is unrolled into a flat
+ * chain of `typeof` / `===` tests against its shape: no serialization, no
+ * allocation, and key order cannot matter because keys are compared by name. The
+ * `Object.keys(...).length === n` term is what makes it an equality rather than a
+ * "has at least these fields" check.
+ *
+ * @param accessor - Expression yielding the runtime value (may be `unknown`).
+ * @param value - The literal to compare against.
+ */
+export declare const generateDeepEqualCheck: (accessor: string, value: unknown) => string;

package/dist/parsers/generators/generate-deep-equal-check.js

@@ -0,0 +1,35 @@
+import { safeAccessor } from "@amritk/helpers/safe-accessor";
+const generateDeepEqualCheck = (accessor, value) => {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "number" && Number.isNaN(value))
+      return `Number.isNaN(${accessor})`;
+    return `${accessor} === ${JSON.stringify(value)}`;
+  }
+  if (Array.isArray(value)) {
+    const elements = `(${accessor} as unknown[])`;
+    const parts2 = [`Array.isArray(${accessor})`, `${elements}.length === ${value.length}`];
+    for (let i = 0; i < value.length; i++) {
+      parts2.push(generateDeepEqualCheck(`${elements}[${i}]`, value[i]));
+    }
+    return parts2.join(" && ");
+  }
+  const entries = Object.entries(value);
+  const record = `(${accessor} as Record<string, unknown>)`;
+  const parts = [
+    `typeof ${accessor} === "object"`,
+    `${accessor} !== null`,
+    `!Array.isArray(${accessor})`,
+    // Pins the key count, so an object carrying extra keys is not "equal" to one
+    // that only has the declared ones. Combined with the per-key value checks
+    // below (an absent key reads as `undefined`, which no JSON literal equals)
+    // this is exact structural equality.
+    `Object.keys(${accessor} as object).length === ${entries.length}`
+  ];
+  for (const [key, sub] of entries) {
+    parts.push(generateDeepEqualCheck(safeAccessor(record, key), sub));
+  }
+  return parts.join(" && ");
+};
+export {
+  generateDeepEqualCheck
+};

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

@@ -0,0 +1,15 @@
+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.
+ *
+ * The emitted expression is a single *nested* ternary in schema order — for
+ * branches `dog`, `cat` it reads `disc === "dog" ? v : disc === "cat" ? v :
+ * <fallback>`. Each branch tests its discriminant (plus any per-branch shape
+ * checks) and, on a match, passes the value through; the innermost `else` is the
+ * shared fallback taken when no discriminant matches. The previous
+ * `cases[i] + ' : ' + result` folding spliced complete ternaries together
+ * (`c1 ? v : d1 : c0 ? v : d0`), which is a parse error for >=2 branches and
+ * also evaluated branches in reverse with the wrong per-case default.
+ */
+export declare const generateDiscriminatedUnionValidation: (accessor: string, schemas: readonly JSONSchema[], discriminatorKey: string, defaultValue: string, isRequired: boolean) => string;

package/dist/parsers/generators/generate-discriminated-union-validation.js

@@ -0,0 +1,28 @@
+import { getDiscriminatorValue } from "../helpers/get-discriminator-value.js";
+import { generateSchemaChecks } from "./generate-schema-checks.js";
+const generateDiscriminatedUnionValidation = (accessor, schemas, discriminatorKey, defaultValue, isRequired) => {
+  const discAccessor = `(${accessor} as Record<string, unknown> | null | undefined)?.[${JSON.stringify(discriminatorKey)}]`;
+  const branches = [];
+  for (const schema of schemas) {
+    const discriminatorValue = getDiscriminatorValue(schema, discriminatorKey);
+    if (discriminatorValue === null)
+      continue;
+    let condition = `${discAccessor} === ${JSON.stringify(discriminatorValue)}`;
+    const checks = generateSchemaChecks(accessor, schema);
+    for (const check of checks) {
+      condition += " && " + check;
+    }
+    branches.push(condition);
+  }
+  if (branches.length === 0) {
+    return isRequired ? `${accessor} ?? ${defaultValue}` : accessor;
+  }
+  let result = isRequired ? defaultValue : accessor;
+  for (let i = branches.length - 1; i >= 0; i--) {
+    result = `${branches[i]} ? ${accessor} : ${result}`;
+  }
+  return result;
+};
+export {
+  generateDiscriminatedUnionValidation
+};

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

@@ -0,0 +1,35 @@
+/**
+ * Generates an enum validation check expression.
+ * Returns a string that checks if the value is in the allowed enum values.
+ *
+ * For the common all-primitive case this emits a parenthesized `x === a || x ===
+ * b` chain rather than `[a, b].includes(x)`. The `.includes` form allocates a
+ * fresh array on every call (this expression runs on the parser hot path); the
+ * `===` chain is allocation-free and matches the validators package's
+ * `enumMembershipExpr`.
+ *
+ * An object or array member is compared *structurally* via
+ * {@link generateDeepEqualCheck}. `.includes` was SameValueZero — reference
+ * equality — so `{ enum: [{ a: 1 }] }` could never match a freshly parsed
+ * `{ a: 1 }`: the fast path never fired and the strict parser threw on a document
+ * Ajv accepts. `NaN` keeps its own `Number.isNaN` test, the one case `===` cannot
+ * express.
+ */
+export declare const generateEnumCheck: (accessor: string, enumValues: readonly unknown[]) => string;
+/**
+ * Builds a case-insensitive coercion expression for a string `enum`/`const`
+ * value whose exact-match check has already failed. Only the *string* members
+ * participate (a number/boolean/null member has no case to fold): a value that
+ * matches one case-insensitively normalizes to that member's exact casing, and
+ * everything else yields `fallback`.
+ *
+ * This is emitted ONLY on the already-invalid branch of the coercion ternary, so
+ * a correctly-cased value never reaches it — the exact `===` fast path (and the
+ * shape validators / deep guards built on it) is unchanged, so the hot path pays
+ * nothing. Only a mis-cased value, which today coerces straight to the default,
+ * now takes a single `toLowerCase()` and an O(1) map lookup instead.
+ *
+ * Returns `null` when no member is a string (nothing to fold), so the caller
+ * keeps its plain fallback and emits no extra code.
+ */
+export declare const generateEnumCaseInsensitiveCoercion: (accessor: string, enumValues: readonly unknown[], fallback: string) => string | null;

package/dist/parsers/generators/generate-enum-check.js

@@ -0,0 +1,31 @@
+import { generateDeepEqualCheck } from "./generate-deep-equal-check.js";
+const generateEnumCheck = (accessor, enumValues) => {
+  if (enumValues.length === 0)
+    return "false";
+  const members = enumValues.map((value) => {
+    const check = generateDeepEqualCheck(accessor, value);
+    return value !== null && typeof value === "object" ? `(${check})` : check;
+  });
+  return `(${members.join(" || ")})`;
+};
+const generateEnumCaseInsensitiveCoercion = (accessor, enumValues, fallback) => {
+  const entries = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of enumValues) {
+    if (typeof value !== "string")
+      continue;
+    const lower = value.toLowerCase();
+    if (seen.has(lower))
+      continue;
+    seen.add(lower);
+    entries.push([lower, value]);
+  }
+  if (entries.length === 0)
+    return null;
+  const map = `new Map(${JSON.stringify(entries)})`;
+  return `(typeof ${accessor} === "string" ? (${map}.get((${accessor} as string).toLowerCase()) ?? ${fallback}) : ${fallback})`;
+};
+export {
+  generateEnumCaseInsensitiveCoercion,
+  generateEnumCheck
+};

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

@@ -0,0 +1,138 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { type HelpersMode, type RuntimeHelperName } from '../helpers/collect-helpers.js';
+import { type ImportExtension } from '../helpers/collect-imports.js';
+/**
+ * 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 filename this file is written as, without extension. Used for
+     * self-import detection when the schema has no `$ref` of its own — the root
+     * document — so a `$defs` entry that collides with the root type name cannot
+     * make the root file import itself.
+     */
+    readonly selfFilename?: 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;
+    /**
+     * When true, the generated parser throws on type/shape mismatches instead
+     * of coercing invalid input to default values.
+     */
+    readonly strict?: boolean;
+    /**
+     * When true, the generated parser builds its result from declared properties
+     * only, silently dropping undeclared input keys at every nesting level (zod's
+     * `.strip()`), without treating extras as a validation error. Composes with
+     * `strict` (still throws on wrong types / missing required properties) and
+     * yields to `additionalProperties: false` (which rejects rather than strips in
+     * strict mode).
+     */
+    readonly stripUnknown?: boolean;
+    /**
+     * Controls how runtime helpers are referenced.
+     * - `'package'` (default): emit imports from `@amritk/helpers/...`.
+     * - `'embedded'`: emit imports from `./_helpers/...` so the helper sources can
+     *   be shipped alongside the generated files.
+     */
+    readonly helpersMode?: HelpersMode;
+    /**
+     * Relative path prefix to the shared `_helpers/` directory in embedded mode.
+     * Defaults to `'./'`. The recursive multi-schema build passes `'../'`,
+     * `'../../'`, etc. so a nested parser can reach a single `_helpers/` directory
+     * at the output root.
+     */
+    readonly helpersImportPrefix?: string;
+    /**
+     * When true, every property, array, and record in the generated type
+     * definitions is emitted as `readonly`.
+     */
+    readonly readonly?: boolean;
+    /**
+     * Suffix appended to every type/parser name derived from a `$ref`.
+     * Defaults to `''` (no suffix). Set to e.g. `'Object'` to emit `ContactObject`.
+     */
+    readonly typeSuffix?: string;
+    /**
+     * Extension used on every relative import specifier (cross-file `$ref`
+     * imports and embedded-helper imports). Defaults to `'js'` (the TS NodeNext
+     * form); `'ts'` makes the generated sources runnable under Node's type
+     * stripping.
+     */
+    readonly importExt?: ImportExtension;
+    /**
+     * True when this file is the root document rather than a `$ref`-reached
+     * definition. Forwarded to the parser generator so the JSON Schema
+     * meta-schema special case (type name `Schema`) never applies to a
+     * user-named root.
+     */
+    readonly isRoot?: boolean;
+    /**
+     * When true, a mis-cased string that matches a declared `enum`/`const` member
+     * case-insensitively is normalized to that member's exact casing (coerce mode
+     * only). The normalization is emitted on the coercion failure branch, so
+     * already-valid input keeps the exact-match fast path.
+     */
+    readonly caseInsensitive?: boolean;
+    /**
+     * How the generated fast paths prove a closed object carries no undeclared
+     * key — `Object.keys` (the default) or a `for…in` count. See
+     * {@link UnknownKeysStrategy} for the trade-off between the two.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
+};
+/** Result of generating a single parser file. */
+export type GeneratedFileContent = {
+    readonly content: string;
+    readonly usedHelpers: ReadonlySet<RuntimeHelperName>;
+};
+/**
+ * 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 generated file content and the set of runtime helpers it references
+ *
+ * @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) => GeneratedFileContent;
+export {};

package/dist/parsers/generators/generate-files.js

@@ -0,0 +1,89 @@
+import { generateTypeDefinition } from "@amritk/helpers/generate-type-definition";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
+import { collectHelpers } from "../helpers/collect-helpers.js";
+import { collectImports, collectImportTypeNames } from "../helpers/collect-imports.js";
+import { generateParserFunction, generateShapeValidator } from "./generate-parser-function.js";
+const generateFile = (schema, typeName, options) => {
+  const typesOnly = options?.typesOnly === true;
+  const selfRef = options?.selfRef;
+  const rootSchema = options?.rootSchema;
+  const helpersMode = options?.helpersMode ?? "package";
+  const typeSuffix = options?.typeSuffix ?? "";
+  const importExt = options?.importExt ?? "js";
+  const typeDefinition = generateTypeDefinition(schema, typeName, {
+    readonly: options?.readonly ?? false,
+    typeSuffix,
+    ...rootSchema !== void 0 ? { rootSchema } : {}
+  });
+  if (typesOnly) {
+    const imports2 = collectImports(schema, {
+      typesOnly: true,
+      selfRef,
+      selfFilename: options?.selfFilename,
+      rootSchema,
+      typeSuffix,
+      importExt,
+      usedIn: typeDefinition
+    });
+    let result2 = "";
+    if (imports2.length > 0) {
+      result2 += imports2[0];
+      for (let i = 1; i < imports2.length; i++) {
+        result2 += "\n" + imports2[i];
+      }
+      result2 += "\n\n";
+    }
+    return { content: result2 + typeDefinition, usedHelpers: /* @__PURE__ */ new Set() };
+  }
+  const stripUnknown = options?.stripUnknown ?? false;
+  const reservedNames = collectImportTypeNames(schema, {
+    selfRef,
+    selfFilename: options?.selfFilename,
+    rootSchema,
+    typeSuffix
+  });
+  const unknownKeys = options?.unknownKeys ?? DEFAULT_UNKNOWN_KEYS;
+  const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames, unknownKeys);
+  const parserFunction = generateParserFunction(schema, typeName, {
+    useRefImports: true,
+    typeSuffix,
+    reservedNames,
+    shapeValidatorSource: shapeValidator,
+    unknownKeys,
+    ...options?.isRoot !== void 0 ? { isRoot: options.isRoot } : {},
+    ...rootSchema !== void 0 ? { rootSchema } : {},
+    ...options?.logWarnings !== void 0 ? { logWarnings: options.logWarnings } : {},
+    ...options?.strict !== void 0 ? { strict: options.strict } : {},
+    ...options?.stripUnknown !== void 0 ? { stripUnknown: options.stripUnknown } : {},
+    ...options?.caseInsensitive !== void 0 ? { caseInsensitive: options.caseInsensitive } : {}
+  });
+  const combinedFunctions = `${shapeValidator}
+
+${parserFunction}`;
+  const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix, importExt);
+  const imports = [
+    ...collectImports(schema, {
+      selfRef,
+      selfFilename: options?.selfFilename,
+      rootSchema,
+      typeSuffix,
+      importExt,
+      // Both halves of the file: the type names the type definition spells and
+      // the functions the emitted code calls are one question about one text.
+      usedIn: typeDefinition + "\n\n" + combinedFunctions
+    }),
+    ...helpers.imports
+  ];
+  let result = "";
+  if (imports.length > 0) {
+    result += imports[0];
+    for (let i = 1; i < imports.length; i++) {
+      result += "\n" + imports[i];
+    }
+    result += "\n\n";
+  }
+  return { content: result + typeDefinition + "\n\n" + combinedFunctions, usedHelpers: helpers.used };
+};
+export {
+  generateFile
+};

package/dist/parsers/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/parsers/generators/generate-non-discriminated-union-validation.js

@@ -0,0 +1,26 @@
+import { generateSchemaChecks } from "./generate-schema-checks.js";
+const generateNonDiscriminatedUnionValidation = (accessor, schemas, defaultValue, isRequired) => {
+  const cases = [];
+  for (const schema of schemas) {
+    const checks = generateSchemaChecks(accessor, schema);
+    if (checks.length > 0) {
+      let combinedChecks = checks[0];
+      for (let i = 1; i < checks.length; i++) {
+        combinedChecks += " && " + checks[i];
+      }
+      cases.push("(" + combinedChecks + ")");
+    }
+  }
+  if (cases.length === 0) {
+    return isRequired ? `${accessor} ?? ${defaultValue}` : accessor;
+  }
+  let combinedCheck = cases[0];
+  for (let i = 1; i < cases.length; i++) {
+    combinedCheck += " || " + cases[i];
+  }
+  const finalDefault = isRequired ? defaultValue : "undefined";
+  return `(${combinedCheck}) ? ${accessor} : ${finalDefault}`;
+};
+export {
+  generateNonDiscriminatedUnionValidation
+};