@amritk/generate-validators 0.13.1 → 0.15.0

package/AI.md

@@ -32,8 +32,9 @@ const files = await buildValidatorSchema(schema, 'Document')
    (you write them).
 3. **Output includes a shared `validation-result.ts`** (`ValidationError`,
    `ValidationResult`, helpers) plus the `index.ts` barrel.
-4. **`NaN` satisfies numeric bounds** (`minimum`/`maximum`/`multipleOf`) — differs
-   from Ajv. Draft-07 schemas are auto-upgraded to 2020-12.
+4. **`NaN` fails a *constrained* number** (`minimum`/`maximum`/`multipleOf` all
+   reject it) and satisfies a bare `{ "type": "number" }`, which is Ajv's answer
+   too. Draft-07 schemas are auto-upgraded to 2020-12.
 5. **`format` emits no check.** It stays an annotation, like the interpreter's
    default — but *not* like the interpreter run with `{ formats: 'all' }`
    (`@amritk/lint`, `createApi({ formats })`), which rejects strings a generated

package/README.md

@@ -95,6 +95,18 @@ if (!result.valid) {
 
 Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
 
+#### Names it will not emit
+
+Both name arguments are used as written — the root type name verbatim, the suffix
+appended to every `$ref`-derived name — so both can name something the output
+cannot say. Generation stops with the name and the reason rather than writing a
+file that fails in your build: a name that is not a plain TypeScript identifier
+(`'my-doc'`, `''`, `'123'`, `'class'`); a definition that would claim the
+`validation-result.ts` or `index.ts` filename; and one whose type name comes out
+as `ValidationResult` or `ValidationError`, which every generated file already
+imports. A type suffix that moves such a name clear — `ValidationErrorObject` — is
+no collision, and non-ASCII identifiers are fine, because TypeScript takes them.
+
 #### Referencing another document
 
 A `$ref` to a URI is resolvable once you hand over the document behind it:
@@ -143,6 +155,19 @@ The verdict is the contract and it matches the interpreter exactly; for that one
 shape `isX` is a weaker type guard than the type it names. Declare a `type` — as
 almost every real schema does — and the guard is exact again.
 
+**Values JSON cannot hold get an answer, not a surprise.** A generated validator
+is a plain function applied to whatever you hand it, so it can meet things
+`JSON.parse` never produces — and it answers each the way the interpreter and Ajv
+do. A key present with an `undefined` value is a value to judge, not an absent
+one, wherever a sweep found the key (`patternProperties`, a schema-form
+`additionalProperties`, `unevaluatedProperties`). A hole in a sparse array is an
+element that has to answer for itself, in the item loops, the tuple positions,
+`contains` and `unevaluatedItems` alike. `NaN` equals itself under `const`,
+`enum` and `uniqueItems`, so `[NaN, NaN]` is a duplicate pair while `[NaN, null]`
+is not. And a self-referential object reaches a verdict — the structural
+comparison stops at 512 levels — where it used to throw a `RangeError` out of a
+function whose signature promises a `ValidationResult`.
+
 **`format` emits no check.** JSON Schema treats `format` as an annotation, and so
 does this generator: `{ type: 'string', format: 'uuid' }` produces the `typeof`
 check and nothing more. That matches the interpreter's default, but *not* the
@@ -163,7 +188,10 @@ unresolvable or cyclic `$ref` at the same instance location, a walk deeper than
 eight applicators, and a node under an *inert* `additionalItems` — one with no
 array `items` to be the tail of, or with a `prefixItems` that took the positions
 out from under it. The draft-07 tail itself is validated, so the draft-07
-spelling of a schema whose 2020-12 spelling generates is accepted too.
+spelling of a schema whose 2020-12 spelling generates is accepted too. One
+difference worth knowing: the check is a single sweep, so its error is reported at
+the object or array — the shape Ajv reports too — where the interpreter names the
+individual key or index. The verdict is identical either way.
 
 One edge worth calling out: **`NaN` fails a constrained number but satisfies an
 unconstrained one.** Every bound is emitted as the negated *pass* condition
@@ -219,29 +247,36 @@ happy path it runs a single allocation-free boolean guard — a pure `&&` chain
 `typeof` checks (plus an `Object.keys().length` count when an object is closed
 with `additionalProperties: false`) — and `return true`s straight away, only
 calling a separate error-collecting function when something is actually wrong.
-Keeping the hot function tiny lets V8 optimise it aggressively, so a valid-input
+Keeping the hot function tiny lets the JIT optimise it aggressively, so a valid-input
 check beats every other library measured — including the build-time transformer
 typia — while still emitting full JSON-Pointer errors for invalid input, and
 emitting the validator stays far cheaper than compiling a schema at startup.
-Measured on Bun 1.3 (Linux x64), validating valid input at steady state:
+Measured on Bun 1.4 (Linux x64), validating valid input at steady state:
 
 | schema | mjst (generated) | typia (transformed) | ajv (compiled) | typebox (compiled) | zod |
 |:--|--:|--:|--:|--:|--:|
-| small (4 fields) | **~49M** ops/s | ~6.4M ops/s | ~11M ops/s | ~5.7M ops/s | ~2.4M ops/s |
-| order (nested + array) | **~11M** ops/s | ~2.5M ops/s | ~4M ops/s | ~2.4M ops/s | ~0.52M ops/s |
-| assert-loose | **~177M** ops/s | ~162M ops/s | ~46M ops/s | ~70M ops/s | ~3.9M ops/s |
-| assert-strict | **~164M** ops/s | ~146M ops/s | ~20M ops/s | ~44M ops/s | ~1.5M ops/s |
+| small (4 fields) | **~59M** ops/s | ~5.8M ops/s | ~10M ops/s | ~7.6M ops/s | ~2.2M ops/s |
+| order (nested + array) | **~9.5M** ops/s | ~2M ops/s | ~3.9M ops/s | ~3.3M ops/s | ~0.54M ops/s |
+| assert-loose | **~189M** ops/s | ~170M ops/s | ~44M ops/s | ~78M ops/s | ~5M ops/s |
+| assert-strict | **~104M** ops/s | ~68M ops/s | ~21M ops/s | ~42M ops/s | ~1.8M ops/s |
 
-The `assert-loose` / `assert-strict` rows are the exact shape used by
+The `assert-loose` / `assert-strict` rows use the same *shape* as
 [`moltar/typescript-runtime-type-benchmarks`](https://github.com/moltar/typescript-runtime-type-benchmarks)
 (seven scalar roots plus a nested object): the boolean guard keeps mjst ahead of
-typia on both, by ~10% on `assert-loose` and ~12% on `assert-strict` (with
-`additionalProperties: false`) — close enough that the two can trade the lead
-run-to-run. (typia and TypeBox still win the *invalid* path, where they bail on
-the first error rather than collecting a full error list.)
-
-Preparing a validator costs ~0.3–0.7 ms for mjst codegen and ~0.04–0.3 ms for a
-TypeBox `TypeCompiler` compile, versus ~7–11 ms for an Ajv compile. Every library
+typia on both, by ~11% on `assert-loose` — close enough that the two can trade
+the lead run-to-run — and by ~52% on `assert-strict` (with
+`additionalProperties: false`), where mjst counts keys once and typia does not.
+(typia and TypeBox still win the *invalid* path, where they bail on the first
+error rather than collecting a full error list.)
+
+They are **not** that project's numbers and they do not belong next to its
+leaderboard: the shape is shared, the harness is not, and the harness is worth
+an order of magnitude. See
+[Against the moltar harness](#against-the-moltar-harness) for the same functions
+measured under benny, the way the leaderboard measures them.
+
+Preparing a validator costs ~0.3–0.7 ms for mjst codegen and ~0.05–0.2 ms for a
+TypeBox `TypeCompiler` compile, versus ~13–17 ms for an Ajv compile. Every library
 agrees on every verdict; parity is asserted before timing.
 
 One caveat on the first two rows: their schemas declare `format` (`uuid`,
@@ -260,6 +295,94 @@ reproduce with:
 bun run bench
 ```
 
+### Against the moltar harness
+
+The table above is this package's own harness (`bench/measure.ts`): the
+validator is called directly over a pool of 32 distinct inputs, its verdict is
+folded into an escaping sink so nothing can be optimised away, and the median of
+21 timed trials is reported.
+
+The public leaderboard measures differently. Every operation there goes through
+[benny](https://github.com/caderek/benny) (benchmark.js) into moltar's
+`Benchmark` class, so the timed work is a call inside benchmark.js's compiled
+loop, then a second call through a class property, around a fixture that is one
+shared frozen module-level constant whose verdict `run()` throws away. That
+harness has a floor, and near the top of the range the floor is what gets
+measured.
+
+`bun run bench:moltar` runs exactly that harness over the same functions, always
+alongside a **no-op** control — a "validator" that checks nothing, which is the
+fastest number the harness can physically produce. One run on this machine
+(Linux x64, Bun 1.3.11 / Node 22.22, valid input):
+
+| harness | runtime | `assert-loose` | `assert-strict` |
+|:--|:--|--:|--:|
+| this package (`measure.ts`) | Bun | ~200M ops/s | ~185M ops/s |
+| benny, moltar's `Benchmark` | Node | ~100M ops/s | ~38M ops/s |
+| benny, moltar's `Benchmark` | Bun | ~70M ops/s | ~2.4M ops/s |
+| *no-op control, benny* | *Node* | *~120M ops/s* | *~120M ops/s* |
+| *no-op control, benny* | *Bun* | *~325M ops/s (±75%)* | *~325M ops/s (±75%)* |
+
+Read two things out of that. First, on Node the `assert-loose` figure sits
+within 20% of a validator that does nothing, so under that harness it is not a
+validator measurement at all: above that floor a faster validator cannot show
+up as a faster number, and the published leaderboard runs on CI hardware slower
+than this box, where the floor sits lower still. Second, `assert-strict` on Bun collapses to
+~2.4M because moltar's fixture is `Object.freeze({ … })` — see
+[Frozen inputs](#frozen-inputs).
+
+The harness makes no difference to correctness and every difference to the
+number, so quote the two separately or not at all. Both are reproducible here:
+
+```bash
+bun run bench          # this package's harness
+bun run bench:moltar   # benny, under the leaderboard's conditions
+```
+
+### Frozen inputs
+
+Closing an object with `additionalProperties: false` means proving no
+undeclared key is present, and every library answers that by enumerating keys:
+mjst's guard counts them (`Object.keys(obj).length === n`, exact because each
+declared property is required and already proven present), Ajv and Zod sweep
+with `for...in`, TypeBox runs its own sweep. On V8 that costs the same whatever
+the input looks like.
+
+On JavaScriptCore (Bun) it does not. Making an object non-extensible —
+`Object.freeze`, `Object.seal` or a bare `Object.preventExtensions` — turns off
+the engine's cached own-keys fast path, and *every* form of key enumeration
+falls back to a generic walk: `Object.keys`, `Object.getOwnPropertyNames`,
+`Reflect.ownKeys` and `for...in` alike. Property reads are untouched (a frozen
+object reads at full speed), so the whole cost lands on the extra-key sweep, and
+therefore on strict schemas only. Frozen inputs are ordinary — a config object
+frozen at startup, a shared fixture, a module-level constant — so `bun run bench`
+carries `small (4 fields, frozen)` and `assert-strict (frozen)` cases to keep it
+measured. One run on this machine (Linux x64, Bun 1.3.11), valid input:
+
+| `assert-strict` | mutable input | frozen input |
+|:--|--:|--:|
+| mjst (generated) | ~185M ops/s | ~1.7M ops/s |
+| typia (transformed) | ~68M ops/s | ~1.7M ops/s |
+| typebox (compiled) | ~46M ops/s | ~1.7M ops/s |
+| ajv (compiled) | ~24M ops/s | ~1.5M ops/s |
+| zod | ~1.4M ops/s | ~0.7M ops/s |
+
+It is an engine-level cliff, not an mjst one: every compiled or generated strict
+validator lands within a hair of the same number, because they are all paying
+the same engine slow path. The generated code keeps the key count anyway. Every
+alternative was measured and every one is worse overall. `Object.values(obj)`
+and `Object.keys({ ...obj })` sidestep the cliff, but on the ordinary mutable
+path they cost 28–37× under JSC and 2–7× under V8. Branching on
+`Object.isExtensible(obj)` first keeps the mutable path recognisable, at ~4×
+under JSC — and makes V8 slower in *both* directions (~2× mutable, ~7× frozen),
+where there was no cliff to fix in the first place. Trading a large, portable
+regression for a smaller win on one engine is not a good deal, so the sweep
+stays as it is.
+
+If it matters for your workload: validate before freezing (the verdict is the
+same either way — `src/generators/frozen-input.test.ts` pins that), or run on a
+V8 runtime, where the cliff does not exist.
+
 ---
 
 ## Related packages

package/dist/generators/assert-unevaluated-generatable.js

@@ -1,3 +1,4 @@
+import { declaresKey, readKey } from "@amritk/helpers/read-key";
 import { unevaluatedItemsExpr, unevaluatedPropertiesExpr } from "./unevaluated-match.js";
 const UNPROVABLE_COVERAGE_MESSAGE = (keyword) => `unsupported "${keyword}": working out which keys the schema already evaluated means reading through an applicator this generator cannot follow inline \u2014 an unresolvable or cyclic "$ref", or a "$dynamicRef", whose target is only known at validation time. Validate this schema with \`@amritk/runtime-validators\` instead.`;
 const SINGLE_SUBSCHEMA_KEYS = [
@@ -13,12 +14,12 @@ const SINGLE_SUBSCHEMA_KEYS = [
 ];
 const SUBSCHEMA_LIST_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
 const SUBSCHEMA_MAP_KEYS = ["properties", "patternProperties", "dependentSchemas", "dependencies"];
-const additionalItemsIsEnforced = (node) => Array.isArray(node["items"]) && !Array.isArray(node["prefixItems"]);
+const additionalItemsIsEnforced = (node) => Array.isArray(readKey(node, "items")) && !Array.isArray(readKey(node, "prefixItems"));
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const check = (node, typeName, rootSchema, match, enforced) => {
   const record = node;
   for (const keyword of ["unevaluatedProperties", "unevaluatedItems"]) {
-    if (!(keyword in record) || record[keyword] === true)
+    if (!declaresKey(record, keyword) || record[keyword] === true)
       continue;
     if (!enforced) {
       throw new Error(`[${typeName}] unsupported "${keyword}": it sits under "additionalItems", a subschema position this generator does not enforce, so the check would never run. Validate this schema with \`@amritk/runtime-validators\` instead.`);
@@ -32,34 +33,34 @@ const assertUnevaluatedGeneratable = (schema, typeName, rootSchema, match) => {
   const visit = (node, enforced) => {
     if (!isRecord(node))
       return;
-    if ("unevaluatedProperties" in node || "unevaluatedItems" in node) {
+    if (declaresKey(node, "unevaluatedProperties") || declaresKey(node, "unevaluatedItems")) {
       check(node, typeName, rootSchema, match, enforced);
     }
     for (const key of SINGLE_SUBSCHEMA_KEYS) {
-      if (key in node)
+      if (declaresKey(node, key))
         visit(node[key], enforced);
     }
-    const items = node["items"];
+    const items = readKey(node, "items");
     if (Array.isArray(items))
       for (const entry of items)
         visit(entry, enforced);
     else if (items !== void 0)
       visit(items, enforced);
     for (const key of SUBSCHEMA_LIST_KEYS) {
-      const list = node[key];
+      const list = readKey(node, key);
       if (Array.isArray(list))
         for (const entry of list)
           visit(entry, enforced);
     }
     for (const key of SUBSCHEMA_MAP_KEYS) {
-      const map = node[key];
+      const map = readKey(node, key);
       if (!isRecord(map))
         continue;
       for (const entry of Object.values(map))
         if (!Array.isArray(entry))
           visit(entry, enforced);
     }
-    if ("additionalItems" in node)
+    if (declaresKey(node, "additionalItems"))
       visit(node["additionalItems"], enforced && additionalItemsIsEnforced(node));
   };
   visit(schema, true);

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

@@ -11,7 +11,7 @@ export type GeneratedFile = {
  * types plus the helpers emitted code calls as free identifiers. Exported so tests
  * can evaluate the very source that ships instead of reimplementing it.
  */
-export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation error with a human-readable message and a JSON Pointer\n * path indicating where in the document the error occurred.\n */\nexport type ValidationError = {\n  message: string\n  path: string\n}\n\n/**\n * The result of a generated validator function.\n * Returns `true` when the input is valid, or an object with `valid: false`\n * and a list of errors when it is not.\n */\nexport type ValidationResult = true | { valid: false; errors: ValidationError[] }\n\n/**\n * Structural deep equality used by generated `const` checks. Objects compare by\n * their key sets rather than serialization, so `{ a: 1, b: 2 }` and\n * `{ b: 2, a: 1 }` are equal \u2014 unlike `JSON.stringify`, which is key-order\n * sensitive and would reject a reordered-but-equal value.\n */\nexport const valuesEqual = (a: unknown, b: unknown): boolean => {\n  if (a === b) return true\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false\n  const aArray = Array.isArray(a)\n  const bArray = Array.isArray(b)\n  if (aArray !== bArray) return false\n  if (aArray) {\n    const aa = a as unknown[]\n    const bb = b as unknown[]\n    if (aa.length !== bb.length) return false\n    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i])) return false\n    return true\n  }\n  const ao = a as Record<string, unknown>\n  const bo = b as Record<string, unknown>\n  const keys = Object.keys(ao)\n  if (keys.length !== Object.keys(bo).length) return false\n  for (const key of keys) {\n    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key])) return false\n  }\n  return true\n}\n\n/**\n * True when every element of `arr` is distinct under structural equality\n * ({@link valuesEqual}). Backs generated `uniqueItems` checks whose items may be\n * objects or arrays, where a `JSON.stringify` dedupe key would be key-order\n * sensitive and let a reordered-but-equal duplicate (`{ a: 1, b: 2 }` vs\n * `{ b: 2, a: 1 }`) slip through. A native `Set` dedupes the all-primitive case\n * in one linear pass; object/array elements fall back to an exact pairwise\n * structural comparison.\n */\nexport const allUnique = (arr: readonly unknown[]): boolean => {\n  const len = arr.length\n  if (len < 2) return true\n  let allPrimitive = true\n  for (let i = 0; i < len; i++) {\n    const v = arr[i]\n    if (v !== null && typeof v === 'object') {\n      allPrimitive = false\n      break\n    }\n  }\n  if (allPrimitive) return new Set(arr).size === len\n  for (let i = 0; i < len; i++) {\n    for (let j = i + 1; j < len; j++) {\n      if (valuesEqual(arr[i], arr[j])) return false\n    }\n  }\n  return true\n}\n\n/**\n * Escapes one JSON Pointer segment (RFC 6901): `~` \u2192 `~0`, `/` \u2192 `~1`, in that\n * order. Generated error paths are built from *runtime* keys wherever the schema\n * did not name them \u2014 a `patternProperties` match, an `additionalProperties`\n * sweep, a `propertyNames` loop \u2014 and a key containing a `/` would otherwise read\n * back as two segments, so an error on `{\"a/b\": \u2026}` pointed at `/a/b`, which is\n * the child `b` of a property `a`. Keys the schema *does* name are escaped at\n * generation time instead, and `@amritk/runtime-validators` escapes the same way,\n * so all three agree.\n *\n * The `indexOf` pre-test keeps the common key \u2014 no `/`, no `~` \u2014 off the replace\n * path entirely, which is what the interpreter does for the same reason.\n */\nexport const escapePointer = (key: string): string =>\n  key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key\n";
+export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation error with a human-readable message and a JSON Pointer\n * path indicating where in the document the error occurred.\n */\nexport type ValidationError = {\n  message: string\n  path: string\n}\n\n/**\n * The result of a generated validator function.\n * Returns `true` when the input is valid, or an object with `valid: false`\n * and a list of errors when it is not.\n */\nexport type ValidationResult = true | { valid: false; errors: ValidationError[] }\n\n/**\n * How deep a structural comparison walks before it gives up and answers \"not\n * equal\".\n *\n * JSON data is acyclic, but a generated validator is a plain function applied to\n * whatever in-memory value a caller hands it \u2014 and a self-referential object\n * reaching a `const` / `enum` / `uniqueItems` check used to recurse until the\n * stack overflowed, so `validateFoo` threw a `RangeError` instead of returning\n * the `ValidationResult` its signature promises. The cap turns that into an\n * ordinary \"these are different\" without ever coming near real data;\n * `@amritk/runtime-validators` guards its own `deepEqual` at the same depth.\n */\nconst MAX_EQUAL_DEPTH = 512\n\n/**\n * Structural deep equality used by generated `const` checks. Objects compare by\n * their key sets rather than serialization, so `{ a: 1, b: 2 }` and\n * `{ b: 2, a: 1 }` are equal \u2014 unlike `JSON.stringify`, which is key-order\n * sensitive and would reject a reordered-but-equal value.\n */\nexport const valuesEqual = (a: unknown, b: unknown, depth = 0): boolean => {\n  // SameValueZero: `===` settles every primitive except `NaN`, which counts as\n  // equal to itself here. That is what the native `Set` in {@link allUnique} does,\n  // what Ajv does, and what the interpreter's `deepEqual` does \u2014 leaving it out\n  // made a `NaN` nested inside an object compare unequal to itself, so the same\n  // array was \"unique\" here and \"duplicated\" everywhere else.\n  if (a === b || (Number.isNaN(a) && Number.isNaN(b))) return true\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false\n  if (depth >= MAX_EQUAL_DEPTH) return false\n  const aArray = Array.isArray(a)\n  const bArray = Array.isArray(b)\n  if (aArray !== bArray) return false\n  if (aArray) {\n    const aa = a as unknown[]\n    const bb = b as unknown[]\n    if (aa.length !== bb.length) return false\n    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i], depth + 1)) return false\n    return true\n  }\n  const ao = a as Record<string, unknown>\n  const bo = b as Record<string, unknown>\n  const keys = Object.keys(ao)\n  if (keys.length !== Object.keys(bo).length) return false\n  for (const key of keys) {\n    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key], depth + 1)) return false\n  }\n  return true\n}\n\n/**\n * A cheap, order-independent structural hash consistent with {@link valuesEqual}:\n * equal values always hash the same. It buckets candidate-equal elements in\n * {@link allUnique} so the exact comparison only ever runs inside a bucket.\n *\n * Object keys are folded commutatively (XOR) so key order does not change the\n * hash, and `NaN` / `-0` collapse the way SameValueZero does. Depth-capped like\n * {@link valuesEqual}: an over-deep value simply shares a bucket and is settled by\n * the (also capped) comparison, so the cap can cost a little time and never a\n * wrong answer. This is the same hash `@amritk/runtime-validators` uses.\n */\nconst structuralHash = (value: unknown, depth = 0): number => {\n  if (value === null) return 0x1a2b3c\n  const t = typeof value\n  if (t === 'number') {\n    const n = value as number\n    return Number.isNaN(n) ? 0x7ff8 : n === 0 ? 0 : Math.trunc(n * 2654435761) | 0\n  }\n  if (t === 'string') {\n    const s = value as string\n    let h = 0x811c9dc5\n    for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)\n    return h | 0\n  }\n  if (t === 'boolean') return value ? 1 : 2\n  if (t !== 'object') return 0x5eed\n  if (depth >= MAX_EQUAL_DEPTH) return 0xdee9\n  if (Array.isArray(value)) {\n    let h = 0x12345 ^ value.length\n    for (let i = 0; i < value.length; i++) h = (Math.imul(h, 31) + structuralHash(value[i], depth + 1)) | 0\n    return h | 0\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj)\n  let h = 0xabcde ^ keys.length\n  for (const k of keys) {\n    let kh = 0x811c9dc5\n    for (let i = 0; i < k.length; i++) kh = Math.imul(kh ^ k.charCodeAt(i), 0x01000193)\n    h = (h ^ (Math.imul(kh, 0x9e3779b1) + structuralHash(obj[k], depth + 1))) | 0\n  }\n  return h | 0\n}\n\n/**\n * True when every element of `arr` is distinct under structural equality\n * ({@link valuesEqual}). Backs generated `uniqueItems` checks whose items may be\n * objects or arrays, where a `JSON.stringify` dedupe key would be key-order\n * sensitive and let a reordered-but-equal duplicate (`{ a: 1, b: 2 }` vs\n * `{ b: 2, a: 1 }`) slip through.\n *\n * A native `Set` dedupes the all-primitive case in one linear pass. Object and\n * array elements are bucketed by {@link structuralHash} first, so the exact\n * comparison runs only against elements that could actually be equal: an array of\n * distinct objects costs ~O(n) instead of the O(n\u00B2) an exhaustive pairwise sweep\n * charged \u2014 4 000 rows took over half a second of pure comparison before, which\n * is a lot to hand an unauthenticated caller.\n */\nexport const allUnique = (arr: readonly unknown[]): boolean => {\n  const len = arr.length\n  if (len < 2) return true\n  let allPrimitive = true\n  for (let i = 0; i < len; i++) {\n    const v = arr[i]\n    if (v !== null && typeof v === 'object') {\n      allPrimitive = false\n      break\n    }\n  }\n  if (allPrimitive) return new Set(arr).size === len\n  const buckets = new Map<number, unknown[]>()\n  for (let i = 0; i < len; i++) {\n    const item = arr[i]\n    const hash = structuralHash(item)\n    const bucket = buckets.get(hash)\n    if (bucket === undefined) {\n      buckets.set(hash, [item])\n      continue\n    }\n    for (const seen of bucket) if (valuesEqual(seen, item)) return false\n    bucket.push(item)\n  }\n  return true\n}\n\n/**\n * Escapes one JSON Pointer segment (RFC 6901): `~` \u2192 `~0`, `/` \u2192 `~1`, in that\n * order. Generated error paths are built from *runtime* keys wherever the schema\n * did not name them \u2014 a `patternProperties` match, an `additionalProperties`\n * sweep, a `propertyNames` loop \u2014 and a key containing a `/` would otherwise read\n * back as two segments, so an error on `{\"a/b\": \u2026}` pointed at `/a/b`, which is\n * the child `b` of a property `a`. Keys the schema *does* name are escaped at\n * generation time instead, and `@amritk/runtime-validators` escapes the same way,\n * so all three agree.\n *\n * The `indexOf` pre-test keeps the common key \u2014 no `/`, no `~` \u2014 off the replace\n * path entirely, which is what the interpreter does for the same reason.\n */\nexport const escapePointer = (key: string): string =>\n  key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key\n";
 /**
  * Builds all TypeScript validator files from a JSON Schema by traversing all
  * `$ref` / `$dynamicRef` references recursively (via the shared

package/dist/generators/build-schema.js

@@ -17,15 +17,35 @@ export type ValidationError = {
  */
 export type ValidationResult = true | { valid: false; errors: ValidationError[] }
 
+/**
+ * How deep a structural comparison walks before it gives up and answers "not
+ * equal".
+ *
+ * JSON data is acyclic, but a generated validator is a plain function applied to
+ * whatever in-memory value a caller hands it \u2014 and a self-referential object
+ * reaching a \`const\` / \`enum\` / \`uniqueItems\` check used to recurse until the
+ * stack overflowed, so \`validateFoo\` threw a \`RangeError\` instead of returning
+ * the \`ValidationResult\` its signature promises. The cap turns that into an
+ * ordinary "these are different" without ever coming near real data;
+ * \`@amritk/runtime-validators\` guards its own \`deepEqual\` at the same depth.
+ */
+const MAX_EQUAL_DEPTH = 512
+
 /**
  * Structural deep equality used by generated \`const\` checks. Objects compare by
  * their key sets rather than serialization, so \`{ a: 1, b: 2 }\` and
  * \`{ b: 2, a: 1 }\` are equal \u2014 unlike \`JSON.stringify\`, which is key-order
  * sensitive and would reject a reordered-but-equal value.
  */
-export const valuesEqual = (a: unknown, b: unknown): boolean => {
-  if (a === b) return true
+export const valuesEqual = (a: unknown, b: unknown, depth = 0): boolean => {
+  // SameValueZero: \`===\` settles every primitive except \`NaN\`, which counts as
+  // equal to itself here. That is what the native \`Set\` in {@link allUnique} does,
+  // what Ajv does, and what the interpreter's \`deepEqual\` does \u2014 leaving it out
+  // made a \`NaN\` nested inside an object compare unequal to itself, so the same
+  // array was "unique" here and "duplicated" everywhere else.
+  if (a === b || (Number.isNaN(a) && Number.isNaN(b))) return true
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+  if (depth >= MAX_EQUAL_DEPTH) return false
   const aArray = Array.isArray(a)
   const bArray = Array.isArray(b)
   if (aArray !== bArray) return false
@@ -33,7 +53,7 @@ export const valuesEqual = (a: unknown, b: unknown): boolean => {
     const aa = a as unknown[]
     const bb = b as unknown[]
     if (aa.length !== bb.length) return false
-    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i])) return false
+    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i], depth + 1)) return false
     return true
   }
   const ao = a as Record<string, unknown>
@@ -41,19 +61,67 @@ export const valuesEqual = (a: unknown, b: unknown): boolean => {
   const keys = Object.keys(ao)
   if (keys.length !== Object.keys(bo).length) return false
   for (const key of keys) {
-    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key])) return false
+    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key], depth + 1)) return false
   }
   return true
 }
 
+/**
+ * A cheap, order-independent structural hash consistent with {@link valuesEqual}:
+ * equal values always hash the same. It buckets candidate-equal elements in
+ * {@link allUnique} so the exact comparison only ever runs inside a bucket.
+ *
+ * Object keys are folded commutatively (XOR) so key order does not change the
+ * hash, and \`NaN\` / \`-0\` collapse the way SameValueZero does. Depth-capped like
+ * {@link valuesEqual}: an over-deep value simply shares a bucket and is settled by
+ * the (also capped) comparison, so the cap can cost a little time and never a
+ * wrong answer. This is the same hash \`@amritk/runtime-validators\` uses.
+ */
+const structuralHash = (value: unknown, depth = 0): number => {
+  if (value === null) return 0x1a2b3c
+  const t = typeof value
+  if (t === 'number') {
+    const n = value as number
+    return Number.isNaN(n) ? 0x7ff8 : n === 0 ? 0 : Math.trunc(n * 2654435761) | 0
+  }
+  if (t === 'string') {
+    const s = value as string
+    let h = 0x811c9dc5
+    for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)
+    return h | 0
+  }
+  if (t === 'boolean') return value ? 1 : 2
+  if (t !== 'object') return 0x5eed
+  if (depth >= MAX_EQUAL_DEPTH) return 0xdee9
+  if (Array.isArray(value)) {
+    let h = 0x12345 ^ value.length
+    for (let i = 0; i < value.length; i++) h = (Math.imul(h, 31) + structuralHash(value[i], depth + 1)) | 0
+    return h | 0
+  }
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj)
+  let h = 0xabcde ^ keys.length
+  for (const k of keys) {
+    let kh = 0x811c9dc5
+    for (let i = 0; i < k.length; i++) kh = Math.imul(kh ^ k.charCodeAt(i), 0x01000193)
+    h = (h ^ (Math.imul(kh, 0x9e3779b1) + structuralHash(obj[k], depth + 1))) | 0
+  }
+  return h | 0
+}
+
 /**
  * True when every element of \`arr\` is distinct under structural equality
  * ({@link valuesEqual}). Backs generated \`uniqueItems\` checks whose items may be
  * objects or arrays, where a \`JSON.stringify\` dedupe key would be key-order
  * sensitive and let a reordered-but-equal duplicate (\`{ a: 1, b: 2 }\` vs
- * \`{ b: 2, a: 1 }\`) slip through. A native \`Set\` dedupes the all-primitive case
- * in one linear pass; object/array elements fall back to an exact pairwise
- * structural comparison.
+ * \`{ b: 2, a: 1 }\`) slip through.
+ *
+ * A native \`Set\` dedupes the all-primitive case in one linear pass. Object and
+ * array elements are bucketed by {@link structuralHash} first, so the exact
+ * comparison runs only against elements that could actually be equal: an array of
+ * distinct objects costs ~O(n) instead of the O(n\xB2) an exhaustive pairwise sweep
+ * charged \u2014 4 000 rows took over half a second of pure comparison before, which
+ * is a lot to hand an unauthenticated caller.
  */
 export const allUnique = (arr: readonly unknown[]): boolean => {
   const len = arr.length
@@ -67,10 +135,17 @@ export const allUnique = (arr: readonly unknown[]): boolean => {
     }
   }
   if (allPrimitive) return new Set(arr).size === len
+  const buckets = new Map<number, unknown[]>()
   for (let i = 0; i < len; i++) {
-    for (let j = i + 1; j < len; j++) {
-      if (valuesEqual(arr[i], arr[j])) return false
+    const item = arr[i]
+    const hash = structuralHash(item)
+    const bucket = buckets.get(hash)
+    if (bucket === undefined) {
+      buckets.set(hash, [item])
+      continue
     }
+    for (const seen of bucket) if (valuesEqual(seen, item)) return false
+    bucket.push(item)
   }
   return true
 }
@@ -91,6 +166,48 @@ export const allUnique = (arr: readonly unknown[]): boolean => {
 export const escapePointer = (key: string): string =>
   key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key
 `;
+const RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set(["ValidationResult", "ValidationError"]);
+const TYPE_NAME = /^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u;
+const RESERVED_WORDS = /* @__PURE__ */ new Set([
+  "await",
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "enum",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "new",
+  "null",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield"
+]);
 const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas) => {
   const files = [];
   walkRefGraph(rootSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
@@ -99,6 +216,15 @@ const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", s
       const purpose = node.filename === "index" ? "the generated barrel" : "the generated validators' runtime contract";
       throw new Error(`${owner} generates the file "${node.filename}.ts", which is reserved for ${purpose}. Rename the definition (or pass a different root type name) so it gets a file of its own.`);
     }
+    if (!TYPE_NAME.test(node.typeName) || RESERVED_WORDS.has(node.typeName)) {
+      const owner = node.isRoot ? "the root type name" : `the name "${node.ref}" derives`;
+      const suffixNote = typeSuffix === "" ? "" : ` (with the type suffix "${typeSuffix}")`;
+      throw new Error(`${owner}${suffixNote}, "${node.typeName}", is not a TypeScript type name, so the generated file would not parse. Pass a name that is a plain identifier \u2014 letters, digits, "_" and "$", not starting with a digit, and not a reserved word.`);
+    }
+    if (RESERVED_TYPE_NAMES.has(node.typeName)) {
+      const owner = node.isRoot ? `the root type name "${node.typeName}"` : `"${node.ref}"`;
+      throw new Error(`${owner} generates the type "${node.typeName}", which every generated file already imports from "validation-result.ts". Rename the definition (or pass a different root type name or type suffix) so the two names do not collide.`);
+    }
     const content = generateValidatorFile(node.schema, node.typeName, {
       rootSchema: node.rootSchema,
       typeSuffix,

package/dist/generators/collect-emitted-refs.js

@@ -1,11 +1,12 @@
+import { declaresKey, readKey } from "@amritk/helpers/read-key";
 import { isSchemaObject } from "@amritk/helpers/schema-guards";
 import { foldsToConstant } from "./folds-to-constant.js";
 import { tupleShapeOf } from "./tuple-shape.js";
 import { unevaluatedItemsExpr, unevaluatedPropertiesExpr } from "./unevaluated-match.js";
 const armsOf = (schema) => {
-  if (!("if" in schema))
+  if (!declaresKey(schema, "if"))
     return [];
-  const condition = schema["if"];
+  const condition = readKey(schema, "if");
   if (!isSchemaObject(condition) && typeof condition !== "boolean")
     return [];
   const decided = foldsToConstant(condition);
@@ -24,14 +25,15 @@ const collectEmittedRefs = (value, refs = [], rootSchema, includeTypeOnly = fals
     return refs;
   }
   const schema = value;
-  if (rootSchema !== void 0 && ("unevaluatedProperties" in schema || "unevaluatedItems" in schema)) {
+  if (rootSchema !== void 0 && (declaresKey(schema, "unevaluatedProperties") || declaresKey(schema, "unevaluatedItems"))) {
     collectCoverageRefs(schema, refs, rootSchema);
   }
-  if (typeof schema["$ref"] === "string") {
-    refs.push(schema["$ref"]);
+  const ref = readKey(schema, "$ref");
+  if (typeof ref === "string") {
+    refs.push(ref);
   }
   for (const mapKey of ["properties", "patternProperties", "dependentSchemas", "dependencies"]) {
-    const map = schema[mapKey];
+    const map = readKey(schema, mapKey);
     if (typeof map === "object" && map !== null && !Array.isArray(map)) {
       for (const sub of Object.values(map))
         collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly);
@@ -40,8 +42,8 @@ const collectEmittedRefs = (value, refs = [], rootSchema, includeTypeOnly = fals
   const { tuple, tail } = tupleShapeOf(schema);
   if (tail !== void 0)
     collectEmittedRefs(tail, refs, rootSchema, includeTypeOnly);
-  if (includeTypeOnly && Array.isArray(schema["items"])) {
-    const additional = schema["additionalItems"];
+  if (includeTypeOnly && Array.isArray(readKey(schema, "items"))) {
+    const additional = readKey(schema, "additionalItems");
     if (additional !== void 0 && additional !== tail) {
       collectEmittedRefs(additional, refs, rootSchema, includeTypeOnly);
     }
@@ -66,11 +68,11 @@ const collectEmittedRefs = (value, refs = [], rootSchema, includeTypeOnly = fals
     "unevaluatedProperties",
     "unevaluatedItems"
   ]) {
-    if (key in schema)
+    if (declaresKey(schema, key))
       collectEmittedRefs(schema[key], refs, rootSchema, includeTypeOnly);
   }
   for (const key of ["oneOf", "anyOf", "allOf"]) {
-    const list = schema[key];
+    const list = readKey(schema, key);
     if (!Array.isArray(list))
       continue;
     for (const sub of list)

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

@@ -18,6 +18,28 @@ type CollectValidatorImportsOptions = {
      * match the suffix used when generating the referenced files. Defaults to `''`.
      */
     readonly typeSuffix?: string;
+    /**
+     * Whether the file being generated reads each half of a `$ref`'s import — the
+     * type, the validator, or both.
+     *
+     * The two halves come apart in both directions. A `$ref` in a position the type
+     * generator does not read (an `if` arm, whose whole node it types `unknown`) is
+     * called and never named; one in a position only the *type* reads (a tuple's
+     * rest, taken from `additionalItems`) is named and never called; and a ref
+     * inside a branch that folded away is neither. Importing a half nothing reads
+     * leaves it unused, which is `TS6133` in the generated file for any consumer
+     * with `noUnusedLocals` — this repo, and anything inheriting its flags.
+     *
+     * Defaults to "both", which is what every caller wanted before anyone asked the
+     * question.
+     */
+    readonly reads?: (names: {
+        readonly typeName: string;
+        readonly validatorName: string;
+    }) => {
+        readonly type: boolean;
+        readonly validator: boolean;
+    };
 };
 /**
  * Collects import statements for all $ref dependencies of a schema.

package/dist/generators/collect-validator-imports.js

@@ -2,16 +2,24 @@ import { refToFilename } from "@amritk/helpers/ref-to-filename";
 import { refToName } from "@amritk/helpers/ref-to-name";
 import { resolveRef } from "@amritk/helpers/resolve-ref";
 import { collectEmittedRefs } from "./collect-emitted-refs.js";
-const buildImport = (ref, suffix) => {
+const buildImport = (ref, suffix, reads) => {
   const filename = refToFilename(ref);
   const typeName = refToName(ref, suffix);
   const validatorName = `validate${typeName}`;
-  return `import { type ${typeName}, ${validatorName} } from './${filename}.js'`;
+  const { type, validator } = reads({ typeName, validatorName });
+  if (type && validator)
+    return `import { type ${typeName}, ${validatorName} } from './${filename}.js'`;
+  if (validator)
+    return `import { ${validatorName} } from './${filename}.js'`;
+  if (type)
+    return `import type { ${typeName} } from './${filename}.js'`;
+  return null;
 };
 const collectValidatorImports = (schema, options) => {
   const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
   const rootSchema = options?.rootSchema;
   const typeSuffix = options?.typeSuffix ?? "";
+  const reads = options?.reads ?? (() => ({ type: true, validator: true }));
   const refs = collectEmittedRefs(schema, [], rootSchema, true);
   const seen = /* @__PURE__ */ new Set();
   const imports = [];
@@ -26,8 +34,10 @@ const collectValidatorImports = (schema, options) => {
       if (!resolved)
         continue;
     }
+    const statement = buildImport(ref, typeSuffix, reads);
     seen.add(filename);
-    imports.push(buildImport(ref, typeSuffix));
+    if (statement !== null)
+      imports.push(statement);
   }
   return imports;
 };