@amritk/validation 0.3.2 → 0.4.1

package/AI.md

@@ -44,14 +44,16 @@ Every mode is reachable from `mjst` without dropping to the programmatic API:
 |:---|:---|
 | `types` | `--types-only` (alone), otherwise always emitted |
 | `guard`, `validate` | `--validators`, or `--validators-only` for no parser |
-| `check` | `--check` |
-| `coerce` | `--coerce` |
-| `repair` | `--repair` (emits `coerceX` too) |
+| `check` | `--validators --check` |
+| `coerce` | `--validators --coerce` |
+| `repair` | `--validators --repair` (emits `coerceX` too) |
 | `parse` | the default on any run that is not `--types-only`/`--validators-only` |
 | `parseStrict` | `--strict` |
 
 `--validators-only` is this package's own default (`['types', 'guard', 'validate']`)
 spelled as a flag: everything that judges a document, nothing that builds one.
+`--check`, `--coerce` and `--repair` shape the validator half, so the CLI rejects
+any of them without one of those two flags.
 
 ## Gotchas — where agents fail
 
@@ -83,10 +85,26 @@ spelled as a flag: everything that judges a document, nothing that builds one.
    validateX(v)` pays for both passes and is no faster than `validateX`.
 
 8. **It emits each engine's exact bytes.** A single-mode build is byte-identical
-   to what that engine emitted when it was its own package, so there is no runtime
-   difference to reason about and no speedup to claim — do not tell a user this is
-   faster. What it changes is that the whole matrix comes out as one type instead
-   of two, and that a build asking for no validator mode ships no
+   to what the engine that owns that mode emits when called directly, so there is
+   no runtime difference to reason about and no speedup to claim — do not tell a
+   user this is faster. What it changes is that the whole matrix comes out as one
+   type instead 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

@@ -74,6 +74,7 @@ so no two can disagree about whether a document is valid.
 | `types` | — | — | — | — |
 | `guard` | `isX(input): input is X` | — | a boolean | the first problem |
 | `validate` | `validateX(input)` | — | every error | the end |
+| `check` | `checkX(input)` | — | the first error | the first problem |
 | `coerce` | `coerceX(input)` | coerced | every error | the end |
 | `repair` | `repairX(input)` | repaired | repairs **and** errors | the end |
 | `parse` | `parseX(input)` | repaired | nothing | never fails |
@@ -84,7 +85,9 @@ it stops at the first thing wrong and builds no error object, which on invalid
 input is dramatically cheaper than reporting. `validate` is the other half: every
 error, each with a JSON Pointer, the keyword that rejected the value, and that
 keyword's own values. Reach for `guard` when the answer is a branch and
-`validate` when a human or an API client has to be told what to fix.
+`validate` when a human or an API client has to be told what to fix. `check` sits
+between them: `checkX` returns the same result type as `validateX`, holding only
+the error `validateX` would have reported first, and walks no further.
 
 **Coerce and repair, with or without the errors.** `coerceX` and `repairX` hand
 back the value *and* the diagnostics; `parseX` hands back only the value and
@@ -92,9 +95,103 @@ 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.
 
+That makes `repairX` an autofix tool rather than a stricter validator. It accepts
+documents `validateX` rejects (a missing required name gets one; an unknown
+`enum` value becomes the first member), and accepting only `valid` with an empty
+`repairs` gives exactly the verdicts `coerceX` gives. An empty `repairs` alone is
+not enough: a document nothing could repair comes back with none either, and
+`valid: false`. To reject a bad config, use `coerceX`. To hand back a fixed one,
+use `repairX`.
+
+**`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, and it is the difference
+  you will meet most: on a real config corpus it was nearly every case where Ajv
+  accepted and `coerceX` did not. 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 where the input has to survive.** 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 on these
+schemas, by 1.2–3.3×, but not on every one: on a large, union-heavy document
+that the caller lets Ajv coerce in place, Ajv can come out modestly ahead. The
+gap above is the clone, so it is real exactly where the caller cannot let Ajv
+mutate its input.
+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
@@ -115,10 +212,17 @@ asking for both is an error rather than a silent choice.
 | `options.readonly` | `boolean` | `false` | Emit `readonly` type members. |
 | `options.caseInsensitive` | `boolean` | `false` | Normalize a mis-cased string onto an `enum` member it matches. |
 | `options.helpersMode` | `'package' \| 'embedded'` | `'package'` | Where the parser half gets its runtime helpers. |
+| `options.helpersImportPrefix` | `string` | `'./'` | Prefix on emitted-helper import specifiers, when `helpersMode` is `'embedded'`. |
 | `options.extensions` | `SchemaExtensions` | — | Schema extensions, passed through to the parser half. |
+| `options.importExt` | `'js' \| 'ts'` | `'js'` | Extension on every emitted relative import. `'ts'` emits the on-disk paths, so the output runs under Node's type stripping with no build step. |
+| `options.logWarnings` | `boolean` | `false` | Print the parser half's warnings about the schema, such as a keyword it cannot enforce. |
 
 Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
 
+The package also exports `ALL_MODES` (every mode but `parseStrict`, for a caller
+who wants the lot) and the types `Mode`, `GenerateOptions`, `GeneratedFile` and
+`ImportExtension`.
+
 ---
 
 ## Output layout
@@ -127,6 +231,8 @@ Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; c
 config.ts         the type, plus isX / validateX / coerceX / repairX
 config.parse.ts   parseX, importing the type from ./config.js
 validation-result.ts   the shared error and result types, and the runtime helpers
+formats.ts        the format checks, only when `formats` enforces one the schema names
+_helpers/         the parser's runtime helpers, only when `helpersMode` is 'embedded'
 index.ts          a barrel over all of it
 ```
 
@@ -146,7 +252,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

@@ -17,9 +17,8 @@ import { generateBackstopAssertion, generateCompositionChecks, generateContainsC
 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;
@@ -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) => {