@amritk/generate-parsers 0.24.0 → 0.25.1

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

@@ -1,15 +0,0 @@
-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/generators/generate-discriminated-union-validation.js

@@ -1,28 +0,0 @@
-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/generators/generate-enum-check.d.ts

@@ -1,35 +0,0 @@
-/**
- * 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/generators/generate-enum-check.js

@@ -1,31 +0,0 @@
-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/generators/generate-files.d.ts

@@ -1,138 +0,0 @@
-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/generators/generate-files.js

@@ -1,89 +0,0 @@
-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/generators/generate-non-discriminated-union-validation.d.ts

@@ -1,6 +0,0 @@
-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-non-discriminated-union-validation.js

@@ -1,26 +0,0 @@
-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
-};

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

@@ -1,120 +0,0 @@
-import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
-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;
-    /**
-     * When true, the generated parser throws on type/shape mismatches instead
-     * of coercing invalid input to default values. Throws on the first violation
-     * with a path-aware Error. When the schema sets `additionalProperties: false`,
-     * undeclared keys throw too; otherwise they are still allowed.
-     */
-    readonly strict?: boolean;
-    /**
-     * When true, the generated parser builds its result from the schema's declared
-     * properties only, silently dropping any undeclared input key at every nesting
-     * level (zod's `.strip()`). Unlike `additionalProperties: false`, extras are
-     * never a validation error — this composes with `strict`: `strict + stripUnknown`
-     * still throws on wrong types and missing required properties but strips extras
-     * instead of throwing on them. When the schema *also* sets
-     * `additionalProperties: false`, rejecting wins over stripping in strict mode.
-     */
-    readonly stripUnknown?: boolean;
-    /**
-     * Suffix appended to every type/parser name derived from a `$ref`. Must match
-     * the suffix used when generating the referenced files. Defaults to `''`.
-     */
-    readonly typeSuffix?: string;
-    /**
-     * The root schema document. When present, a top-level `oneOf`/`anyOf` whose
-     * branches are `$ref`s can be resolved to find a shared discriminator and emit a
-     * dispatch to the branch parsers, instead of falling back to a passthrough cast.
-     */
-    readonly rootSchema?: Record<string, unknown>;
-    /**
-     * Type names the generated file imports for its `$ref`s. Synthesized private
-     * sub-type names (nested objects, array items, the root array's `{Type}Item`)
-     * dedup against this set so they can never shadow an imported identifier —
-     * which would both fail to compile (duplicate declaration) and silently
-     * validate against the wrong schema.
-     */
-    readonly reservedNames?: ReadonlySet<string>;
-    /**
-     * True when this schema is the root document (not a `$ref`-reached definition).
-     * The root type name is user-derived (schema `title`, filename, or `--root-type`),
-     * so the JSON Schema meta-schema special case — keyed on the literal name
-     * `Schema` — must not apply to it, or a common `schema.json` root would silently
-     * generate a validation-free pass-through parser.
-     */
-    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 (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
-     * failure branch of the coercion ternary, so a correctly-cased value keeps the
-     * exact `===` fast path and the hot path is unaffected.
-     */
-    readonly caseInsensitive?: boolean;
-    /**
-     * How the fast paths prove a closed object carries no undeclared key —
-     * `Object.getPrototypeOf(input) === Object.prototype && Object.keys(input).length`
-     * (the default) or a `for…in` count. See {@link UnknownKeysStrategy} for the
-     * trade-off, and {@link keyCountCheck} for what each form emits.
-     */
-    readonly unknownKeys?: UnknownKeysStrategy;
-    /**
-     * The exact source of the `validate{TypeName}Shape` predicate emitted into
-     * the same file as this parser (generate-files produces it for the root
-     * type). When the parser can prove — by rendering the predicate it would
-     * need and comparing byte-for-byte — that this emitted predicate tests
-     * exactly its own fast-path guard, it emits `validate{TypeName}Shape(input)`
-     * instead of a second inline copy of the whole check chain, which roughly
-     * halves the emitted checks per object type. Any mismatch (composition
-     * keywords, conditional flattening, alias/union predicates, stubs) keeps
-     * the inline guard, so a wrong substitution is impossible by construction.
-     */
-    readonly shapeValidatorSource?: string;
-};
-/**
- * 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, rawOptions?: 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, suffix?: string, exported?: boolean, stripUnknown?: boolean, reservedNames?: ReadonlySet<string>, unknownKeys?: UnknownKeysStrategy) => string;
-export {};