ata-validator 1.45.0 → 1.46.1

package/README.md

@@ -244,15 +244,15 @@ 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 | **2.1 KB** | 112.8 KB |
-| Time to a served request | **3.5 ms** | 8.6 ms |
+| In a bundle, gzipped | **2.1 KB** | 113.3 KB |
+| Time to a served request | **3.5 ms** | 8.5 ms |
 | Schema known when | build time | any time |
 
 The bundle row is the ten-field user schema in
 `tests/fixtures/error-dx/user.schema.json`, every export of the compiled module against
-`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.44.0.
+`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.45.0.
 The startup row is a Hono route on Bun 1.4, the median of three rounds of best-of-seven, from
-`benchmark/bundle`, against 3.5 ms for the same app doing no validation at all, so the
+`benchmark/bundle`, 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
@@ -278,7 +278,7 @@ const v = new Validator(schema)
 const result = v.validate(data)
 ```
 
-The runtime API is unchanged from previous releases. Code written against the default validator's class keeps working through `ata-validator/compat`, which covers `compile`, `addSchema`, `addFormat`, `addKeyword`, `errorsText` and the rest of that surface, and reports errors in the same shape and order. See [docs/migration-from-ajv.md](docs/migration-from-ajv.md).
+The runtime API is unchanged from previous releases. Code written against the default validator's class keeps working through `ata-validator/compat`, which covers `compile`, `addSchema`, `addFormat`, `addKeyword`, `errorsText` and the rest of that surface, and reports errors in the same shape and order. `npx ata migrate` reports what the switch would change in a project, and what it cannot translate, before anything is written. See [docs/migration-from-ajv.md](docs/migration-from-ajv.md).
 
 ## Usage
 
@@ -491,7 +491,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. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.1 KB gzipped, full error detail included, against 112.8 KB for the runtime bundled for the browser (ata 1.44.0).
+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. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.1 KB gzipped, full error detail included, against 113.3 KB for the runtime bundled for the browser (ata 1.45.0).
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs
@@ -533,11 +533,11 @@ npx ata build 'schemas/*.json' --out-dir build/validators --check
 Run with `--watch` during development for incremental rebuilds.
 
 Bundle sizes for the 10-field user schema in `tests/fixtures/error-dx/user.schema.json`,
-minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.44.0:
+minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.45.0:
 
 | What the app imports | Size | Notes |
 |---|---|---|
-| `Validator` from `ata-validator` | 112.8 KB | The compiler ships with it, because a runtime schema can use any keyword |
+| `Validator` from `ata-validator` | 113.3 KB | The compiler ships with it, because a runtime schema can use any keyword |
 | `isValid` from the compiled module | **1.3 KB** | Nothing else is reachable, so the error collector is dropped |
 | `validate` from the compiled module | **1.9 KB** | Adds the detailed error collector |
 
@@ -575,7 +575,7 @@ 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.4 ms, ata 2.7 ms, no build step required.** ata registers in 0.2 ms of that and
+ajv 19.7 ms, ata 2.75 ms, no build step required.** ata registers in 0.25 ms of that and
 compiles on the first request, so counting only registration would overstate the gap.
 Reproduce with `node benchmark/bench_fastify_boot.mjs`.
 

package/bin/ata.js

@@ -11,6 +11,7 @@ Usage:
   ata compile  <schema-file> [options]  Compile one schema to a standalone module.
   ata build    <glob>...     [options]  Compile a project's schemas (glob pattern) per file.
   ata validate <schema> <data> [options] Validate a JSON data file against a schema.
+  ata migrate  [dir]         [options]  Report what switching from ajv would change; --write applies it.
 
 Validate options:
   --pretty                Render errors with source frames (default on TTY)
@@ -29,6 +30,11 @@ Compile options:
   --source                Embed schema source map (default in development)
   --no-source             Omit source map (default in production, NODE_ENV=production)
 
+Migrate options:
+  --write                 Apply the mechanical changes (import specifiers, addFormats calls).
+                          Without it the command only reports. Exit code 1 when a site
+                          needs a reader, so it can run as a readiness check in CI.
+
 Build options:
   --out-dir <dir>         Write outputs into this directory instead of alongside sources
   --suffix <str>          Output filename suffix (default: ".compiled")
@@ -98,6 +104,7 @@ function parseArgs(argv) {
       continue;
     }
     if (a === '--watch') { out.opts.watch = true; continue; }
+    if (a === '--write') { out.opts.write = true; continue; }
     if (a === '--source') { out.opts.source = true; continue; }
     if (a === '--no-source') { out.opts.source = false; continue; }
     if (a === '--dual') { out.opts.dual = true; continue; }
@@ -451,6 +458,15 @@ function main() {
     return;
   }
 
+  if (cmd === 'migrate') {
+    const { migrate, formatReport } = require('../lib/migrate');
+    const result = migrate(args._[0] || '.', { write: !!args.opts.write });
+    process.stdout.write(formatReport(result, { write: !!args.opts.write }) + '\n');
+    // Non-zero when something needs a reader, so the command works as a
+    // readiness check in CI.
+    process.exit(result.flagged > 0 ? 1 : 0);
+  }
+
   process.stderr.write(`error: unknown command "${cmd}"\n\n`);
   usage();
   process.exit(1);

package/index.js

@@ -243,14 +243,15 @@ function installCodegenPaths (ctx) {
     this.validate = preprocess
       ? (data) => { preprocess(data); return _fn(data) ? VALID_RESULT : ABORT_EARLY_RESULT; }
       : (data) => (_fn(data) ? VALID_RESULT : ABORT_EARLY_RESULT);
-  } else if (hasDynRef && _isCodegen && jsFn) {
-    // $dynamicRef with JS codegen: direct path, no wrapper layers
-    const _fn = jsFn, _efn = errOnly, _R = VALID_RESULT;
-    this.validate = preprocess
-      ? (data) => { preprocess(data); return _fn(data) ? _R : _efn(data); }
-      : (data) => _fn(data) ? _R : _efn(data);
-  } else if (hasDynRef) {
-    // $dynamicRef without codegen: the interpreted engine. It scores the
+  } else if (hasDynRef && !(_isCodegen && jsFn)) {
+    // $dynamicRef without codegen: the interpreted engine. A schema the
+    // generators unroll by scope (expandDynamicScopes) takes the assembly
+    // below like any other, with the one-pass function once its errors are
+    // read; a direct verdict-then-error-function path kept for these from
+    // before the unrolling cost the suite's dynamicRef groups 5229 ns a pass
+    // where the assembly answers in 3136. (A first attempt dropped them into
+    // this interpreter branch instead and measured slower; the condition
+    // here is what makes them fall through.) 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) {
@@ -545,7 +546,8 @@ installCodegenPaths.compileVerdict = function compileVerdict () {
 // validateJSON and isValidJSON over a schema-directed scanner, which answers
 // from the JSON text without building the document.
 installCodegenPaths.installScanner = function installScanner (schemaObj, options) {
-  const { ABORT_EARLY_RESULT, VALID_RESULT, _bindEntry } = core._internals;
+  const { ABORT_EARLY_RESULT, VALID_RESULT, _bindEntry, _jsonSyntaxRejection } = core._internals;
+  let textRejects = 0;
   const self = this;
   // Generating a scanner costs about 20 microseconds, measured, and it
   // saves from around 85 nanoseconds on a small accepted document to
@@ -619,16 +621,58 @@ installCodegenPaths.installScanner = function installScanner (schemaObj, options
   {
     const validateByParsing = this.validateJSON;
     const abortEarly = !!options.abortEarly;
+      // A validator whose errors are being read answers validate() with
+      // the one-pass function (the switch in lib/validator-core.js), and
+      // without richErrors nothing it hands out depends on the text. A
+      // rejected text is then parsed and given to that function directly,
+      // instead of to the layers below, which parsed it, decided again and
+      // wrapped a rejection whose errors are built on first read: a 1.7 KB
+      // rejected body took 9.2 microseconds through those layers.
+      // The scanner itself is the other half of that cost on a rejected
+      // text (2.7 of the 9.2 on that body) and all the saving on an accepted
+      // one, which it answers without parsing. So the scan runs while the
+      // texts a validator sees are mostly accepted, and is skipped while
+      // they are mostly rejected: `bias` counts rejections against
+      // acceptances, from either path, and the mode follows its sign with
+      // some room, so a mixed stream does not flip on every document.
+      const onePassText = (text) => {
+        let op = self._onePass;
+        // A validator rejecting text only never reads through the object
+        // path's switch; the second rejected text makes it.
+        if (op === undefined && self._tierOnePass !== undefined && ++textRejects >= 2) { op = self._tierOnePass() || undefined; if (op === undefined) self._tierOnePass = undefined; }
+        if (op === undefined) return undefined;
+        let obj;
+        try { obj = JSON.parse(text); } catch (e) { if (!(e instanceof SyntaxError)) throw e; return _jsonSyntaxRejection(e); }
+        return op(obj);
+      };
     this.validateJSON = (jsonStr) => {
       const scan = self._ensureScanner();
       if (scan === undefined) return validateByParsing(jsonStr);
-      if (scan === null) { _bindEntry(self, 'validateJSON', validateByParsing); return validateByParsing(jsonStr); }
+      if (scan === null) {
+        // No scanner for this schema: the one-pass function still answers a
+        // lean validator's texts directly once it is installed.
+        _bindEntry(self, 'validateJSON', self._richErrors ? validateByParsing : (text) => {
+          if (typeof text === 'string') { const o = onePassText(text); if (o !== undefined) return o; }
+          return validateByParsing(text);
+        });
+        return self.validateJSON(jsonStr);
+      }
+      let bias = 0;
       _bindEntry(self, 'validateJSON', (text) => {
         if (typeof text === 'string') {
+          if (bias > 16 && !self._richErrors && self._onePass !== undefined) {
+            const r = onePassText(text);
+            if (r !== undefined) { if (r.valid) { if (--bias < -32) bias = -32; } else if (bias < 64) bias++; return r; }
+          }
           const r = scan(text);
-          if (r === 1) return VALID_RESULT;
+          if (r === 1) { if (--bias < -32) bias = -32; return VALID_RESULT; }
           if (r === 0) {
+            if (bias < 64) bias++;
             if (abortEarly) return ABORT_EARLY_RESULT;
+            if (!self._richErrors) {
+              const o = onePassText(text);
+              if (o !== undefined) return o;
+            }
             self._skipNativeFast = true;
             try {
               return validateByParsing(text);
@@ -637,6 +681,9 @@ installCodegenPaths.installScanner = function installScanner (schemaObj, options
             }
           }
         }
+        // The scanner could not decide (a shape it does not read): the
+        // one-pass function answers a lean validator here too.
+        if (!self._richErrors && typeof text === 'string') { const o = onePassText(text); if (o !== undefined) return o; }
         return validateByParsing(text);
       });
       return self.validateJSON(jsonStr);
@@ -870,7 +917,21 @@ function buildParse (self, decline, extended) {
       if (self._mutatesInput) {
         try { target = structuredClone(data); } catch { target = data; }
       }
-      e.errors = self.validate(target).errors;
+      // The errors are worked out when first read, as validate() works them
+      // out: building every error with its enrichment before throwing made a
+      // rejected parse() cost about 12 µs on a document with 16 violations,
+      // most of it for callers that only catch. Read once, the list stays.
+      const rejection = self.validate(target);
+      Object.defineProperty(e, 'errors', {
+        configurable: true,
+        enumerable: true,
+        get () {
+          const errors = rejection.errors;
+          Object.defineProperty(e, 'errors', { value: errors, writable: true, configurable: true, enumerable: true });
+          return errors;
+        },
+        set (v) { Object.defineProperty(e, 'errors', { value: v, writable: true, configurable: true, enumerable: true }); },
+      });
       throw e;
     }
     return copy(data);

package/lib/branch-collapse.js

@@ -112,4 +112,4 @@ function embedSource () {
     'const __ataCollapse=' + __ataCollapse.toString() + ';';
 }
 
-module.exports = { collapseBranches, scoreBranch: __ataScore, SEVERITY: __ATA_SEVERITY, embedSource };
+module.exports = { collapseBranches, scoreBranch: __ataScore, SEVERITY: __ATA_SEVERITY, embedSource, _collapse: __ataCollapse, _multi: __ataMulti };

package/lib/combined-runtime.js

@@ -0,0 +1,149 @@
+'use strict'
+
+// What the one-pass (combined) function needs at run time and does not need
+// a copy of: one module-level implementation each, handed to every compiled
+// program as a closure value. Each program used to carry its own copy of
+// these in its source, so a thousand validators meant a thousand `_ap`s, a
+// thousand `__ataCollapse`s and so on, each parsed, each compiled by the
+// baseline compiler, each queued for the optimizing compiler on its own.
+// On the official suite, with about a thousand validators in one process,
+// the optimizing compiler got to 728 functions in five seconds, and the
+// validators themselves (`_vC`) were 242 of those. Shared, a helper is
+// compiled once and is hot from the second validator on. The generated
+// standalone modules (lib/aot-impl.js) are not built from this generator and
+// keep their own embedded copies.
+
+// The error list's order, kept as it grows (see apOrd in lib/js-compiler.js):
+// `os` the ordinal of each error in push order, `mo` whether they are still in
+// order, `lo` the last ordinal. One state per compiled program, reset at the
+// top of each call.
+function apState () { return { mo: true, lo: -1, on: 0, os: [] } }
+
+// Whether a collapsed error holds, at any depth, a branch list of more than
+// one error, which only the reader puts in schema order.
+function multiBranch (x) {
+  for (let b = x.branchErrors; b !== undefined; b = b[0].branchErrors) {
+    if (b.length > 1) return true
+    if (b.length === 0) return false
+  }
+  return false
+}
+
+// Append one error, keeping whether the list is still in the reader's order.
+function ap (S, e, x, o) {
+  // Keys are dense integers in the reader's order (ordinal, then the rank of
+  // the path), given per program when it is assembled (assignOrdKeys in
+  // lib/js-compiler.js): two errors with one exact key are ones the reader
+  // keeps as they came. -1 is a key the program does not know. Below -1 is a
+  // coarse key, -(k+2): every error behind a reference into a shared
+  // definition takes the key k of the reference that reached it, so two of
+  // them with one key and different paths are ordered by the reader.
+  if (o < 0) {
+    if (o === -1) S.mo = false
+    else {
+      const k = -o - 2
+      if (k < S.lo || (k === S.lo && (e === undefined || x.schemaPath !== e[e.length - 1].schemaPath))) S.mo = false
+      else S.lo = k
+    }
+  } else if (o < S.lo) S.mo = false
+  else S.lo = o
+  // A collapsed branch error's own lists, at any depth, are ordered by the
+  // reader (sr hands such a list to it); an in-order outer list must still
+  // get there.
+  if (x.branchErrors !== undefined && multiBranch(x)) S.mo = false
+  S.os[S.on++] = o
+  if (e === undefined) return [x]
+  e.push(x)
+  return e
+}
+
+// Put a list that did not come in order into order by the ordinals collected
+// beside it: a stable insertion sort over a few integers. The reader's sort
+// (`srt`) still answers where a key is unknown (-1), where two errors share a
+// coarse key but not a path, where a collapsed error holds a branch list of
+// more than one error, and for long lists.
+function sr (S, e, srt) {
+  const n = e.length
+  const os = S.os
+  if (n > 16 || n !== S.on) return srt(e)
+  let coarse = 0
+  for (let i = 0; i < n; i++) {
+    let k = os[i]
+    if (k < 0) {
+      if (k === -1) return srt(e)
+      k = -k - 2
+      os[i] = k
+      coarse |= 1 << i
+    }
+    // A collapsed branch error carries the closest branch's errors, which
+    // the reader puts in schema order too; one error needs no ordering.
+    if (e[i].branchErrors !== undefined && multiBranch(e[i])) return srt(e)
+  }
+  // Two errors with one key and different paths, one of them coarse: the
+  // reader ranks their paths.
+  if (coarse !== 0) {
+    for (let i = 1; i < n; i++) {
+      for (let j = 0; j < i; j++) if (os[j] === os[i] && ((coarse >> i | coarse >> j) & 1) && e[j].schemaPath !== e[i].schemaPath) return srt(e)
+    }
+  }
+  for (let i = 1; i < n; i++) {
+    const k = os[i]
+    const x = e[i]
+    let j = i - 1
+    while (j >= 0 && os[j] > k) { os[j + 1] = os[j]; e[j + 1] = e[j]; j-- }
+    os[j + 1] = k
+    e[j + 1] = x
+  }
+  return e
+}
+
+// `sr` checked against the reader's order on every list; the test suites run
+// the generator with ATA_CHECK_SORT set, which routes here.
+function srX (S, e, srt) {
+  const c = e.slice()
+  const k = S.os.slice(0, S.on)
+  const a = sr(S, e, srt)
+  const b = srt(c)
+  if (a.length !== b.length || a.some((x, i) => x.schemaPath !== b[i].schemaPath || x.instancePath !== b[i].instancePath)) {
+    throw new Error('ata: local error sort disagrees with the reader ' + JSON.stringify(a.map((x) => x.schemaPath)) + ' vs ' + JSON.stringify(b.map((x) => x.schemaPath)) + ' keys ' + JSON.stringify(k))
+  }
+  return a
+}
+
+// Presence helpers (see OWN_HELPER_CODE in lib/js-compiler.js for the text
+// the standalone modules carry). The prototype test itself stays inline in
+// the generated code, read once per object: a shared helper reading the
+// prototype of every object it was asked about was megamorphic.
+const _PN = ({}).__proto__ === Object.prototype // eslint-disable-line no-proto
+const _OP = Object.prototype
+const _gp = Object.getPrototypeOf
+const _hop = Object.prototype.hasOwnProperty
+function _h (o, k) { return _hop.call(o, k) }
+function _ok (o, k) { return (_PN ? o.__proto__ : _gp(o)) === _OP || _hop.call(o, k) } // eslint-disable-line no-proto
+function _hall (o, ks) { for (let i = 0; i < ks.length; i++) if (!_hop.call(o, ks[i])) return false; return true }
+
+// RFC 6901 escaping for a key only known at run time (the static ones are
+// escaped when the code is written).
+function _pe (s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c === 126 || c === 47) return s.replace(/~/g, '~0').replace(/\//g, '~1')
+  }
+  return s
+}
+
+// The annotation functions' constants (emitAnnot): the boolean schemas, and
+// the rollback of the evaluated-name list when a branch fails.
+function _anT () { return true }
+function _anF () { return false }
+function _rb (S, m) { if (S.length !== m) S.length = m }
+
+module.exports = {
+  apState, ap, sr, srX,
+  _PN, _OP, _gp, _hop, _h, _ok, _hall, _pe, _anT, _anF, _rb,
+}
+// Loaded when a program first asks for them: a schema without const, enum,
+// uniqueItems, oneOf or anyOf never needs these modules on its cold path.
+Object.defineProperty(module.exports, '_deq', { enumerable: true, get () { return require('./unique-items')._deq } })
+Object.defineProperty(module.exports, '__ataCollapse', { enumerable: true, get () { return require('./branch-collapse')._collapse } })
+Object.defineProperty(module.exports, '__ataMulti', { enumerable: true, get () { return require('./branch-collapse')._multi } })

package/lib/interpreter.js

@@ -1251,7 +1251,7 @@ module.exports = { createInterpreter };
 // The resolver, for the code generator: it resolves references at compile
 // time the way this engine does at run time (normalizeRefs in js-compiler).
 Object.defineProperty(module.exports, '_refInternals', {
-  value: { indexSchemas, resolveRef, FALLBACK_BASE },
+  value: { indexSchemas, resolveRef, splitFragment, resolveUri, FALLBACK_BASE },
   enumerable: false,
 });
 // For lib/plan-source.js, which emits source from the same plans and must call