ata-validator 1.0.2 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.2.0 - 2026-07-18
+
+### Added
+
+- An interpreted engine (`lib/interpreter.js`) now backs schemas the JS compiler cannot represent when the native addon is absent (browser, edge workers, `ATA_NO_NATIVE=1`). These schemas validated only with the native engine before, and 1.1.0 made them throw a clear error in native-less environments; they now just validate. Full draft 2020-12 semantics: `$id`/`$anchor` resolution, `$dynamicRef` dynamic scoping, annotation tracking for `unevaluatedProperties`/`unevaluatedItems`. The pure-JS configuration now passes 1184 of 1190 applicable cases (99.5%) in the official test suite, up from 974, and the six remaining failures are shared with the native engine. Error results on the native-less path also carry full per-keyword detail now instead of a single generic message.
+
+### Changed
+
+- Validation errors now follow the schema's keyword declaration order instead of a fixed required-first order: a schema declaring `properties` before `required` reports the property errors first, matching what schema authors read top to bottom and what the previous default validator emitted. Order within one keyword is unchanged (`required` errors still follow the array). Single-error and `abortEarly` results are untouched. With this change ata passes every applicable test in Fastify's validation suite (181 of 187; the remaining 6 test the incumbent validator's own extension API rather than validation behavior).
+
+## 1.1.0 - 2026-07-18
+
+### Added
+
+- TypeBox-style modifier combinators on `ata-validator/t`: `t.pick`, `t.omit`, `t.partial`, `t.required`, `t.composite`, and `t.recursive`. All six emit plain JSON Schema, so `Infer`, the runtime validator, and the AOT pipeline consume them with no adapter. This closes the authoring-parity gap for TypeBox migrations. Note: `t.recursive` schemas validate through the interpreted engine and are not AOT-precompilable; the other five combinators AOT-compile like any schema.
+
+### Changed
+
+- The `ata-validator` package is now pure JavaScript: no bundled binaries, no vendored C++ sources, no install script. The native engine moved to per-platform `@ata-validator/native-*` packages, installed automatically as optional dependencies (the same pattern Vite uses for esbuild). The tarball shrinks from ~5.3 MB to under 300 KB. `npm install --omit=optional` or `ATA_NO_NATIVE=1` gives a guaranteed zero-binary setup; validation behavior is identical for every schema shape the JS engine compiles, and the few shapes that still need the native engine now throw a clear error instead (see Fixed below).
+
+### Fixed
+
+- Schemas the JS engine cannot compile (some `$dynamicRef`, cyclic `$ref`, and unusual keyword interactions) crashed with `Maximum call stack size exceeded` in environments without the native addon: the lazy `validate` stub and the rich-error wrapper dispatched to each other forever. These schemas now throw a clear "not supported by the pure-JS engine" error on first use. The same cycle could hit `isValidObject` even with the native addon present when it was the first method called; it now falls through to the full compile and validates correctly.
+
 ## 1.0.2 - 2026-07-17
 
 ### Fixed

package/README.md

@@ -14,6 +14,14 @@ npm install --save-dev ata-validator
 npx ata build 'schemas/*.json' --out-dir src/generated
 ```
 
+The `ata-validator` package itself is pure JavaScript. The native accelerator (simdjson parsing, parallel NDJSON, buffer APIs) ships as per-platform optional packages that npm installs automatically where they fit, the same pattern Vite uses for esbuild. For a guaranteed zero-binary install:
+
+```bash
+npm install ata-validator --omit=optional
+```
+
+or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup passes 99.5% of the official draft 2020-12 test suite. Only the buffer and parallel APIs (`isValid` on raw buffers, `countValid`, `batchIsValid`, `validateAndParse`) need the native engine and say so with a clear error.
+
 In your code:
 
 ```ts
@@ -227,7 +235,14 @@ type User = Infer<typeof User>
 const v = new Validator(User)
 ```
 
-The builder covers primitives (`string`, `number`, `integer`, `boolean`, `null`), composites (`object` with `optional` keys, `array`, `tuple`, `record`, `union`, `intersect`, `literal`, `const`, `enum`), and refs (`ref`). Optionality is carried by a Symbol marker that the emitted JSON Schema and ata's codegen never see, so the output is still a plain JSON Schema literal that you can pass to anything that takes one.
+The builder covers primitives (`string`, `number`, `integer`, `boolean`, `null`), composites (`object` with optional keys, `array`, `tuple`, `record`, `union`, `intersect`, `literal`, `const`, `enum`), plus the TypeBox-style modifiers `pick`, `omit`, `partial`, `required`, `composite`, and `recursive`. Optionality is carried by a Symbol marker that the emitted JSON Schema and ata's codegen never see, so the output is still a plain JSON Schema literal that you can pass to anything that takes one.
+
+```ts
+const User = t.object({ id: t.integer(), name: t.string(), email: t.optional(t.string()) })
+const Patch = t.partial(t.omit(User, ['id']))
+type Patch = Infer<typeof Patch>
+// { name?: string; email?: string }
+```
 
 #### Async refinement
 
@@ -462,6 +477,8 @@ If one of these blocks you, open an issue; scope decisions get revisited with re
 
 ## Building from Source
 
+This section applies to contributors building the repository. Regular `npm install` users need not have a C++ toolchain.
+
 ### Development prerequisites
 
 Native builds require C/C++ toolchain support and the following libraries:
@@ -470,7 +487,7 @@ Native builds require C/C++ toolchain support and the following libraries:
 - `abseil`
 - `mimalloc`
 
-Install them before running `npm install` / `npm run build`:
+Install them before running `npm run build`:
 
 ```bash
 # macOS (Homebrew)

package/index.js

@@ -1,7 +1,7 @@
 // Native addon: optional. Core validate() uses JS codegen and works without it.
 // Buffer APIs (isValid, countValid, isValidParallel) require native.
-// Loading is delegated so this file stays free of `pkg-prebuilds`/`__dirname`/
-// `path` (the browser entry must not pull those in via the bundler).
+// Loading is delegated to lib/native-load.js so this file stays free of
+// platform probing and `path` (the browser entry must not pull those in).
 const native = require("./lib/native-load")();
 const {
   compileToJS,
@@ -319,6 +319,47 @@ function resolveSchemaByPath(rootSchema, schemaPath) {
   return target;
 }
 
+// Rank an error by walking its schemaPath through the schema object: at each
+// level the segment's index among the node's declared keys. Comparing ranks
+// lexicographically orders errors by keyword declaration order, which is the
+// order AJV emits and what schema authors read top to bottom. Segments that
+// cannot be resolved (cross-schema refs, normalized keys) end the walk; the
+// stable sort then keeps such errors in engine emission order.
+function schemaOrderRank(rootSchema, schemaPath) {
+  if (!schemaPath || typeof schemaPath !== 'string' || !schemaPath.startsWith('#')) return null;
+  const parts = schemaPath.slice(1).split('/').filter(Boolean).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  const rank = [];
+  let node = rootSchema;
+  for (const seg of parts) {
+    if (node == null || typeof node !== 'object') break;
+    if (Array.isArray(node)) {
+      const idx = Number(seg);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= node.length) break;
+      rank.push(idx);
+      node = node[idx];
+    } else {
+      const idx = Object.keys(node).indexOf(seg);
+      if (idx < 0) break;
+      rank.push(idx);
+      node = node[seg];
+    }
+  }
+  return rank;
+}
+
+function sortErrorsBySchemaOrder(rootSchema, errors) {
+  const ranked = errors.map((e, i) => ({ e, i, rank: schemaOrderRank(rootSchema, e.schemaPath) }));
+  ranked.sort((a, b) => {
+    if (!a.rank || !b.rank) return a.i - b.i;
+    const n = Math.min(a.rank.length, b.rank.length);
+    for (let k = 0; k < n; k++) {
+      if (a.rank[k] !== b.rank[k]) return a.rank[k] - b.rank[k];
+    }
+    return a.i - b.i;
+  });
+  return ranked.map((r) => r.e);
+}
+
 function parsePointerPath(path) {
   if (!path) return [];
   return path
@@ -569,6 +610,10 @@ class Validator {
         };
       } else {
         this._ensureCodegen();
+        // Codegen can bail on shapes it cannot represent; the full compile
+        // binds the native path or the unsupported thrower instead of
+        // leaving this stub to re-dispatch to itself.
+        if (!this._jsFn) this._ensureCompiled();
       }
       return this.isValidObject(data);
     };
@@ -721,16 +766,32 @@ class Validator {
       // invalid path doesn't dereference a null _compiled.
       const hasUnevaluated = schemaObj && (schemaObj.unevaluatedProperties !== undefined || schemaObj.unevaluatedItems !== undefined || this._schemaStr.includes('unevaluatedProperties') || this._schemaStr.includes('unevaluatedItems'))
       const hasDynRef = this._schemaStr.includes('"$dynamicRef"') || this._schemaStr.includes('"$dynamicAnchor"')
-      const jsOnlyFallback = (d) => ({
-        valid: jsFn(d),
-        errors: jsFn(d) ? [] : [{
-          keyword: 'validation',
-          instancePath: '',
-          schemaPath: '',
-          params: {},
-          message: 'schema validation failed (detailed errors unavailable without native addon)'
-        }]
-      });
+      // Native-less error path: the interpreted engine re-validates failing
+      // data to produce full errors. If it disagrees with the codegen verdict
+      // (it should not), a generic error keeps the result consistent.
+      let _interp = null;
+      const jsOnlyFallback = (d) => {
+        if (jsFn(d)) return { valid: true, data: d, errors: [] };
+        if (!_interp) {
+          const { createInterpreter } = require('./lib/interpreter');
+          _interp = createInterpreter(schemaObj, {
+            schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
+            formats: this._userFormats,
+          });
+        }
+        const r = _interp.validate(d);
+        if (!r.valid) return r;
+        return {
+          valid: false,
+          errors: [{
+            keyword: 'validation',
+            instancePath: '',
+            schemaPath: '',
+            params: {},
+            message: 'schema validation failed'
+          }]
+        };
+      };
       const errFn =
         safeErrFn ||
         (hasUnevaluated
@@ -1004,6 +1065,43 @@ class Validator {
           return valid;
         };
       }
+    } else {
+      // No JS codegen and no native engine: fall back to the interpreted
+      // engine. Slow but correct, and strictly better than the previous
+      // behavior (the lazy stubs re-dispatched to themselves forever).
+      const { createInterpreter } = require('./lib/interpreter');
+      const interp = createInterpreter(schemaObj, {
+        schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
+        formats: this._userFormats,
+      });
+      const run = preprocess
+        ? (data) => { preprocess(data); return interp.validate(data); }
+        : (data) => interp.validate(data);
+      this.validate = run;
+      this.isValidObject = (data) => run(data).valid;
+      this.validateJSON = (jsonStr) => {
+        try {
+          return run(JSON.parse(jsonStr));
+        } catch (e) {
+          return { valid: false, errors: [{ keyword: 'syntax', instancePath: '', schemaPath: '#', params: {}, message: e.message }] };
+        }
+      };
+      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.
+    if (this.validate) {
+      const inner = this.validate;
+      const root = this._schemaObj;
+      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

package/lib/aot.js

@@ -1,7 +1,7 @@
 'use strict';
 
 // All ahead-of-time (AOT) code generation lives here so the default and browser
-// entries can stay free of `fs`, `path`, `__dirname`, and `pkg-prebuilds`.
+// entries can stay free of `fs`, `path`, and `__dirname`.
 // Browser bundles get `lib/aot.browser.js` instead (see package.json `browser`
 // field), which throws if anyone tries to call an AOT function from the browser.
 //