ata-validator 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 1.26.0 - 2026-09-17
+
+### Added
+
+- `toStandaloneModule(schema, { parse: true })` inlines local, acyclic `$ref`s before the clone proof runs, so schemas that keep their shapes in `$defs` and reference them, which is every schema a generator emits, now get a `parse()`. Only a node that is exactly a `$ref` plus annotations is inlined; a cycle, an external reference or a constraining sibling keyword leaves the reference in place and the clone declines as before. Defaults follow the runtime exactly: a `default` written next to the `$ref` fills, a `default` written inside the referenced definition does not, because `validate()` with `useDefaults` draws the same line and `parse()` must not be more generous than `validate()`. A new test holds `parse()` output equal to the runtime's `validate().data` on the same input.
+- When `parse: true` is requested and the clone still cannot be proven, the decline is loud: `onWarning` fires with the reason, and the emitted module carries a NOTE comment saying it has no `parse` export. Previously the only way to notice was reading the export list.
+
+### Fixed
+
+- The runtime compiler built `patternProperties` (and combined `additionalProperties`) child validators with `new Function`, which discarded the parent's helper scope: a child schema that needed a compiled pattern or format helper threw `ReferenceError` at validation time. Child checks are now generated inline in the parent validator and share its helper bindings. Reported and fixed by @jdalton in #46.
+- The TypeScript declarations emitted next to a compiled module now declare the `schemaHash` export; 1.25.0 added it to every module but not to the generated `.d.mts`, so importing it by name failed type checking while working at runtime.
+
 ## 1.25.0 - 2026-09-17
 
 ### Fixed

package/README.md

@@ -60,7 +60,7 @@ file.
   libraries maintained outside this project. On its validation page, valid data, the run of
   2026-09-13 against ata 1.14.1 puts ata first at 603 ns, with the next entry at 1.77 times
   that. The same site puts ata last on the download page, at 64.9 KB gzipped, because the entry
-  it bundles is the runtime compiler; the module `ata build` emits for that schema is 3.9 KB
+  it bundles is the runtime compiler; the module `ata build` emits for that schema is 5.1 KB
   minified and gzipped, and a compiled entry for the harness is in preparation.
 - [Bowtie](https://bowtie.report/), the cross-implementation JSON Schema test harness. ata's
   harness runs Draft 2020-12 and draft 7 there; on the harness at ata 1.16.1 the official suite
@@ -71,17 +71,19 @@ file.
 
 | Dimension | Schema | ata-AOT | runtime validator | Difference |
 |---|---|---|---|---|
-| Bundle (gzipped) | simple | 1.0 KB | 52.7 KB | 50.5x smaller |
-| Bundle (gzipped) | complex | 4.8 KB | 52.7 KB | 11.0x smaller |
-| Bundle (gzipped) | nested | 2.3 KB | 52.7 KB | 23.1x smaller |
+| Bundle (gzipped) | simple | 1.1 KB | 52.7 KB | 48.1x smaller |
+| Bundle (gzipped) | complex | 7.6 KB | 52.7 KB | 7.0x smaller |
+| Bundle (gzipped) | nested | 4.1 KB | 52.7 KB | 13.0x smaller |
 | Cold start | simple | 21 ms | 40 ms | 1.9x faster |
-| Throughput (1M ops) | simple | 258 Mops/s | 102 Mops/s | 2.5x faster |
-| Compile time | simple | 8 µs | 1.61 ms | 191x faster |
+| Throughput (1M ops) | simple | 257 Mops/s | 114 Mops/s | 2.3x faster |
+| Compile time | simple | 14 µs | 1.52 ms | 111x faster |
 
 The runtime column is the default validator most frameworks ship. Reproduce on your machine
-with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-08-13. Across three runs throughput moved between 258 and 278
-Mops/s and the compile ratio between 150x and 199x, so treat the last two rows as an order
-of magnitude rather than a constant.
+with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-09-17,
+on ata-validator 1.25.0, whose emitted modules carry full error detail and a schema hash, which
+is where the growth over earlier 1.x module sizes comes from. Across three runs throughput moved
+between 257 and 297 Mops/s and the compile ratio between 104x and 112x, so treat the last two
+rows as an order of magnitude rather than a constant.
 
 The wins are largest on bundle size and compile time because AOT moves work from runtime to
 build time. Throughput and cold start are also faster because the compiled validator is a
@@ -209,19 +211,19 @@ is the most common way to get a misleading number out of this library.
 
 | | compiled with `ata build` | runtime `new Validator(schema)` |
 |---|---|---|
-| In a bundle, gzipped | **1.9 KB** | 75.6 KB |
-| Time to a served request | **3.5 ms** | 10.7 ms |
+| In a bundle, gzipped | **4.5 KB** | 87.0 KB |
+| Time to a served request | **3.4 ms** | 10.6 ms |
 | Schema known when | build time | any time |
 
 The bundle row is a ten-field user schema built with
 `bun build --minify --target=browser`. The startup row is a Hono route on Bun 1.4, best
-of seven, against 3.6 ms for the same app doing no validation at all, so the compiled
+of seven, against 3.7 ms for the same app doing no validation at all, so the compiled
 path costs nothing measurable to start. The runtime
 figure is what it is because a schema that arrives at run time can use any keyword, so
 the whole engine has to be there. The compiled module imports nothing and contains only
 the checks your schema asks for.
 
-**On a server, use whichever fits your schemas.** 76 KB of JavaScript on a Node or Bun
+**On a server, use whichever fits your schemas.** 87 KB of JavaScript on a Node or Bun
 process is not a cost anyone notices, and the runtime API is the simpler thing to reach
 for. Speed is the same either way once warm.
 
@@ -450,7 +452,7 @@ const v = new Validator(schema, {
 
 ### Build-time compile (`ata compile`)
 
-The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. Typical output is about 2 KB gzipped for a ten-field schema, against 74 KB for the runtime bundled for the browser.
+The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. Typical output is about 4.5 KB gzipped for a ten-field schema, full error detail included, against 87 KB for the runtime bundled for the browser.
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs

package/lib/aot-impl.js

@@ -199,6 +199,74 @@ function emitFormatDecls(closures, mode, declKW) {
 // Returns null when the clone cannot be proven exact, and the module then
 // simply has no parse(). Declining is recoverable; a sanitiser that quietly
 // drops a property the schema allows is not.
+// Resolve a local JSON pointer ('#', '#/$defs/x', draft-7 '#/definitions/x',
+// any '#/...' path) against the schema root. Returns null for anything else:
+// external documents, anchors, URNs. Those stay with the runtime engines.
+function resolveLocalPointer(root, ref) {
+  if (ref === '#') return root;
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) return null;
+  let cur = root;
+  for (const raw of ref.slice(2).split('/')) {
+    let seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (cur === null || typeof cur !== 'object') return null;
+    if (!Object.prototype.hasOwnProperty.call(cur, seg)) {
+      try { seg = decodeURIComponent(seg); } catch (_) { return null; }
+      if (!Object.prototype.hasOwnProperty.call(cur, seg)) return null;
+    }
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+// Inline local, acyclic $refs before the clone proof runs, so a generated
+// schema ($defs + $ref, the shape every schema generator emits) can still get
+// a parse(). Only a node that is exactly a $ref plus annotations is replaced;
+// a $ref with a constraining sibling, a cycle, an unresolvable target or an
+// external reference is left in place, and emitClone declines it as before.
+// The walk never mutates its input and never descends into data positions
+// (default, const, enum, examples), where an object holding a "$ref" key is
+// a value, not a schema.
+const _INLINE_ANNOTATIONS = new Set(['$ref', 'title', 'description', '$comment', 'examples', 'deprecated', 'readOnly', 'writeOnly', 'default']);
+const _INLINE_DATA_KEYS = new Set(['default', 'const', 'enum', 'examples']);
+function inlineRefsForClone(root) {
+  const state = { budget: 512 };
+  // `inRef` marks content brought in from behind a reference. The runtime's
+  // useDefaults fills a default written next to the $ref, and does not fill
+  // defaults written inside the referenced definition, so the inlined copy
+  // keeps the first and drops the second. parse() must stay exactly as
+  // generous as validate(); a parse that fills more is a disagreement, not a
+  // feature.
+  const walk = (node, active, inRef) => {
+    if (!node || typeof node !== 'object') return node;
+    if (Array.isArray(node)) return node.map((n) => walk(n, active, inRef));
+    let cur = node;
+    let entered = false;
+    let siblingDefault;
+    while (cur && typeof cur === 'object' && !Array.isArray(cur) && typeof cur.$ref === 'string') {
+      for (const k of Object.keys(cur)) if (!_INLINE_ANNOTATIONS.has(k)) return node;
+      if (active.has(cur.$ref) || state.budget-- <= 0) return node;
+      const target = resolveLocalPointer(root, cur.$ref);
+      if (!target || typeof target !== 'object' || Array.isArray(target)) return node;
+      if (!entered && !inRef && cur.default !== undefined) siblingDefault = cur.default;
+      active = new Set(active);
+      active.add(cur.$ref);
+      cur = target;
+      entered = true;
+    }
+    const strip = inRef || entered;
+    const out = {};
+    for (const k of Object.keys(cur)) {
+      if (strip && k === 'default') continue;
+      const v = cur[k];
+      if (_INLINE_DATA_KEYS.has(k) || k === '$defs' || k === 'definitions') { out[k] = v; continue; }
+      out[k] = walk(v, active, strip);
+    }
+    if (siblingDefault !== undefined) out.default = siblingDefault;
+    return out;
+  };
+  return walk(root, new Set(), false);
+}
+
 function emitClone(node, access, depth) {
   if (!node || typeof node !== 'object') return null;
   if (depth > 12) return null;
@@ -422,11 +490,21 @@ function toStandaloneModule(validator, opts) {
   // schema declares. Off by default: it costs bytes in every emitted module,
   // and the reason to compile a schema ahead of time is usually to ship as
   // little as possible. Ask for it with { parse: true }.
-  const cloneExpr = !(opts && opts.parse) ? null : emitClone(
-    typeof validator._schemaObj === 'object' ? validator._schemaObj : null,
-    'data',
-    0,
-  );
+  // Local acyclic $refs are inlined first, so the schemas generators emit
+  // ($defs + $ref everywhere) still get a parse(). When the clone is still
+  // not provable, the decline is loud: the caller asked for parse and is not
+  // getting it, and discovering that by reading the export list cost a user
+  // an afternoon. Same channel as the error-detail decline above.
+  let cloneExpr = null;
+  if (opts && opts.parse) {
+    const baseSchema = typeof validator._schemaObj === 'object' ? validator._schemaObj : null;
+    cloneExpr = baseSchema ? emitClone(inlineRefsForClone(baseSchema), 'data', 0) : null;
+    if (!cloneExpr && typeof opts.onWarning === 'function') {
+      opts.onWarning(
+        'parse() could not be generated for this schema: the rebuild is only emitted where the allowed key set is provable, and a remaining $ref (cyclic, external, or carrying constraining siblings), patternProperties, or an additionalProperties schema makes it someone else\'s decision. The module ships without a parse export; validate and strip with the runtime Validator instead.'
+      );
+    }
+  }
   // Named _ataParse rather than parse: the emitted module also carries the
   // safe-regex prelude, which has a module-scope parse() of its own for
   // reading patterns. A second declaration of that name shadowed it and the
@@ -483,9 +561,12 @@ function validateJSON(text) {
     ? `export { ${names}${parseAlias} };\nexport default { ${names}${parseProp} };\n`
     : `module.exports = { ${names}${parseProp} };\nmodule.exports.default = module.exports;\n`;
 
-  const degradedNote = (!abortEarly && !errCore)
+  let degradedNote = (!abortEarly && !errCore)
     ? '// NOTE: error detail was requested but could not be generated for this\n// schema; failures report the single ATA9000 abort-early error. The verdict\n// is exact. Validate failing documents with the runtime Validator for detail.\n'
     : '';
+  if (opts && opts.parse && !cloneExpr) {
+    degradedNote += '// NOTE: parse() was requested but could not be generated for this schema;\n// the module has no parse export. Validate and strip with the runtime Validator.\n';
+  }
   return `// Auto-generated by ata-validator — do not edit.
 // Schema is embedded; runtime has zero dependency on ata-validator.
 ${degradedNote}'use strict';

package/lib/js-compiler.js

@@ -2246,15 +2246,13 @@ function genCode(schema, v, lines, ctx, knownType) {
       }
     }
 
-    // Build sub-schema validators as closure vars
+    // Build sub-schema checks inline so they share the parent helper scope.
+    const subChecks = []
     for (let i = 0; i < ppEntries.length; i++) {
       const [, sub] = ppEntries[i]
       const subLines = []
       genCode(sub, `_ppv`, subLines, ctx)
-      const fnBody = subLines.length === 0 ? `return true` : `${subLines.join(';')};return true`
-      const fnVar = `_ppf${pi}_${i}`
-      ctx.closureVars.push(fnVar)
-      ctx.closureVals.push(new Function('_ppv', fnBody))
+      subChecks.push(subLines.join(';'))
     }
 
     const guard = isObj ? '' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v}))`
@@ -2268,13 +2266,11 @@ function genCode(schema, v, lines, ctx, knownType) {
       ctx._ppHandledAdditional = true
       ctx._ppHandledPropertyNames = !!pn
       const propKeys = Object.keys(schema.properties || {})
-      let apFn = null
+      let apCheck = null
       if (apSchema) {
         const apLines = []
         genCode(apSchema, '_apv', apLines, ctx)
-        apFn = `_apf${pi}`
-        ctx.closureVars.push(apFn)
-        ctx.closureVals.push(new Function('_apv', apLines.length === 0 ? 'return true' : `${apLines.join(';')};return true`))
+        apCheck = apLines.join(';')
       }
       lines.push(`${guard}{for(const ${kVar} in ${v}){`)
       // propertyNames checks (merged into same loop)
@@ -2308,14 +2304,14 @@ function genCode(schema, v, lines, ctx, knownType) {
       if (ppEntries.length > 0) {
         lines.push(`let _pm${pi}=false`)
         for (let i = 0; i < ppEntries.length; i++) {
-          lines.push(`if(${matchers[i].check}){_pm${pi}=true;if(!_ppf${pi}_${i}(${v}[${kVar}]))return false}`)
+          lines.push(`if(${matchers[i].check}){_pm${pi}=true;const _ppv=${v}[${kVar}];${subChecks[i]}}`)
         }
       }
       // A key that is neither declared nor matched is additional. switch on
       // the declared names (V8 compiles string cases to a jump table); no
       // switch at all when nothing is declared, since a switch with no case
       // clause is a syntax error.
-      const additional = apFn ? `if(!${apFn}(${v}[${kVar}]))return false` : `return false`
+      const additional = apCheck !== null ? `const _apv=${v}[${kVar}];${apCheck}` : `return false`
       const notMatched = ppEntries.length > 0 ? `if(!_pm${pi}){${additional}}` : additional
       if (propKeys.length) {
         const switchCases = propKeys.map(k => `case ${JSON.stringify(k)}:`).join('')
@@ -2352,7 +2348,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         }
       }
       for (let i = 0; i < ppEntries.length; i++) {
-        lines.push(`if(${matchers[i].check}&&!_ppf${pi}_${i}(${v}[${kVar}]))return false`)
+        lines.push(`if(${matchers[i].check}){const _ppv=${v}[${kVar}];${subChecks[i]}}`)
       }
       lines.push(`}}`)
     }

package/lib/ts-gen.js

@@ -238,7 +238,8 @@ export type Result = ValidResult | InvalidResult;
 
 export declare function isValid(data: unknown): data is ${rootName};
 export declare function validate(data: unknown): Result;
-declare const _default: { validate: typeof validate; isValid: typeof isValid };
+export declare const schemaHash: string;
+declare const _default: { validate: typeof validate; isValid: typeof isValid; schemaHash: typeof schemaHash };
 export default _default;
 `;
 }

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.25.0';
+module.exports = '1.26.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "JSON Schema validation that compiles for speed and still runs where code generation is blocked. Compiled and interpreted engines answer identically at 100% of the official suite. TypeScript inference, Standard Schema V1, and a build step that emits dependency-free modules.",
   "main": "index.js",
   "module": "index.mjs",
@@ -122,13 +122,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.25.0",
-    "@ata-validator/native-darwin-x64": "1.25.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.25.0",
-    "@ata-validator/native-linux-arm64-musl": "1.25.0",
-    "@ata-validator/native-linux-x64-gnu": "1.25.0",
-    "@ata-validator/native-linux-x64-musl": "1.25.0",
-    "@ata-validator/native-win32-x64": "1.25.0"
+    "@ata-validator/native-darwin-arm64": "1.26.0",
+    "@ata-validator/native-darwin-x64": "1.26.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.26.0",
+    "@ata-validator/native-linux-arm64-musl": "1.26.0",
+    "@ata-validator/native-linux-x64-gnu": "1.26.0",
+    "@ata-validator/native-linux-x64-musl": "1.26.0",
+    "@ata-validator/native-win32-x64": "1.26.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"