@amritk/validation 0.3.1 → 0.4.0

package/AI.md

@@ -89,4 +89,20 @@ spelled as a flag: everything that judges a document, nothing that builds one.
    of two, and that a build asking for no validator mode ships no
    `validation-result.ts`.
 
+9. **`coerceX` is not Ajv's `coerceTypes`, on purpose.** It never modifies its
+   input (no defensive clone needed), never coerces `null` in either direction,
+   and reads only clean numerals as numbers (`" "`, `"0x10"`, `"Infinity"` are
+   rejected). It coerces inside `anyOf`/`oneOf`/`allOf`/`if`: a union branch the
+   value already matches wins uncoerced (so `false` stays `false` under
+   `anyOf: [string, { const: false }]`, where Ajv answers `"false"`), and two
+   branches that would coerce to different values leave it as written. Do not
+   tell a user a value will come out the way Ajv would produce it inside a union.
+10. **The coercing `parseX` returns exactly what `coerceX` returns** whenever
+   `coerceX` accepts the document, and only repairs what `coerceX` would reject.
+   A parser file for a definition with `anyOf`/`oneOf`/`allOf`/`if`/`not` (or one
+   such a definition reaches) therefore exports `matchesX` and `coerceXInput`
+   too, and its repairing parser is private (`_parseXRepair`, kept out of the
+   barrel — a leading `_` marks a name for sibling files only). Strict and
+   `stripUnknown` parsers are unchanged.
+
 Only the `.` entry. Install: `bun add @amritk/validation`.

package/README.md

@@ -92,9 +92,90 @@ never fails. Coercion moves a value that is already right but written in the
 wrong type; repair also substitutes a value the schema supplies for one that
 cannot be coerced, and reports the validator's own errors as the repairs.
 
+**`parseX` agrees with `coerceX`.** Wherever `coerceX` accepts a document, the
+coercing `parseX` returns the very same value — through a union, an `allOf`, an
+`if`, a `$ref`, recursion included — and it only repairs what `coerceX` would
+have rejected. A differential test pins that over random schemas. To get there,
+a definition whose own tree has an `anyOf`/`oneOf`/`allOf`/`if`/`not` carries an
+exact test (`matchesX`) and the coercion walk (`coerceXInput`) in front of its
+repairing parser, and every definition such a one reaches carries them too. A
+schema without combinators emits exactly what it always did; one with them
+emits more — about twice the parser code on a large OpenAPI document — which is
+what a second, exact opinion on each definition costs. A `strict` or
+`stripUnknown` parser has no `coerceX` to agree with and is unchanged.
+
 `parse` and `parseStrict` are the same function name under two contracts, so
 asking for both is an error rather than a silent choice.
 
+### Moving off Ajv
+
+`coerceX` is built to replace Ajv compiled with `{ allErrors: true,
+coerceTypes: true }`, and it is better on each count: the answer, the speed and
+the safety of the input.
+
+**It accepts only what the schema accepts.** Anything `coerceX` hands back as
+valid, `validateX` has just accepted, and a differential fuzz over random
+schemas with `anyOf`, `oneOf`, `allOf` and `if`/`then`/`else` checks every
+accepted document against an Ajv that does not coerce. Where the two differ, it
+is on purpose:
+
+- **`null` is never coerced**, in either direction. Ajv reads `null` as `""`, `0`
+  or `false` for a string, number or boolean field, and reads those back as
+  `null`. A `null` usually means "not set", and turning it into a real value
+  erases that. Here it goes to the validator as written, and the validator
+  rejects it.
+- **Only clean numerals become numbers.** `" "`, `" 1 "`, `"0x10"`, `"Infinity"`
+  and `"1."` are rejected. Ajv turns them into `0`, `1`, `16`, a value JSON
+  cannot hold, and `1`. `"007"` and `"1e3"` are still coerced.
+- **At a union, a branch the value already matches wins.** Ajv coerces into the
+  first branch that will take the value. Given `anyOf: [{ type: 'string' }, {
+  const: false }]`, Ajv turns `false` into `"false"`; `coerceX` keeps `false`.
+  When no branch matches as written, each branch coerces the value its own way
+  and the result is taken only if every branch that then accepts it agrees.
+  Two different readings leave the value alone for the validator to report, so
+  the order the branches were written in never changes the answer.
+- **A branch that fails leaves nothing behind.** Ajv coerces in place while it
+  tries each branch, so under `oneOf: [{ type: 'integer' }, { type: 'string' }]`
+  it turns `0` into `"0"` while trying the string branch, sees two matches, and
+  rejects a valid document. `coerceX` accepts `0` as written.
+- **Coercion reaches every applicator.** Scalars are coerced through `$ref`,
+  `allOf` (each subschema in turn), `if`/`then`/`else` (toward `then` when the
+  value matches `if`, `else` otherwise), and union branches, nested to any depth.
+
+**It never touches the input.** Ajv coerces in place, so a caller that keeps its
+document has to clone it first. `coerceX` returns a new value that shares
+everything it did not touch, or the input itself when nothing needed coercing.
+
+**It is faster.** Against Ajv cloning first, so both leave the caller's document
+alone (`bun run bench:validators:coerce`, or
+`bench:validators:coerce:node`):
+
+| schema | runtime | valid input | needs coercing | cannot be coerced |
+|:--|:--|--:|--:|--:|
+| small (4 fields) | Bun | 5.4× | 1.7× | 1.5× |
+| small (4 fields) | Node | 9.9× | 2.1× | 2.2× |
+| order (nested + array) | Bun | 11× | 1.6× | 1.9× |
+| order (nested + array) | Node | 8.4× | 1.8× | 2.2× |
+| assert-loose | Bun | 19× | 1.4× | 3.0× |
+| assert-loose | Node | 36× | 1.6× | 3.1× |
+| config (unions via `$ref`) | Bun | 7.2× | 1.7× | 3.7× |
+| config (unions via `$ref`) | Node | 5.2× | 1.5× | 4.6× |
+
+<sub>Each cell is how many times faster `coerceX` is than Ajv on the same input,
+each engine timed in its own process (Bun 1.3.11, Node 22.22, Linux x64). A
+valid document is the common case and the widest gap: where `isX` is a
+standalone guard, `coerceX` answers it with that guard and hands the input
+straight back, without walking it. On valid input Ajv rewrites nothing, so it can
+also be timed without the clone; `coerceX` is still ahead there, by 1.2–3.3×.
+The config case is the shape `--coerce` exists for: every coercible scalar sits
+inside a union reached through `$ref`, and every union branch is tested by a
+named function rather than a closure built per call.</sub>
+
+The errors differ in one way worth knowing if you key diagnostics on
+`path + keyword + params`: an `additionalProperties` error points **at the
+undeclared key** (`/readme/example_requests`) where Ajv points at the object
+holding it (`/readme`). `params.additionalProperty` names the key in both.
+
 ---
 
 ## API
@@ -146,7 +227,8 @@ could import its 17 KiB of error types and runtime helpers.
 
 ## Is it faster?
 
-No, and it should not be. Ask this package for one mode and it emits **the exact
+Than the two engines it wraps? No, and it should not be. (Than Ajv, yes — see
+[Moving off Ajv](#moving-off-ajv).) Ask this package for one mode and it emits **the exact
 bytes** the engine that owns that mode emits — which the test suite pins per
 mode, by fingerprint, not by reading the output. Identical code cannot
 run at a different speed, so there is no runtime claim to make here and none is

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

@@ -6,6 +6,7 @@ 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 { planExactHalves } from "./generate-exact-half.js";
 import { generateFile } from "./generate-files.js";
 const readHelperSource = async (helper, importExt) => {
   const require2 = createRequire(import.meta.url);
@@ -32,10 +33,18 @@ const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logW
   const files = [];
   const usedHelpers = /* @__PURE__ */ new Set();
   const foldedSchema = foldNullable(rootSchema);
+  const nodes = [];
   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;
+    nodes.push({
+      node,
+      schema: extensions ? applySchemaExtensions(node.schema, node.filename, extensions) : node.schema
+    });
+  });
+  const exactHalves = typesOnly === true || strict === true || stripUnknown ? /* @__PURE__ */ new Map() : planExactHalves(nodes.map(({ node, schema }) => ({ typeName: node.typeName, schema, rootSchema: node.rootSchema })), typeSuffix);
+  for (const { node, schema: extended } of nodes) {
+    const exactHalf = exactHalves.get(node.typeName);
     const result = generateFile(extended, node.typeName, {
       selfFilename: node.filename,
       typesOnly: typesOnly ?? false,
@@ -51,12 +60,13 @@ const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logW
       ...strict !== void 0 ? { strict } : {},
       ...stripUnknown ? { stripUnknown } : {},
       ...caseInsensitive ? { caseInsensitive } : {},
+      ...exactHalf !== void 0 ? { exactHalf } : {},
       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);

package/dist/parsers/generators/generate-exact-half.d.ts

@@ -0,0 +1,50 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * The exact, coercing half of a coercing parser file: `matchesX`, a yes/no test
+ * that agrees with `validateX` on every value, and `coerceXInput`, the walk
+ * `coerceX` runs. `wrap` says whether `parseX` itself runs them ahead of its
+ * repair, or whether the file only carries them for another file to call.
+ */
+export type ExactHalf = {
+    readonly code: string;
+    readonly wrap: boolean;
+};
+/** The name of a definition's exact yes/no test. */
+export declare const exactMatcherName: (typeName: string) => string;
+/** The name of a definition's coercion walk, as the parser exports it. */
+export declare const exactCoercerName: (typeName: string) => string;
+/** The name the repairing parser takes when `parseX` is the wrapper in front of it. */
+export declare const repairParserName: (typeName: string) => string;
+/** One definition as the planner sees it. */
+export type ExactHalfNode = {
+    readonly typeName: string;
+    readonly schema: JSONSchema;
+    readonly rootSchema: Record<string, unknown>;
+};
+/**
+ * Decides which definitions of a coercing parser build carry the exact half,
+ * and emits it for each.
+ *
+ * Every definition whose own tree has a combinator is wrapped. Everything such
+ * a definition reaches through `$ref` carries the half without the wrapper,
+ * because the wrapped definition's test and walk call into it. A definition the
+ * emitters cannot express drops out, and so does everything that would have
+ * called into it, until what is left is closed — so a file never imports a half
+ * that was not written.
+ */
+export declare const planExactHalves: (nodes: readonly ExactHalfNode[], typeSuffix: string) => ReadonlyMap<string, ExactHalf>;
+/**
+ * The imports a file's exact half needs: each `$ref` target's test and walk that
+ * the half actually calls.
+ *
+ * Its own lines rather than names added to the parser's import collector. That
+ * collector walks only the positions the repairing parser reads, and the exact
+ * half reads them all — a `$ref` under `not`, inside `propertyNames`, beside
+ * another `$ref`. Two import statements from one module are fine; the same name
+ * imported twice is not, and the two sets of names never meet.
+ */
+export declare const exactHalfImports: (schema: JSONSchema, code: string, options: {
+    readonly selfFilename?: string;
+    readonly typeSuffix: string;
+    readonly importExt: 'js' | 'ts';
+}) => string[];

package/dist/parsers/generators/generate-exact-half.js

@@ -0,0 +1,165 @@
+import { identifierMentions } from "@amritk/helpers/identifier-mentions";
+import { readKey } from "@amritk/helpers/read-key";
+import { refToFilename } from "@amritk/helpers/ref-to-filename";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { generateCoerceWalk } from "../../validators/generators/generate-coerce-function.js";
+const exactMatcherName = (typeName) => `matches${typeName}`;
+const exactCoercerName = (typeName) => `coerce${typeName}Input`;
+const repairParserName = (typeName) => `_parse${typeName}Repair`;
+const COMBINATOR_KEYS = ["anyOf", "oneOf", "allOf", "if", "not"];
+const SINGLE_SUBSCHEMA_KEYS = [
+  "additionalProperties",
+  "additionalItems",
+  "contains",
+  "propertyNames",
+  "not",
+  "if",
+  "then",
+  "else",
+  "unevaluatedProperties",
+  "unevaluatedItems"
+];
+const SUBSCHEMA_LIST_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const SUBSCHEMA_MAP_KEYS = ["properties", "patternProperties", "dependentSchemas", "dependencies"];
+const scanOwnTree = (schema) => {
+  const refs = /* @__PURE__ */ new Set();
+  let combinator = false;
+  const visit = (node) => {
+    if (!isSchemaObject(node))
+      return;
+    const record = node;
+    const ref = readKey(record, "$ref");
+    if (typeof ref === "string")
+      refs.add(ref);
+    if (COMBINATOR_KEYS.some((key) => readKey(record, key) !== void 0))
+      combinator = true;
+    for (const key of SINGLE_SUBSCHEMA_KEYS)
+      visit(readKey(record, key));
+    const items = readKey(record, "items");
+    if (Array.isArray(items))
+      items.forEach(visit);
+    else
+      visit(items);
+    for (const key of SUBSCHEMA_LIST_KEYS) {
+      const list = readKey(record, key);
+      if (Array.isArray(list))
+        list.forEach(visit);
+    }
+    for (const key of SUBSCHEMA_MAP_KEYS) {
+      const map = readKey(record, key);
+      if (typeof map === "object" && map !== null && !Array.isArray(map)) {
+        for (const value of Object.values(map))
+          if (!Array.isArray(value))
+            visit(value);
+      }
+    }
+  };
+  visit(schema);
+  return { refs, combinator };
+};
+const emitExactHalf = (schema, typeName, typeSuffix, rootSchema, wrap) => {
+  let walk;
+  try {
+    walk = generateCoerceWalk(schema, {
+      typeSuffix,
+      rootSchema,
+      refCoercer: (ref) => exactCoercerName(refToName(ref, typeSuffix)),
+      refGuard: exactMatcherName,
+      hoistNamespace: "_exact",
+      withRootMatch: true
+    });
+  } catch {
+    return null;
+  }
+  const { declarations, expression, rootMatch } = walk;
+  const matcher = exactMatcherName(typeName);
+  const matcherSource = typeof rootMatch === "string" ? [
+    `export const ${matcher} = (${/\binput\b/.test(rootMatch) ? "input" : "_input"}: unknown): boolean => {`,
+    .../\b_path\b/.test(rootMatch) ? [`  const _path = ''`] : [],
+    rootMatch,
+    `}`
+  ].join("\n") : `export const ${matcher} = (_input: unknown): boolean => ${rootMatch === true}`;
+  const text = [...declarations, matcherSource].join("\n");
+  const needsErrorType = /\bValidationError\b/.test(text);
+  if (needsErrorType && typeName === "ValidationError")
+    return null;
+  const coercer = exactCoercerName(typeName);
+  const parts = [
+    ...needsErrorType ? ["type ValidationError = { message: string; path: string; keyword: string; params: Record<string, unknown> }"] : [],
+    ...declarations,
+    matcherSource,
+    `export const ${coercer} = (input: unknown): unknown => ${expression ?? "input"}`
+  ];
+  if (wrap) {
+    const walked = expression === null ? [] : [`  const value = ${coercer}(input)`, `  if (${matcher}(value)) return value as ${typeName}`];
+    parts.push([
+      `export const parse${typeName} = (input: unknown): ${typeName} => {`,
+      `  if (${matcher}(input)) return input as ${typeName}`,
+      ...walked,
+      `  return ${repairParserName(typeName)}(input)`,
+      `}`
+    ].join("\n"));
+  }
+  return parts.join("\n\n");
+};
+const planExactHalves = (nodes, typeSuffix) => {
+  const byName = new Map(nodes.map((node) => [node.typeName, node]));
+  const scans = new Map(nodes.map((node) => [node.typeName, scanOwnTree(node.schema)]));
+  const targetsOf = (typeName) => [...scans.get(typeName)?.refs ?? []].map((ref) => refToName(ref, typeSuffix));
+  const wrapped = new Set(nodes.filter((node) => scans.get(node.typeName)?.combinator === true).map((n) => n.typeName));
+  const closure = /* @__PURE__ */ new Set();
+  const queue = [...wrapped];
+  while (queue.length > 0) {
+    const name = queue.pop();
+    if (closure.has(name))
+      continue;
+    closure.add(name);
+    for (const target of targetsOf(name))
+      if (!closure.has(target))
+        queue.push(target);
+  }
+  const emitted = /* @__PURE__ */ new Map();
+  const failed = /* @__PURE__ */ new Set();
+  for (const name of closure) {
+    const node = byName.get(name);
+    const code = node === void 0 ? null : emitExactHalf(node.schema, name, typeSuffix, node.rootSchema, wrapped.has(name));
+    if (code === null)
+      failed.add(name);
+    else
+      emitted.set(name, code);
+  }
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const name of emitted.keys()) {
+      if (targetsOf(name).some((target) => failed.has(target) || !byName.has(target))) {
+        emitted.delete(name);
+        failed.add(name);
+        changed = true;
+      }
+    }
+  }
+  return new Map([...emitted].map(([name, code]) => [name, { code, wrap: wrapped.has(name) }]));
+};
+const exactHalfImports = (schema, code, options) => {
+  const mentions = identifierMentions(code);
+  const byFile = /* @__PURE__ */ new Map();
+  for (const ref of scanOwnTree(schema).refs) {
+    const filename = refToFilename(ref);
+    if (filename === options.selfFilename || byFile.has(filename))
+      continue;
+    const typeName = refToName(ref, options.typeSuffix);
+    const names = [exactMatcherName(typeName), exactCoercerName(typeName)].filter((name) => mentions(name));
+    if (names.length > 0)
+      byFile.set(filename, names);
+  }
+  return [...byFile].map(([filename, names]) => `import { ${names.join(", ")} } from './${filename}.${options.importExt}';`).sort();
+};
+export {
+  exactCoercerName,
+  exactHalfImports,
+  exactMatcherName,
+  planExactHalves,
+  repairParserName
+};

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

@@ -2,6 +2,7 @@ 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';
+import { type ExactHalf } from './generate-exact-half.js';
 /**
  * Options for controlling what gets generated in a file.
  */
@@ -99,6 +100,13 @@ type GenerateFileOptions = {
      * {@link UnknownKeysStrategy} for the trade-off between the two.
      */
     readonly unknownKeys?: UnknownKeysStrategy;
+    /**
+     * The exact, coercing half this definition carries, planned across the whole
+     * build by `planExactHalves`: a coercing parser that agrees with `coerceX` on
+     * every document `coerceX` accepts. Absent for a strict, stripping or
+     * types-only build, and for a definition that needs none.
+     */
+    readonly exactHalf?: ExactHalf;
 };
 /** Result of generating a single parser file. */
 export type GeneratedFileContent = {

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

@@ -2,6 +2,7 @@ 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 { exactHalfImports, repairParserName } from "./generate-exact-half.js";
 import { generateParserFunction, generateShapeValidator } from "./generate-parser-function.js";
 const generateFile = (schema, typeName, options) => {
   const typesOnly = options?.typesOnly === true;
@@ -44,7 +45,9 @@ const generateFile = (schema, typeName, options) => {
   });
   const unknownKeys = options?.unknownKeys ?? DEFAULT_UNKNOWN_KEYS;
   const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames, unknownKeys);
+  const exactHalf = options?.exactHalf;
   const parserFunction = generateParserFunction(schema, typeName, {
+    ...exactHalf?.wrap === true ? { entryName: repairParserName(typeName) } : {},
     useRefImports: true,
     typeSuffix,
     reservedNames,
@@ -59,7 +62,9 @@ const generateFile = (schema, typeName, options) => {
   });
   const combinedFunctions = `${shapeValidator}
 
-${parserFunction}`;
+${parserFunction}` + (exactHalf === void 0 ? "" : `
+
+${exactHalf.code}`);
   const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix, importExt);
   const imports = [
     ...collectImports(schema, {
@@ -72,6 +77,11 @@ ${parserFunction}`;
       // the functions the emitted code calls are one question about one text.
       usedIn: typeDefinition + "\n\n" + combinedFunctions
     }),
+    ...exactHalf === void 0 ? [] : exactHalfImports(schema, exactHalf.code, {
+      ...options?.selfFilename !== void 0 ? { selfFilename: options.selfFilename } : {},
+      typeSuffix,
+      importExt
+    }),
     ...helpers.imports
   ];
   let result = "";

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

@@ -4,6 +4,12 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * Options for controlling parser function generation behavior.
  */
 type GenerateParserOptions = {
+    /**
+     * The name to emit this definition's parser under, in place of `parseX`. Used
+     * when `parseX` is a wrapper that runs the exact, coercing half first and falls
+     * back to this parser only for a value no coercion can make valid.
+     */
+    readonly entryName?: string;
     /**
      * When true, properties with $ref will call the imported parser function
      * instead of inlining the validation logic. This is used when generating

package/dist/parsers/generators/generate-parser-function.js

@@ -12,14 +12,13 @@ import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
 import { findDiscriminator } from "../helpers/find-discriminator.js";
 import { getDiscriminatorValue } from "../helpers/get-discriminator-value.js";
 import { assertNoUnsupportedKeywords } from "./assert-supported-keywords.js";
-import { generateEnumCaseInsensitiveCoercion } from "./generate-enum-check.js";
+import { generateEnumCaseInsensitiveCoercion, generateEnumCheck } from "./generate-enum-check.js";
 import { generateBackstopAssertion, generateCompositionChecks, generateContainsCheck, generateKeyedValueChecks, generateObjectKeywordChecks, generateObjectSizeChecks, generateObjectStrictAssertion, generateScalarStrictAssertion, inlineAllOfMembers } from "./generate-strict-assertion.js";
 import { canEnforceUnion, generatePropertyTypeCheck, generateUnionCheck, getUnionBranches, hasFastPathBlockingKeyword, isExclusiveUnion, isInlineObjectArrayProperty, isInlineObjectProperty, isInlineUnionProperty, isUnionArrayProperty, shapeValidatorName } from "./generate-type-checks.js";
 import { generateUniqueItemsCheck } from "./generate-unique-items-check.js";
 import { generatePrefixItemsMap, generateValidationExpression, getPrefixItems, isCoercibleItemSchema, prefixItemsCapsLength } from "./generate-validation-expression.js";
-const generateParserName = (typeName) => {
-  return `parse${typeName}`;
-};
+let entryOverride = null;
+const generateParserName = (typeName) => entryOverride !== null && entryOverride.typeName === typeName ? entryOverride.name : `parse${typeName}`;
 const safeLiteralKey = (key) => key === "__proto__" ? '["__proto__"]' : safeKey(key);
 const isPropertyRequired = (key, schema) => {
   if (!isSchemaObject(schema)) {
@@ -224,6 +223,7 @@ const SCALAR_ROOT_CONSTRAINTS = [
   "exclusiveMaximum",
   "multipleOf"
 ];
+const COERCED_SCALAR_ROOT_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean"]);
 const isConstrainedScalarRoot = (schema) => {
   if (!isSchemaObject(schema) || !hasType(schema))
     return false;
@@ -472,11 +472,11 @@ ${assertions}
       return isPrimitive ? `export const ${functionName} = (input: unknown): ${typeName} => input === ${literal} ? input as ${typeName} : ${literal} as ${typeName};` : `export const ${functionName} = (input: unknown): ${typeName} => ${literal} as ${typeName};`;
     }
     if (hasEnum(schema) && schema.enum.length > 0) {
-      const values = JSON.stringify(schema.enum);
       const fallback = JSON.stringify(schema.enum[0]);
       const ci = unionCtx?.caseInsensitive ? generateEnumCaseInsensitiveCoercion("input", schema.enum, fallback) : null;
       const coerced = ci ? `(${ci})` : fallback;
-      return `export const ${functionName} = (input: unknown): ${typeName} => ${values}.includes(input as never) ? input as ${typeName} : ${coerced} as ${typeName};`;
+      const member = generateEnumCheck("input", schema.enum);
+      return `export const ${functionName} = (input: unknown): ${typeName} => ${member} ? input as ${typeName} : ${coerced} as ${typeName};`;
     }
     if (hasOneOf(schema) || hasAnyOf(schema)) {
       const branches = hasOneOf(schema) ? schema.oneOf : hasAnyOf(schema) ? schema.anyOf : [];
@@ -584,8 +584,22 @@ ${assertion}
   return ${returnExpr};
 };`;
   }
-  if (isConstrainedScalarRoot(schema)) {
-    const expr = generateValidationExpression("", schema, getDefaultValue(schema), true, unionCtx?.rootSchema, void 0, "input", true, unionCtx?.caseInsensitive);
+  if (isConstrainedScalarRoot(schema) || COERCED_SCALAR_ROOT_TYPES.has(schema.type)) {
+    const expr = generateValidationExpression(
+      "",
+      schema,
+      getDefaultValue(schema),
+      true,
+      unionCtx?.rootSchema,
+      void 0,
+      "input",
+      // A parser's `input` can be `undefined` — a parent building the default for
+      // a missing required property calls `parseX(undefined)` — and coercing that
+      // to the string `"undefined"` is worse than the type's own default. The
+      // constrained path keeps what it always passed.
+      isConstrainedScalarRoot(schema),
+      unionCtx?.caseInsensitive
+    );
     return `export const ${functionName} = (input: unknown): ${typeName} => (${expr}) as ${typeName};`;
   }
   switch (schema.type) {
@@ -847,10 +861,12 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
   const propertyKeys = Object.keys(schemaProps);
   const { objects: subTypeNames, arrayItems: subItemNames } = collectInlineSubTypes(schema, typeName, reservedNames);
   const preamble = [];
+  const prunable = /* @__PURE__ */ new Map();
   for (const [key, subName] of subTypeNames) {
     const propSchema = schemaProps[key];
     preamble.push(`type ${subName} = NonNullable<${typeName}>[${JSON.stringify(key)}];`);
     const subShapeValidator = generateShapeValidator(propSchema, subName, useRefImports, suffix, false, stripUnknown, reservedNames, unknownKeys);
+    prunable.set(subShapeValidator, `${shapeValidatorName(subName)}(`);
     preamble.push(subShapeValidator);
     preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema, reservedNames, caseInsensitive, subShapeValidator, unknownKeys));
   }
@@ -859,11 +875,14 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
     const itemSchema = propSchema.items;
     preamble.push(`type ${subName} = NonNullable<NonNullable<${typeName}>[${JSON.stringify(key)}]>[number];`);
     const itemShapeValidator = generateShapeValidator(itemSchema, subName, useRefImports, suffix, false, stripUnknown, reservedNames, unknownKeys);
+    prunable.set(itemShapeValidator, `${shapeValidatorName(subName)}(`);
     preamble.push(itemShapeValidator);
-    preamble.push(`const _every${subName} = (arr: readonly unknown[]): boolean => {
+    const everyLoop = `const _every${subName} = (arr: readonly unknown[]): boolean => {
   for (let i = 0; i < arr.length; i++) if (!${shapeValidatorName(subName)}(arr[i])) return false;
   return true;
-};`);
+};`;
+    prunable.set(everyLoop, `_every${subName}(`);
+    preamble.push(everyLoop);
     const unionBranches = strict ? null : getUnionBranches(itemSchema);
     const scoredItemParser = unionBranches === null ? null : generateScoredUnionParser(generateParserName(subName), subName, unionBranches, {
       useRefImports,
@@ -1373,9 +1392,21 @@ ${assertBodyLines.join("\n")}
   }
   lines.push(`}`);
   const fn = lines.join("\n");
-  if (preamble.length === 0)
+  let kept = preamble;
+  if (shapeValidatorSource !== void 0) {
+    let changed = true;
+    while (changed) {
+      const current = kept;
+      kept = current.filter((entry) => {
+        const call = prunable.get(entry);
+        return call === void 0 || fn.includes(call) || shapeValidatorSource.includes(call) || current.some((other) => other !== entry && other.includes(call));
+      });
+      changed = kept.length !== current.length;
+    }
+  }
+  if (kept.length === 0)
     return fn;
-  return `${preamble.join("\n\n")}
+  return `${kept.join("\n\n")}
 
 ${fn}`;
 };
@@ -1837,7 +1868,14 @@ const generateParserFunction = (schema, typeName, rawOptions) => {
       ...options.stripUnknown !== void 0 ? { stripUnknown: options.stripUnknown } : {}
     });
   }
-  return selectParserStrategy(schema, typeName, options);
+  if (options?.entryName === void 0)
+    return selectParserStrategy(schema, typeName, options);
+  entryOverride = { typeName, name: options.entryName };
+  try {
+    return selectParserStrategy(schema, typeName, options);
+  } finally {
+    entryOverride = null;
+  }
 };
 const shapeValidatorFunctionName = (typeName) => shapeValidatorName(typeName);
 const generateShapeValidator = (schema, typeName, useRefImports, suffix = "", exported = true, stripUnknown = false, reservedNames = NO_RESERVED_NAMES, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {

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

@@ -1,5 +1,5 @@
 /** Names (without `.ts`) of runtime helpers that can be embedded into generated output. */
-export type RuntimeHelperName = 'is-object' | 'validate-array' | 'validate-record' | 'has-ref';
+export type RuntimeHelperName = 'is-object' | 'validate-array' | 'validate-record' | 'has-ref' | 'coercion-runtime';
 /** Controls how generated parsers reference their runtime helpers. */
 export type HelpersMode = 'package' | 'embedded';
 export type CollectedHelpers = {

package/dist/parsers/helpers/collect-helpers.js

@@ -3,14 +3,27 @@ const PACKAGE_IMPORTS = {
   "validate-array": "import { validateArray } from '@amritk/helpers/validate-array';",
   "validate-record": "import { validateRecord } from '@amritk/helpers/validate-record';",
   // hasRef has historically lived in the schema-guards subpath; preserve that for package mode.
-  "has-ref": "import { hasRef } from '@amritk/helpers/schema-guards';"
+  "has-ref": "import { hasRef } from '@amritk/helpers/schema-guards';",
+  // Never used: the coercion runtime exports several functions and a file imports
+  // only the ones it calls, so its line is built per file (see below).
+  "coercion-runtime": ""
 };
 const EMBEDDED_NAMED_EXPORTS = {
   "is-object": "isObject",
   "validate-array": "validateArray",
   "validate-record": "validateRecord",
-  "has-ref": "hasRef"
+  "has-ref": "hasRef",
+  "coercion-runtime": ""
 };
+const COERCION_RUNTIME = [
+  "coerceScalar",
+  "coerceUnion",
+  "valuesEqual",
+  "allUnique",
+  "everyItem",
+  "escapePointer"
+];
+const COERCION_RUNTIME_USAGE = /\b(coerceScalar|coerceUnion|valuesEqual|allUnique|everyItem|escapePointer)\(/g;
 const embeddedImport = (helper, prefix, ext) => (
   // An explicit extension so the embedded-helper import resolves under Node ESM, not only Bun.
   `import { ${EMBEDDED_NAMED_EXPORTS[helper]} } from '${prefix}_helpers/${helper}.${ext}';`
@@ -57,6 +70,16 @@ const collectHelpers = (parserFunction, mode, helpersImportPrefix = "./", import
     imports.push(importFor("has-ref"));
     used.add("has-ref");
   }
+  const runtime = /* @__PURE__ */ new Set();
+  COERCION_RUNTIME_USAGE.lastIndex = 0;
+  for (let hit = COERCION_RUNTIME_USAGE.exec(parserFunction); hit !== null; hit = COERCION_RUNTIME_USAGE.exec(parserFunction)) {
+    runtime.add(hit[1]);
+  }
+  if (runtime.size > 0) {
+    const names = COERCION_RUNTIME.filter((name) => runtime.has(name)).join(", ");
+    imports.push(mode === "embedded" ? `import { ${names} } from '${helpersImportPrefix}_helpers/coercion-runtime.${importExt}';` : `import { ${names} } from '@amritk/helpers/coercion-runtime';`);
+    used.add("coercion-runtime");
+  }
   return { imports, used };
 };
 export {