@amritk/generate-parsers 0.17.2 → 0.19.0

package/AI.md

@@ -31,6 +31,16 @@ const files = await buildSchema(schema, 'Document')
    (unless `typesOnly`) runtime helper files.
 4. **Default parsers COERCE invalid input to defaults** rather than throwing;
    pass `strict: true` (the 6th positional) to make them throw.
+5. **Strict mode enforces the whole Draft 2020-12 assertion vocabulary** —
+   including `unevaluatedProperties` / `unevaluatedItems`, `contains` bounds,
+   `propertyNames`, `dependent*`, `patternProperties`, tuple `prefixItems`, and a
+   `$ref`'s 2020-12 siblings — and is held against Ajv by differential fuzz. It
+   deliberately differs on three points (`format` is an annotation, `multipleOf`
+   uses a scaled tolerance, a type-less `properties` schema still requires an
+   object); see the README.
+6. **Strict generation FAILS LOUDLY on anything it cannot enforce** (e.g. a
+   recursive `$ref` it would have to inline when ref imports are off). Catch the
+   error and fall back to a coercing parser if that is not what you want.
 
 Only the `.` entry (`buildSchema`, `GeneratedFile`, `ImportExtension`).
 Install: `bun add @amritk/generate-parsers`.

package/README.md

@@ -75,19 +75,61 @@ Write them to disk however you like.
 
 ## API
 
-### `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?)`
-
-| Parameter | Type | Description |
-|:---|:---|:---|
-| `rootSchema` | `JSONSchema` | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. |
-| `rootTypeName` | `string` | Name used for the root type (e.g. `"Document"`). |
-| `extensions` | `SchemaExtensions` _(optional)_ | Map of definition name → extra optional properties to merge in before generation. |
-| `typesOnly` | `boolean` _(optional)_ | When `true`, only emit `.ts` type definitions — skip parser functions and runtime helpers. |
-| `logWarnings` | `boolean` _(optional)_ | When `true`, generated parsers emit a `console.warn` for every input key not declared in the schema's properties. |
-| `strict` | `boolean` _(optional)_ | When `true`, generated parsers throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. |
+### `buildSchema(rootSchema, rootTypeName, …options)`
+
+Every option after the first two is **positional** — pass them in this order:
+
+| # | Parameter | Type | Default | Description |
+|--:|:---|:---|:---|:---|
+| 1 | `rootSchema` | `JSONSchema` | — | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. |
+| 2 | `rootTypeName` | `string` | — | Name used for the root type (e.g. `"Document"`). |
+| 3 | `extensions` | `SchemaExtensions` | — | Map of definition name → extra optional properties to merge in before generation. |
+| 4 | `typesOnly` | `boolean` | — | Only emit `.ts` type definitions — skip parser functions and runtime helpers. |
+| 5 | `logWarnings` | `boolean` | — | Generated parsers emit a `console.warn` for every input key not declared in the schema's properties. |
+| 6 | `strict` | `boolean` | — | Generated parsers throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. |
+| 7 | `helpersMode` | `'package' \| 'embedded'` | `'package'` | `'package'` imports runtime helpers from `@amritk/helpers`; `'embedded'` emits them alongside the output so it is self-contained. |
+| 8 | `helpersImportPrefix` | `string` | `'./'` | Prefix the generated files use when importing embedded helpers. |
+| 9 | `readonly` | `boolean` | `false` | Emit every property, array, and record in the type definitions as `readonly`. |
+| 10 | `stripUnknown` | `boolean` | `false` | Build each result from the declared properties only, dropping undeclared input keys at every level (zod's `.strip()`). |
+| 11 | `typeSuffix` | `string` | `''` | Suffix appended to every `$ref`-derived type name (`'Object'` turns `Contact` into `ContactObject`). The root type name is unaffected. |
+| 12 | `importExt` | `'js' \| 'ts'` | `'js'` | Extension emitted on relative import specifiers. `'js'` is the NodeNext form for output you compile; `'ts'` emits the literal on-disk paths so the sources run unbuilt. |
+| 13 | `caseInsensitive` | `boolean` | `false` | Normalize a mis-cased string to the exact casing of an enum/const member it matches case-insensitively. Coerce mode only. |
+| 14 | `schemas` | `Record<string, unknown>` | — | Documents you have **already loaded**, keyed by the absolute URI a `$ref` names them by. See below. |
 
 Returns: `Promise<GeneratedFile[]>`.
 
+#### Referencing another document
+
+A `$ref` to a URI is resolvable once you hand over the document behind it — pass
+it as the 14th argument:
+
+```typescript
+const files = await buildSchema(
+  { $ref: 'https://example.com/user.json' },
+  'Document',
+  undefined, false, false, true, 'embedded', './', false, false, '', 'js', false,
+  { 'https://example.com/user.json': userSchema },
+)
+```
+
+Each registered document becomes a resource of the generated document: its `$id`,
+its `$anchor`s and `$dynamicAnchor`s and its own embedded resources all resolve, a
+`$ref` from one registered document into another resolves, and each definition
+reached gets a file, a type and a parser like any other. A document with no `$id`
+resolves its relative `$ref`s against the URI you registered it under; one whose
+`$id` disagrees answers to both.
+
+Nothing is fetched — you cannot pass a URL, only a document — so generation stays
+a pure function of its inputs. Loading is yours to do, or
+[`@amritk/resolve-refs`](../resolve-refs)'. Registering more than the schema uses
+costs nothing: only the documents actually reached are emitted. A `$ref` to a URI
+nobody registered still stops the build, with a message naming the ref.
+
+> [!NOTE]
+> `importExt` defaults to `'js'` here, whereas the [`mjst` CLI](../cli) defaults it to
+> `'ts'`. The example above therefore emits `./info.js` specifiers; pass `'ts'` for
+> output meant to run without a build step.
+
 ---
 
 ## Options
@@ -148,12 +190,98 @@ Returns: `Promise<GeneratedFile[]>`.
 
 The generator handles:
 
-- `$ref` and `$dynamicRef` resolution, including JSON Schema 2020-12 `$dynamicAnchor`
+- `$ref` and `$dynamicRef` resolution, including JSON Schema 2020-12 `$dynamicAnchor` and a recursive root (`$ref: "#"`)
 - Discriminated and non-discriminated unions (`oneOf` / `anyOf`)
 - Enums and `const` values
-- Nested objects, arrays, records, and tuples
+- Nested objects, arrays, records, and tuples (`prefixItems`, and the draft-07 array form of `items`)
+- Multi-type schemas (`type: ["string", "null"]`) and the OpenAPI 3.0 `nullable: true` spelling
+- Composition alongside a declared shape — `allOf` members and sibling unions are intersected into the type, not dropped
 - Pattern-based default values
 
+### Strict-mode validation coverage
+
+A `strict` parser throws on any document the schema rejects, and its accept /
+reject decision is held against [Ajv](https://ajv.js.org) (2020-12) by a set of
+differential fuzz suites. The whole Draft 2020-12 assertion vocabulary is
+enforced:
+
+| family | keywords |
+|:--|:--|
+| types | `type` (single and array form), `enum`, `const` (compared structurally) |
+| numbers | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` |
+| strings | `minLength`, `maxLength` (counted in Unicode **code points**), `pattern` |
+| arrays | `items`, `prefixItems`, `additionalItems`, `minItems`, `maxItems`, `uniqueItems`, `contains`, `minContains`, `maxContains` |
+| objects | `properties`, `required`, `patternProperties`, `additionalProperties`, `propertyNames`, `minProperties`, `maxProperties`, `dependentRequired`, `dependentSchemas` |
+| composition | `allOf`, `anyOf`, `oneOf`, `not`, `if` / `then` / `else`, `$ref` (with its 2020-12 siblings), boolean schemas |
+| annotations | `unevaluatedProperties`, `unevaluatedItems` — including the keys and indices an `allOf` member, a `$ref` target, a matching `anyOf` / `oneOf` branch, an `if` / `then` / `else` arm, or a triggered `dependentSchemas` entry evaluated |
+
+Constraints bind their own family, with or without a declared `type`:
+`{ minimum: 5 }` rejects `4` and accepts `"anything"`, exactly as JSON Schema
+(and Ajv) specify.
+
+Three deliberate departures:
+
+- **`format` is an annotation**, not an assertion — matching Ajv's own default
+  (`ajv-formats` is opt-in there). Use
+  [`@amritk/runtime-validators`](../runtime-validators), whose `formats` option
+  asserts them.
+- **`multipleOf` compares within a magnitude-scaled tolerance** for a fractional
+  divisor, rather than Ajv's exact `x / m` integer test, so `0.3` satisfies
+  `multipleOf: 0.1` here and fails there. IEEE-754 makes the exact test reject
+  values every author intends as valid. An integer divisor takes the exact `%`
+  path, which needs no tolerance. Both branches are emitted from
+  `@amritk/helpers/multiple-of-check`, which mirrors the runtime interpreter's
+  own check — so parsers, validators, and the interpreter cannot disagree about
+  a document.
+- **A type-less schema that declares `properties` still requires an object.**
+  Ajv accepts `"a string"` against `{ properties: { a: {} } }`; a parser has to
+  return the type it declares, and the declared type is an object.
+
+If a strict parser cannot enforce something — a `$ref` cycle it would have to
+inline because the build emits a single file, a subschema using a keyword it
+cannot prove — generation **fails with an error naming the keyword** rather than
+emitting a parser that quietly accepts what the schema forbids. Coercing
+(non-strict) parsers are documented to repair rather than reject, so they ignore
+the rejecting keywords by design.
+
+### Conformance, measured
+
+The coverage above is not a claim — it is checked against the corpus every
+validator in every language is judged on.
+`src/generators/json-schema-conformance.test.ts` generates a strict parser for
+each schema in the official
+[JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
+(the required Draft 2020-12 tests — 1281 cases), links the emitted files in
+memory, and runs the suite's instances through the real generated code:
+
+**1240 / 1281 cases pass (96.8%).**
+
+A case passes only if the parser throws exactly when the spec says invalid *and*
+returns an accepted document unchanged — strict mode does not coerce, so a parser
+that quietly rewrites a valid document fails here too.
+
+The suite's `remotes/` documents and the 2020-12 dialect metaschema are supplied
+through the `schemas` option, which is how the suite intends a generator that does
+no I/O to answer the retrieval step. Everything else — applying the base URIs,
+walking anchors across documents, emitting a parser per definition and an import
+graph that links — the generator still has to do.
+
+Of the 41 that do not, **18** are the `ignores a non-object` cases that follow
+from the third departure above, and **12** are a keyword strict mode will not
+approximate (a cyclic `$ref` with siblings, a cyclic `unevaluatedProperties`) —
+those cost a build error naming the cause, never a wrong verdict. The rest: **8**
+`$dynamicRef`s whose binding depends on the evaluation path (a generator emits one
+function per definition, shared by every path that reaches it), **2** embedded
+resources whose definitions reduce to one filename, and one `$vocabulary` case.
+
+Every one is listed in
+`src/generators/json-schema-conformance-expected-failures.test-utils.ts` with the
+reason, and the test fails if a case moves in *either* direction — a regression
+breaks the build, and so does a case that starts passing without its entry being
+removed. The corpus is vendored under
+[`fixtures/json-schema-test-suite`](../../fixtures/json-schema-test-suite); none
+of it is published.
+
 ---
 
 ## Benchmarks
@@ -173,18 +301,18 @@ x64), parsing valid input at steady state:
 
 | case | mode | mjst (generated) | zod | typebox |
 |:--|:--|--:|--:|--:|
-| user (4 fields) | parseSafe | **~16M** ops/s | ~3.3M ops/s | ~1.3M ops/s |
-| order (nested + array) | parseSafe | **~5.8M** ops/s | ~0.6M ops/s | ~0.18M ops/s |
-| user (4 fields) | parseStrict | **~13M** ops/s | ~1.8M ops/s | ~1.85M ops/s |
-| order (nested + array) | parseStrict | **~7.5M** ops/s | ~0.36M ops/s | ~0.28M ops/s |
+| user (4 fields) | parseSafe | **~18M** ops/s | ~3M ops/s | ~1.6M ops/s |
+| order (nested + array) | parseSafe | **~7.2M** ops/s | ~0.59M ops/s | ~0.18M ops/s |
+| user (4 fields) | parseStrict | **~15M** ops/s | ~2M ops/s | ~2.05M ops/s |
+| order (nested + array) | parseStrict | **~8.5M** ops/s | ~0.38M ops/s | ~0.29M ops/s |
 
 The upstream `assert` case (seven scalar roots plus a nested object) runs faster
-still — tens of millions of ops/s — but at that size the numbers swing enough
+still — ~44M ops/s strict, ~97M safe — but at that size the numbers swing enough
 run-to-run that the ratio, not the absolute, is the honest signal: mjst lands
-~5–30× ahead of zod across every case above.
+~6–30× ahead of zod across every case above.
 
 The trade is a one-shot **prepare** cost that only mjst pays — generating the
-parser source — which measures **~0.1–0.8 ms** per schema here (zod and TypeBox
+parser source — which measures **~0.15–1 ms** per schema here (zod and TypeBox
 author or interpret their parsers with no separate build step, so there is
 nothing to time). That is trivially amortized: you generate once at build time
 and run the emitted code forever.

package/dist/generators/assert-supported-keywords.d.ts

@@ -1,4 +1,5 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { type StrictAssertionContext } from './generate-strict-assertion.js';
 /**
  * Throws when a schema (anywhere in its subtree) uses a keyword the *strict*
  * parser generator cannot enforce but which narrows the set of valid documents.
@@ -9,18 +10,21 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  *
  * Two families are rejected:
  *
- *  - `unevaluatedProperties` / `unevaluatedItems` with a constraining value
- *    (`false` or a subschema). The generator has no support for the "which
- *    properties/items were evaluated" bookkeeping these require; only the
- *    runtime interpreter does. A `true` value permits everything and is allowed.
+ *  - `contains`, `not`, `propertyNames`, or `dependentSchemas` whose subschema
+ *    uses a form {@link canMatchSubschema} cannot prove inline (a cyclic `$ref`,
+ *    an unknown keyword). The parser enforces these keywords only for subschemas
+ *    it can match exactly; anything else would be silently ignored.
  *
- *  - `contains`, `propertyNames`, or `dependentSchemas` whose subschema uses a
- *    form {@link canMatchSubschema} cannot prove inline (a `$ref`, a combinator,
- *    a schema-valued record, …). The parser enforces these keywords only for
- *    subschemas it can match exactly; anything else would be silently ignored.
+ *  - A node whose enforcement rests on the whole-schema backstop (see
+ *    {@link backstopReason} — `unevaluatedProperties` / `unevaluatedItems`, a
+ *    `$ref` nothing delegates, a type-less constraint) when the matcher cannot
+ *    build that backstop.
+ *
+ * Everything the matcher *can* prove is enforced rather than refused, which is
+ * why `unevaluated*` and `$ref`-carrying subschemas no longer fail outright.
  *
  * This runs for strict generation only — coercing parsers are documented to be
  * permissive (they repair rather than reject), so ignoring these keywords there
  * is the contract, not a lie.
  */
-export declare const assertNoUnsupportedKeywords: (schema: JSONSchema, typeName: string) => void;
+export declare const assertNoUnsupportedKeywords: (schema: JSONSchema, typeName: string, context?: StrictAssertionContext) => void;

package/dist/generators/assert-supported-keywords.js

@@ -1,29 +1,49 @@
 import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { backstopReason, backstopSchema } from "./generate-strict-assertion.js";
 import { canMatchSubschema } from "./subschema-match.js";
-const assertNoUnsupportedKeywords = (schema, typeName) => {
+const SUBSCHEMA_KEYS = [
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "contains",
+  "additionalProperties",
+  "propertyNames",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "not",
+  "if",
+  "then",
+  "else",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "contentSchema"
+];
+const SUBSCHEMA_MAP_KEYS = [
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  "$defs",
+  "definitions"
+];
+const assertNoUnsupportedKeywords = (schema, typeName, context = {}) => {
+  const rootSchema = context.rootSchema ?? (isSchemaObject(schema) ? schema : void 0);
+  const provable = (sub) => canMatchSubschema(sub, rootSchema);
   const fail = (keyword, detail) => {
     throw new Error(`[${typeName}] unsupported keyword "${keyword}": the strict parser generator ${detail}, and would silently accept documents the schema rejects. Generate a coercing (non-strict) parser, validate this schema with @amritk/generate-validators, or remove the keyword.`);
   };
   const visit = (node) => {
-    if (typeof node !== "object" || node === null)
+    if (typeof node !== "object" || node === null || Array.isArray(node))
       return;
-    if (Array.isArray(node)) {
-      for (const item of node)
-        visit(item);
-      return;
-    }
     const record = node;
-    if ("unevaluatedProperties" in record && record["unevaluatedProperties"] !== true) {
-      fail("unevaluatedProperties", "does not implement it");
-    }
-    if ("unevaluatedItems" in record && record["unevaluatedItems"] !== true) {
-      fail("unevaluatedItems", "does not implement it");
-    }
-    if ("contains" in record && !canMatchSubschema(record["contains"])) {
+    if ("contains" in record && !provable(record["contains"])) {
       fail("contains", "cannot prove its subschema inline");
     }
+    if ("not" in record && !provable(record["not"])) {
+      fail("not", "cannot prove its subschema inline");
+    }
     if ("propertyNames" in record && isSchemaObject(record["propertyNames"])) {
-      if (!canMatchSubschema(record["propertyNames"])) {
+      if (!provable(record["propertyNames"])) {
         fail("propertyNames", "cannot prove its subschema inline");
       }
     }
@@ -32,13 +52,33 @@ const assertNoUnsupportedKeywords = (schema, typeName) => {
       for (const sub of Object.values(dependentSchemas)) {
         if (typeof sub === "boolean")
           continue;
-        if (!canMatchSubschema(sub)) {
+        if (!provable(sub)) {
           fail("dependentSchemas", "cannot prove one of its subschemas inline");
         }
       }
     }
-    for (const key in record)
-      visit(record[key]);
+    const reason = backstopReason(node, context);
+    if (reason !== null && !provable(backstopSchema(node, reason))) {
+      fail(reason, "cannot prove the schema it appears in inline");
+    }
+    for (const keyword of SUBSCHEMA_KEYS) {
+      const value = record[keyword];
+      if (value === void 0)
+        continue;
+      if (Array.isArray(value)) {
+        for (const item of value)
+          visit(item);
+      } else {
+        visit(value);
+      }
+    }
+    for (const keyword of SUBSCHEMA_MAP_KEYS) {
+      const value = record[keyword];
+      if (typeof value !== "object" || value === null || Array.isArray(value))
+        continue;
+      for (const sub of Object.values(value))
+        visit(sub);
+    }
   };
   visit(schema);
 };

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

@@ -59,6 +59,14 @@ export type GeneratedFile = {
  *   mode only — strict parsers still reject a casing mismatch. The normalization lives on
  *   the coercion failure branch, so correctly-cased input keeps the exact-match fast path
  *   and the hot path is unaffected.
+ * @param schemas - Other schema documents you have **already loaded**, keyed by the absolute
+ *   URI a `$ref` names them by. Supplying them makes those URIs resolvable, so the schema can
+ *   reference a document that is not itself — each one becomes a resource of the generated
+ *   document, with its own `$id`, anchors and nested resources all resolvable, and a `$ref`
+ *   from one registered document into another resolving too. Nothing is fetched here: loading
+ *   is yours to do (or `@amritk/resolve-refs`'), and a `$ref` to a URI nobody registered still
+ *   stops generation. Only the documents actually referenced get files, so registering more
+ *   than the schema uses costs nothing in the output.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -91,4 +99,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension, caseInsensitive?: boolean) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string, importExt?: ImportExtension, caseInsensitive?: boolean, schemas?: Readonly<Record<string, unknown>>) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, resolve as resolvePath } from "node:path";
+import { foldNullable } from "@amritk/helpers/fold-nullable";
 import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
 import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
 import { applySchemaExtensions } from "../helpers/apply-schema-extensions.js";
@@ -19,14 +20,16 @@ const readHelperSource = async (helper, importExt) => {
     return { ext: "js", content: compiled };
   }
 };
-const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false) => {
+const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false, schemas) => {
   const files = [];
   const usedHelpers = /* @__PURE__ */ new Set();
-  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+  const foldedSchema = foldNullable(rootSchema);
+  walkRefGraph(foldedSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
     if (node.filename === "index")
       return;
     const extended = extensions ? applySchemaExtensions(node.schema, node.filename, extensions) : node.schema;
     const result = generateFile(extended, node.typeName, {
+      selfFilename: node.filename,
       typesOnly: typesOnly ?? false,
       rootSchema: node.rootSchema,
       helpersMode,

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

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

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

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

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

@@ -1,8 +1,7 @@
-import { safeAccessor } from "@amritk/helpers/safe-accessor";
 import { getDiscriminatorValue } from "../helpers/get-discriminator-value.js";
 import { generateSchemaChecks } from "./generate-schema-checks.js";
 const generateDiscriminatedUnionValidation = (accessor, schemas, discriminatorKey, defaultValue, isRequired) => {
-  const discAccessor = safeAccessor(`${accessor}?`, discriminatorKey);
+  const discAccessor = `(${accessor} as Record<string, unknown> | null | undefined)?.[${JSON.stringify(discriminatorKey)}]`;
   const branches = [];
   for (const schema of schemas) {
     const discriminatorValue = getDiscriminatorValue(schema, discriminatorKey);

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

@@ -6,9 +6,14 @@
  * b` chain rather than `[a, b].includes(x)`. The `.includes` form allocates a
  * fresh array on every call (this expression runs on the parser hot path); the
  * `===` chain is allocation-free and matches the validators package's
- * `enumMembershipExpr`. It falls back to `.includes` when a member is an
- * object/array (reference equality) or `NaN` (where `includes`'s SameValueZero
- * differs from `===`), so the verdict is unchanged.
+ * `enumMembershipExpr`.
+ *
+ * An object or array member is compared *structurally* via
+ * {@link generateDeepEqualCheck}. `.includes` was SameValueZero — reference
+ * equality — so `{ enum: [{ a: 1 }] }` could never match a freshly parsed
+ * `{ a: 1 }`: the fast path never fired and the strict parser threw on a document
+ * Ajv accepts. `NaN` keeps its own `Number.isNaN` test, the one case `===` cannot
+ * express.
  */
 export declare const generateEnumCheck: (accessor: string, enumValues: readonly unknown[]) => string;
 /**

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

@@ -1,10 +1,12 @@
+import { generateDeepEqualCheck } from "./generate-deep-equal-check.js";
 const generateEnumCheck = (accessor, enumValues) => {
-  const allPrimitive = enumValues.length > 0 && enumValues.every((v) => (v === null || typeof v !== "object") && typeof v !== "function") && !enumValues.some((v) => typeof v === "number" && Number.isNaN(v));
-  if (allPrimitive) {
-    return `(${enumValues.map((v) => `${accessor} === ${JSON.stringify(v)}`).join(" || ")})`;
-  }
-  const serializedEnum = JSON.stringify(enumValues);
-  return `${serializedEnum}.includes(${accessor} as never)`;
+  if (enumValues.length === 0)
+    return "false";
+  const members = enumValues.map((value) => {
+    const check = generateDeepEqualCheck(accessor, value);
+    return value !== null && typeof value === "object" ? `(${check})` : check;
+  });
+  return `(${members.join(" || ")})`;
 };
 const generateEnumCaseInsensitiveCoercion = (accessor, enumValues, fallback) => {
   const entries = [];

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

@@ -16,6 +16,13 @@ type GenerateFileOptions = {
      * the import list, preventing a file from importing itself.
      */
     readonly selfRef?: string;
+    /**
+     * The filename this file is written as, without extension. Used for
+     * self-import detection when the schema has no `$ref` of its own — the root
+     * document — so a `$defs` entry that collides with the root type name cannot
+     * make the root file import itself.
+     */
+    readonly selfFilename?: string;
     /**
      * The root schema document. When provided, URI refs that cannot be resolved
      * within the root schema's $defs are excluded from the import list.

package/dist/generators/generate-files.js

@@ -9,9 +9,20 @@ const generateFile = (schema, typeName, options) => {
   const helpersMode = options?.helpersMode ?? "package";
   const typeSuffix = options?.typeSuffix ?? "";
   const importExt = options?.importExt ?? "js";
-  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false, typeSuffix });
+  const typeDefinition = generateTypeDefinition(schema, typeName, {
+    readonly: options?.readonly ?? false,
+    typeSuffix,
+    ...rootSchema !== void 0 ? { rootSchema } : {}
+  });
   if (typesOnly) {
-    const imports2 = collectImports(schema, { typesOnly: true, selfRef, rootSchema, typeSuffix, importExt });
+    const imports2 = collectImports(schema, {
+      typesOnly: true,
+      selfRef,
+      selfFilename: options?.selfFilename,
+      rootSchema,
+      typeSuffix,
+      importExt
+    });
     let result2 = "";
     if (imports2.length > 0) {
       result2 += imports2[0];
@@ -23,7 +34,12 @@ const generateFile = (schema, typeName, options) => {
     return { content: result2 + typeDefinition, usedHelpers: /* @__PURE__ */ new Set() };
   }
   const stripUnknown = options?.stripUnknown ?? false;
-  const reservedNames = collectImportTypeNames(schema, { selfRef, rootSchema, typeSuffix });
+  const reservedNames = collectImportTypeNames(schema, {
+    selfRef,
+    selfFilename: options?.selfFilename,
+    rootSchema,
+    typeSuffix
+  });
   const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames);
   const parserFunction = generateParserFunction(schema, typeName, {
     useRefImports: true,
@@ -41,7 +57,10 @@ const generateFile = (schema, typeName, options) => {
 
 ${parserFunction}`;
   const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix, importExt);
-  const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix, importExt }), ...helpers.imports];
+  const imports = [
+    ...collectImports(schema, { selfRef, selfFilename: options?.selfFilename, rootSchema, typeSuffix, importExt }),
+    ...helpers.imports
+  ];
   let result = "";
   if (imports.length > 0) {
     result += imports[0];

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

@@ -89,7 +89,7 @@ type GenerateParserOptions = {
  * the resolved schema's validation logic. Array properties whose items are a
  * $ref will map each element through the imported parser.
  */
-export declare const generateParserFunction: (schema: JSONSchema, typeName: string, options?: GenerateParserOptions) => string;
+export declare const generateParserFunction: (schema: JSONSchema, typeName: string, rawOptions?: GenerateParserOptions) => string;
 /**
  * Returns the predicate function name for a generated shape validator.
  * @example shapeValidatorFunctionName('CustomerObject') // 'validateCustomerObjectShape'