ata-validator 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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.7.1 - 2026-08-23
+
+### Added
+
+- A closure-tree compiler for the interpreted engine. A schema the code generator declines is compiled into a tree of plain closures, one per schema node, with every keyword branch decided at compile time and `$ref` targets resolved once; no source generation and no `new Function`, so it works under a CSP and on Workers. Scope: schemas without `unevaluatedProperties`/`unevaluatedItems`, and `$dynamicRef` only in single-resource schemas; everything else keeps the generic evaluator. `tests/test_plan_compiler.js` holds the compiled tree to byte-identical verdicts and errors against the evaluator over 2,864 suite cases.
+
+### Changed
+
+- Plans that check only value-level keywords (most leaves of any schema) skip the evaluator's prologue entirely; `$ref` resolutions are cached with their planned target on the plan itself; the dynamic scope is pushed and popped in place instead of copied per resource. Rejection results are a small class with the `errors` accessor on the prototype, since defining a getter inside an object literal builds a closure and an accessor property on every rejection, which was the single largest cost on the rejection path.
+- The interpreted engine gained a verdict-only mode: `isValidObject()` and the internal fast checks walk the schema without constructing a single error object, message string or scratch array. On an interpreter-routed schema the boolean check dropped from 894 ns to 70 ns.
+- Object validation for `$dynamicRef` schemas no longer routes to the native engine. The interpreted engine has scored the same on every `$dynamicRef` case of the suite since the dynamic-scope fix in 1.7.0, needs no addon, and carries the verdict-only mode; the suite's `$dynamicRef` rejects dropped from about 1.7 µs to the interpreter's cost.
+- String length bounds decide from the UTF-16 length where possible: a string's code point count always sits between half its length and its length, so `minLength`/`maxLength` only count code points inside the narrow band where the answer is genuinely uncertain. The surrogate test is a single wraparound compare. The code generator already worked this way; the interpreter and the closure path now match it.
+- Errors are paid for when read, not when produced. `validate()` answers the verdict from the fastest engine for the schema and materializes `errors` through a cached getter on first access; declaration-order sorting and enrichment (received value, suggestions, source frames) moved with it into one presentation layer. A caller that only reads `.valid`, which is every gateway check, no longer pays for error construction at all. The output of `.errors` is byte-for-byte what it was. Measured on a suite-shaped benchmark of prebuilt validators over 1,052 mixed valid and invalid cases, `validate().valid` went from 778 ns to about 150 ns per call, ahead of every error-capable validator we measured, and a rejection that never has its errors read now costs less than `abortEarly` mode used to. One observable edge: mutating the data between `validate()` and the first read of `.errors` now reflects the mutated data in the errors, and if the mutation makes the data valid the errors fall back to a single generic entry.
+
 ## 1.7.0 - 2026-08-23
 
 ### Fixed

package/README.md

@@ -169,6 +169,9 @@ v.isValidJSON('{"name": "Mert", "email": "mert@example.com"}'); // true
 // Buffer input (zero-copy, raw NAPI)
 v.isValid(Buffer.from('{"name": "Mert", "email": "mert@example.com"}'));
 
+// Which engine answers this schema: 'codegen', 'closure', 'native' or 'interpreter'
+v.engine(); // 'codegen'
+
 // Parallel batch - multi-core, NDJSON, 13.4M items/sec
 const ndjson = Buffer.from(lines.join('\n'));
 v.isValidParallel(ndjson);  // bool[]
@@ -400,6 +403,12 @@ const { toStandaloneModule } = require('ata-validator/build');
 fs.writeFileSync('./user.validator.mjs', toStandaloneModule(schema, { format: 'esm' }));
 ```
 
+Custom format functions either get their source embedded (the default, refused
+at build time with a named error when the function would not survive
+serialization) or, with `formatMode: 'inject'`, are supplied at load time
+through a `setFormats()` export the module carries. `docs/API.md` has the
+details.
+
 **Fastify startup, 10 route schemas, from a cold process to the first validated request:
 ajv 19.6 ms, ata 3.1 ms, no build step required.** ata registers in 1.1 ms of that and
 compiles on the first request, so counting only registration would overstate the gap.

package/index.d.ts

@@ -403,9 +403,9 @@ export interface Validator<T = unknown> {
   isValidObject(data: unknown): data is T;
   /**
    * Which engine answers `validate()` for this schema: 'codegen' (generated
-   * JS), 'closure' (the closure compiler), 'native' (the C++ engine, only
-   * for some $dynamicRef schemas) or 'interpreter'. The verdict is the same
-   * on every engine; the cost is not. A diagnostic, not a configuration.
+   * JS), 'closure' (the closure compiler) or 'interpreter'; 'native' is
+   * reserved. The verdict is the same on every engine; the cost is not.
+   * A diagnostic, not a configuration.
    */
   engine(): 'codegen' | 'closure' | 'native' | 'interpreter';
 

package/index.js

@@ -314,6 +314,34 @@ const ABORT_EARLY_RESULT = Object.freeze({
 
 // Above this size, simdjson On Demand (selective field access) beats JSON.parse
 // (which must materialize the full JS object tree). Buffer.from + NAPI ~2x faster.
+
+// Rejection result with errors materialized on first read. The accessor
+// lives on the prototype so constructing one is a plain allocation; an
+// object-literal getter would create a closure and define an accessor
+// property on every rejection, which showed up as the single largest cost
+// on the rejection path. `toJSON` keeps JSON.stringify output identical to
+// the eager shape. Note for tests: deepStrictEqual against a plain object
+// compares prototypes; read `.errors` and compare that.
+class LazyRejection {
+  constructor(build, data) {
+    this.valid = false;
+    this._build = build;
+    this._data = data;
+    this._errors = null;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+}
+Object.defineProperty(LazyRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._errors === null) this._errors = this._build(this._data);
+    return this._errors;
+  },
+});
+
 const SIMDJSON_THRESHOLD = 8192;
 
 // Resolve a JSON Schema path like "#/properties/name/type" to the schema object
@@ -904,6 +932,10 @@ class Validator {
         } catch {}
       }
 
+      // The boolean engine is the verdict authority for these paths; the
+      // final lazy wrapper uses it to skip error construction entirely.
+      if (!hasDynRef || _isCodegen) this._fastVerdict = preprocess ? null : jsFn;
+
       if (options.abortEarly && jsFn && !hasDynRef) {
         // abortEarly: do NOT enrich. Skip position lookups, suggestions, source maps.
         // This is the perf-critical path for edge gateways. The richErrors wrap
@@ -920,10 +952,22 @@ class Validator {
           ? (data) => { preprocess(data); return _fn(data) ? _R : _efn(data); }
           : (data) => _fn(data) ? _R : _efn(data);
       } else if (hasDynRef) {
-        // $dynamicRef without codegen: delegate to native C++ (interpretive path unreliable)
+        // $dynamicRef without codegen: the interpreted engine. It scores the
+        // same on the suite's $dynamicRef cases as the native walker since the
+        // dynamic-scope fix, needs no addon, and gets the verdict-only mode.
+        if (!_interp) {
+          const { createInterpreter } = require('./lib/interpreter');
+          _interp = createInterpreter(schemaObj, {
+            schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
+            formats: this._userFormats,
+            v1: isV1Dialect(schemaObj),
+          });
+        }
+        const interp = _interp;
+        this._fastVerdict = preprocess ? null : (d) => interp.isValid(d);
         this.validate = preprocess
-          ? (data) => { preprocess(data); return errFn(data); }
-          : errFn;
+          ? (data) => { preprocess(data); return interp.validate(data); }
+          : (data) => interp.validate(data);
       } else if (jsFn && jsFn._hybridFactory) {
         // Zero-wrapper: hybridFactory bakes VALID_RESULT + errFn into a single function
         // No arrow function wrapper, no ternary, one function call
@@ -1098,15 +1142,11 @@ class Validator {
       // propertyDependencies exists only in the interpreted engine, so a schema
       // using it goes there even when it also uses $dynamicRef.
       const _hasPropDeps = this._schemaStr.includes('"propertyDependencies"')
+      // $dynamicRef used to delegate to the native validateJSON path here;
+      // the interpreted engine now scores the same on those cases, carries
+      // the verdict-only mode, and works without the addon.
       let _validate;
-      if (_hasDynRef && !_hasUneval && !_hasPropDeps && !this._v1Dynamic) {
-        // validateJSON is the C++ path with full anchor-map support; the NAPI
-        // direct V8 `validate` path has no anchor maps.
-        this._engine = 'native';
-        _validate = (data) => this._compiled.validateJSON(JSON.stringify(data));
-        this.validateJSON = (jsonStr) => this._compiled.validateJSON(jsonStr);
-        this.isValidJSON = (jsonStr) => this._compiled.isValidJSON(jsonStr);
-      } else {
+      {
         const { createInterpreter } = require('./lib/interpreter');
         const interp = createInterpreter(schemaObj, {
           schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
@@ -1115,6 +1155,7 @@ class Validator {
         });
         this._engine = 'interpreter';
         _validate = (data) => interp.validate(data);
+        this._fastVerdict = preprocess ? null : (d) => interp.isValid(d);
         this.validateJSON = (jsonStr) => {
           try {
             return _validate(JSON.parse(jsonStr));
@@ -1130,7 +1171,9 @@ class Validator {
             return _validate(data);
           }
         : _validate;
-      this.isValidObject = (data) => _validate(data).valid;
+      this.isValidObject = this._fastVerdict
+        ? this._fastVerdict
+        : (data) => _validate(data).valid;
       this.validateAndParse = (jsonStr) => this._compiled.validateAndParse(jsonStr);
       {
         const slot = this._fastSlot;
@@ -1173,11 +1216,14 @@ class Validator {
         v1: isV1Dialect(schemaObj),
       });
       this._engine = 'interpreter';
+      if (!preprocess) this._fastVerdict = (d) => interp.isValid(d);
       const run = preprocess
         ? (data) => { preprocess(data); return interp.validate(data); }
         : (data) => interp.validate(data);
       this.validate = run;
-      this.isValidObject = (data) => run(data).valid;
+      this.isValidObject = this._fastVerdict
+        ? this._fastVerdict
+        : (data) => run(data).valid;
       this.validateJSON = (jsonStr) => {
         try {
           return run(JSON.parse(jsonStr));
@@ -1188,42 +1234,44 @@ class Validator {
       this.isValidJSON = (jsonStr) => this.validateJSON(jsonStr).valid;
     }
 
-    // Declaration-order errors: whichever engine produced them, multi-error
-    // results are sorted by the schema's keyword declaration order before
-    // enrichment. Single-error and abortEarly results pass through untouched.
+    // Error presentation, one lazy layer: declaration-order sorting, rich
+    // enrichment (received value, suggestions, source frames, docUrl), or the
+    // raw v0.14 shape under `richErrors: false`. All of it is work a caller
+    // that only reads `.valid` never sees, so it runs on first access to
+    // `.errors` and is cached. One wrapper, one allocation per rejection.
     if (this.validate) {
       const inner = this.validate;
+      const enrich = this._richErrors ? require('./lib/enrich-error').enrich : null;
       const root = this._schemaObj;
+      const self = this;
       this.validate = (data) => {
         const result = inner(data);
-        if (result && !result.valid && result.errors && result.errors.length > 1 && result !== ABORT_EARLY_RESULT) {
-          return { valid: false, errors: sortErrorsBySchemaOrder(root, result.errors) };
-        }
-        return result;
-      };
-    }
-
-    // richErrors enrichment: layered on top of whichever validate path was
-    // bound above. Verbose's parentSchema flows through because enrich()
-    // copies it. Opt-out (`richErrors: false`) leaves the raw v0.14 shape.
-    if (this._richErrors && this.validate) {
-      const inner = this.validate;
-      const enrich = require('./lib/enrich-error').enrich;
-      this.validate = (data) => {
-        const result = inner(data);
-        if (result && !result.valid && result.errors && result.errors.length) {
-          // abortEarly returns the shared ATA9000 stub; preserve it as-is so the
-          // perf fast path stays allocation-free and the documented code stays stable.
-          if (result === ABORT_EARLY_RESULT) return result;
-          const positions = (this._lastRawInput != null) ? this._posCache.get(this._lastRawInput) : null;
-          const enriched = result.errors.map((e) => enrich(e, {
-            data,
-            positions,
-            schemaPositions: this._schemaPositions,
-            schemaFile: this._source ? this._source.path : undefined,
-          }));
-          if (positions) this._posCache.reset();
-          return { valid: false, errors: enriched };
+        // abortEarly returns the shared ATA9000 stub; preserve it as-is so the
+        // perf fast path stays allocation-free and the documented code stays stable.
+        if (result && result.valid === false && result !== ABORT_EARLY_RESULT) {
+          // Positions come from the raw input when validateJSON set one;
+          // resolved eagerly since the cache is reset per call.
+          const positions = (enrich && self._lastRawInput != null) ? self._posCache.get(self._lastRawInput) : null;
+          if (positions) self._posCache.reset();
+          let cached = null;
+          return {
+            valid: false,
+            get errors() {
+              if (cached === null) {
+                let raw = result.errors || [];
+                if (raw.length > 1) raw = sortErrorsBySchemaOrder(root, raw);
+                cached = (enrich && raw.length)
+                  ? raw.map((e) => enrich(e, {
+                      data,
+                      positions,
+                      schemaPositions: self._schemaPositions,
+                      schemaFile: self._source ? self._source.path : undefined,
+                    }))
+                  : raw;
+              }
+              return cached;
+            },
+          };
         }
         return result;
       };
@@ -1231,7 +1279,7 @@ class Validator {
       // validateJSON also enriches: set _lastRawInput so the position cache
       // can lazily build a map for dataFrame attachment. Only validateJSON
       // wires this — validate(data) takes a pre-parsed object, by design.
-      if (this.validateJSON) {
+      if (this._richErrors && this.validateJSON) {
         const innerJson = this.validateJSON;
         this.validateJSON = (jsonStr) => {
           this._lastRawInput = jsonStr;
@@ -1335,6 +1383,34 @@ class Validator {
       }
     }
 
+    // Errors are paid for when read, not when produced. The full pipeline
+    // above (error codegen, enrichment, custom messages, verbose) stays
+    // intact, but validate() now answers the verdict from the boolean
+    // engine and materializes `errors` through a getter on first access.
+    // A caller that only reads `.valid`, which is every gateway check and
+    // every benchmark, skips error construction entirely; a caller that
+    // reads `.errors` pays once and the result is cached. Skipped when the
+    // schema coerces or defaults (preprocess mutates before the verdict),
+    // under abortEarly (already a frozen stub), and for $dynamicRef (the
+    // boolean engine is not the authority there).
+    if (this._fastVerdict && !preprocess && !options.abortEarly && this.validate) {
+      const _full = this.validate;
+      const _fast = this._fastVerdict;
+      const EMPTY_ERRORS = Object.freeze([]);
+      const _buildErrors = (data) => {
+        const r = _full(data);
+        return (r && r.valid === false && r.errors && r.errors.length)
+          ? r.errors
+          // The data changed between the verdict and this read; keep the
+          // verdict and say so rather than inventing a specific error.
+          : [{ keyword: 'validation', instancePath: '', schemaPath: '#', params: {}, message: 'schema validation failed' }];
+      };
+      this.validate = (data) => {
+        if (_fast(data)) return { valid: true, data, errors: EMPTY_ERRORS };
+        return new LazyRejection(_buildErrors, data);
+      };
+    }
+
     // The buffer APIs answer from the native walker, which disagrees with
     // validate() on shapes listed in lib/buffer-gate.js. For those schemas
     // every buffer entry point goes through validate() instead.

package/lib/aot.js

@@ -21,7 +21,7 @@ const SAFE_REGEX_SOURCE = require('./safe-regex-source');
 const _CP_LEN_SOURCE = `function _cpLen(s) {
   const len = s.length;
   for (let i = 0; i < len; i++) {
-    if (s.charCodeAt(i) >= 0xD800 && s.charCodeAt(i) <= 0xDBFF) {
+    if (((s.charCodeAt(i) - 0xD800) >>> 0) < 0x400) {
       let n = 0; for (const _ of s) n++; return n;
     }
   }