ata-validator 1.46.1 → 1.48.0

package/README.md

@@ -43,6 +43,16 @@ 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 scores the same on the official suite as the native one, 1301 of 1301 Draft 2020-12 cases. The buffer and parallel APIs (`isValid` on raw buffers, `isValidPrepadded`, `isValidNDJSON`, `isValidParallel`, `countValid`, `batchIsValid`, `validateAndParse`) work without the addon too, answering through the same checks as `isValidJSON()`, slower than the addon: 177 ns against 92 for a small document on Node 25. In a browser, which has no `Buffer`, they throw and name the methods to use instead.
 
+Where the size of what ships matters more than nanoseconds per call, `ata-validator/lite` is
+the same `Validator` on the interpreted engine alone, without the code generator: the same
+verdicts and errors, 58 KB gzipped in a bundled worker against 136 KB for the full entry.
+It leaves out what needs the generator, `parse()` and the ahead-of-time bundle methods.
+
+On Deno the same package is `npm:ata-validator` or `jsr:@ata/validator`; the JSR package
+re-exports the npm one at the same version, and CI runs the official suite under Deno. The
+details, and what Deno Deploy's refusal of dynamic code means for it, are in
+[docs/edge-runtimes.md](docs/edge-runtimes.md).
+
 Those four now agree with `validate()` on every case of the official suite, 3365 across three dialects. The native walker behind them does not handle every shape (`contains`, `unevaluatedProperties`, `patternProperties`, tuple `items`, cross-document `$ref`, a few formats), so for schemas using one of those the buffer APIs parse the bytes and answer through `validate()`; the list is in `lib/buffer-gate.js`. Typical request schemas stay on the zero-copy path. `npm test` holds the disagreement count at zero.
 
 Where `new Function` is refused altogether, on Cloudflare Workers, Deno Deploy or under a strict Content-Security-Policy, ata drops to the interpreted engine and scores the same 1301 of 1301 with code generation blocked. No flags, and on Workers no `nodejs_compat` either. See [docs/edge-runtimes.md](docs/edge-runtimes.md).
@@ -103,18 +113,18 @@ file.
 
 | Dimension | Schema | ata-AOT | runtime validator | Difference |
 |---|---|---|---|---|
-| Bundle (gzipped) | simple | 1.3 KB | 58.1 KB | 43.9x smaller |
-| Bundle (gzipped) | complex | 7.8 KB | 58.1 KB | 7.4x smaller |
-| Bundle (gzipped) | nested | 4.5 KB | 58.1 KB | 12.9x smaller |
-| Cold start | simple | 22 ms | 40 ms | 1.8x faster |
-| Throughput (1M ops) | simple | 269 Mops/s | 116 Mops/s | 2.3x faster |
-| Compile time | simple | 19 µs | 1.63 ms | 85x faster |
+| Bundle (gzipped) | simple | 1.4 KB | 52.7 KB | 38.4x smaller |
+| Bundle (gzipped) | complex | 3.0 KB | 52.7 KB | 17.5x smaller |
+| Bundle (gzipped) | nested | 4.5 KB | 52.7 KB | 11.6x smaller |
+| Cold start | simple | 20 ms | 37 ms | 1.9x faster |
+| Throughput (1M ops) | simple | 289 Mops/s | 96 Mops/s | 3.0x faster |
+| Compile time | simple | 18 µs | 1.56 ms | 85x 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-09-28,
-on ata-validator 1.36.0. Across four runs throughput moved between 213 and 269 Mops/s against
-94 to 116, cold start between 21 and 22 ms against 40 to 42, and the compile ratio between 79x
-and 90x. The throughput row times a single one-million-call
+with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple M4 Pro, Node 25.2.1, 2026-10-06,
+on ata-validator 1.46.0. Across four runs throughput moved between 288 and 329 Mops/s against
+96 to 116, cold start between 19 and 20 ms against 37 to 39, and the compile ratio between 77x
+and 85x. The throughput row times a single one-million-call
 loop of a few milliseconds, so it moves the most from run to run; treat the last three rows as
 an order of magnitude rather than a constant.
 
@@ -244,15 +254,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** | 113.3 KB |
-| Time to a served request | **3.5 ms** | 8.5 ms |
+| In a bundle, gzipped | **2.1 KB** | 125.0 KB |
+| Time to a served request | **3.5 ms** | 7.6 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.45.0.
+`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.47.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.7 ms for the same app doing no validation at all, so the
+`benchmark/bundle`, against 3.5 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
@@ -280,6 +290,15 @@ 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. `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).
 
+Coming from the default validator, one command reports what the switch touches and a second applies the mechanical part:
+
+```bash
+npx ata migrate            # per file: imports to rewrite, addFormats() calls that go, sites to look at by hand
+npx ata migrate --write    # rewrites the imports to ata-validator/compat and removes the calls, leaves the rest
+```
+
+Coercion, defaults, `allErrors` and the error objects behave as before; the details and the limits are in [docs/migration-from-ajv.md](docs/migration-from-ajv.md).
+
 ## Usage
 
 ### Node.js

package/bin/ata.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 'use strict';
+const { env } = require('../lib/env');
 
 const fs = require('fs');
 const path = require('path');
@@ -27,6 +28,8 @@ Compile options:
   --name <TypeName>       Name of the top-level type in .d.ts. Default: inferred from filename
   --no-types              Skip .d.ts generation
   --abort-early           Use stub errors (smallest bundle)
+  --one-pass              Report errors with the runtime's one-pass function: faster on
+                          rejected documents, a module 1.3 to 1.7x the size
   --source                Embed schema source map (default in development)
   --no-source             Omit source map (default in production, NODE_ENV=production)
 
@@ -40,6 +43,8 @@ Build options:
   --suffix <str>          Output filename suffix (default: ".compiled")
   -f, --format <fmt>      Module format: esm | cjs. Default: esm
   --abort-early           Use stub errors (smallest bundle)
+  --one-pass              Report errors with the runtime's one-pass function: faster on
+                          rejected documents, a module 1.3 to 1.7x the size
   --check                 Check (don't write); exit 1 if any output is stale
   --cache-file <path>     Cache file for incremental builds (default: cache disabled)
   --max-size <bytes>      Fail build if any compiled module exceeds this gzipped size
@@ -88,6 +93,7 @@ function parseArgs(argv) {
     if (a === '--name') { out.opts.name = argv[++i]; continue; }
     if (a === '--no-types') { out.opts.types = false; continue; }
     if (a === '--abort-early') { out.opts.abortEarly = true; continue; }
+    if (a === '--one-pass') { out.opts.onePass = true; continue; }
     if (a === '--check') { out.opts.check = true; continue; }
     if (a === '--strict') { out.opts.strict = true; continue; }
     if (a === '--strict-schema') { out.opts.strictSchema = true; continue; }
@@ -130,7 +136,7 @@ function parseArgs(argv) {
 function resolveSourceDefault (opts) {
   if (opts.source === true) return true;
   if (opts.source === false) return false;
-  return process.env.NODE_ENV !== 'production';
+  return env('NODE_ENV') !== 'production';
 }
 
 function inferOutput(inputPath, format) {
@@ -232,7 +238,7 @@ function cmdCompile(args) {
   }
   const schemaFile = path.relative(process.cwd(), input) || input;
   const compileWarnings = [];
-  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onWarning: (w) => compileWarnings.push(w) });
+  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onePass: args.opts.onePass === true ? true : undefined, onWarning: (w) => compileWarnings.push(w) });
   if (compileWarnings.length > 0) {
     if (args.opts.strict) {
       for (const w of compileWarnings) reportCompileError(input, w);
@@ -289,6 +295,7 @@ function cmdBuild(args) {
     outDir: args.opts.outDir,
     suffix: args.opts.suffix,
     abortEarly: !!args.opts.abortEarly,
+    onePass: args.opts.onePass === true ? true : undefined,
     check: !!args.opts.check,
     maxSize: args.opts.maxSize,
     strict: !!args.opts.strict,

package/build.d.ts

@@ -96,13 +96,26 @@ export interface ToStandaloneModuleOptions {
    */
   strictSchema?: boolean;
   /**
-   * Called when the module ships degraded: error detail was requested but the
-   * error generator declined this schema, so failures report the single
+   * Called when the module ships degraded: error detail was requested but
+   * neither error path takes this schema, so failures report the single
    * ATA9000 abort-early error while the verdict stays exact.
    */
   onWarning?: (message: string) => void;
   format?: 'cjs' | 'esm';
   abortEarly?: boolean;
+  /**
+   * Report errors with the runtime's one-pass function, the program
+   * `validate()` runs once a validator's errors have been read: one walk that
+   * checks and collects, with a verdict per subtree. On a 175 KB schema and a
+   * 15 KB document it rejects in 39 µs where the older collector took 89. Its
+   * module is 1.3 to 1.7 times the older one, gzipped, so it is not the
+   * default; `true` asks for it, `false` refuses it. Without the option the
+   * one-pass function is taken only where the older collector declines the
+   * schema, which reported one stub error before. A module built with
+   * `source` frames, or from a validator with a custom format, keeps the
+   * older collector either way.
+   */
+  onePass?: boolean;
   source?: boolean;
   sourceMap?: unknown;
   schemaFile?: string;

package/index.js

@@ -1,4 +1,5 @@
 'use strict';
+const { compileFunction } = require('./lib/compile-fn')
 
 // The full package: the validator core with the code generator registered,
 // plus the tools no Validator calls (TypeScript generation, renderers, output
@@ -878,7 +879,7 @@ function buildPreprocessCodegen(schema, options) {
   let fn = _preprocessBySource.get(src);
   if (fn === undefined) {
     try {
-      fn = new Function('d', src);
+      fn = compileFunction('d', src);
     } catch {
       fn = null;
     }
@@ -902,7 +903,7 @@ function buildParse (self, decline, extended) {
   let copy;
   try {
     // eslint-disable-next-line no-new-func
-    copy = new Function('data', 'return ' + expr);
+    copy = compileFunction('data', 'return ' + expr);
   } catch {
     return decline('code generation is not allowed here');
   }

package/lib/aot-build.js

@@ -1,4 +1,5 @@
 'use strict';
+const { env } = require('./env');
 
 const crypto = require('crypto');
 const fs = require('fs');
@@ -10,7 +11,7 @@ const { buildPositionMap } = require('./source-positions');
 function resolveSourceDefault (opts) {
   if (opts.source === true) return true;
   if (opts.source === false) return false;
-  return process.env.NODE_ENV !== 'production';
+  return env('NODE_ENV') !== 'production';
 }
 
 async function expandGlobs(globs) {
@@ -159,6 +160,7 @@ async function build(opts) {
       const src = aot.toStandaloneModule(v, {
         format,
         abortEarly: !!opts.abortEarly,
+        onePass: opts.onePass === true ? true : undefined,
         source,
         sourceMap,
         schemaFile,

package/lib/aot-impl.js

@@ -1,4 +1,5 @@
 'use strict';
+const { compileFunction } = require('./compile-fn');
 
 // All ahead-of-time (AOT) code generation lives here so the default and browser
 // entries can stay free of `fs`, `path`, and `__dirname`.
@@ -13,11 +14,12 @@
 //   bundleCompact(Validator, schemas, opts)
 //   loadBundle(Validator, mods, schemas, opts)
 
-const { compileToJSCodegenWithErrors, compileToJSCodegen, unevalContributions } = require('./js-compiler');
+const { compileToJSCodegenWithErrors, compileToJSCodegen, compileToJSCombined, unevalContributions } = require('./js-compiler');
+const VALID_RESULT = Object.freeze({ valid: true, errors: Object.freeze([]) });
 const { buildTargetedPositionMap } = require('./data-positions');
 const { schemaHash } = require('./schema-hash');
 const ATA_VERSION = require('./version');
-const { engineSource: safeRegexEngineSource } = require('./safe-regex');
+const safeRegexEngineSource = () => require('./safe-regex').engineSource();
 
 // Embedded verbatim in standalone modules so the output file has no runtime
 // dependency on ata-validator. ASCII fast-path plus surrogate-aware slow path.
@@ -175,7 +177,7 @@ function emitFormatDecls(closures, mode, declKW) {
     }
     try {
       // eslint-disable-next-line no-new-func
-      new Function('return (' + src + ')');
+      compileFunction('return (' + src + ')');
     } catch {
       throw new Error(`ata: custom format "${label}" has no standalone source (a bound function, a class method, or a native); use { formatMode: 'inject' } and register it with setFormats() at load time`);
     }
@@ -204,6 +206,143 @@ function sourceFrameDecls(frames, schemaFile) {
     `const __ataSS = [${rows.join(',')}].map((r) => Object.freeze({ file: __ataSF, line: r[0], col: r[1], text: __ataSL[r[2]] }));\n`;
 }
 
+// The one-pass function as the module's error path. The runtime's validate()
+// becomes this function once a validator's errors are read (compileToJSCombined):
+// it checks and collects in one walk, with a verdict per subtree so an
+// accepted subtree is never collected over. The module used to carry the
+// older collector instead, which walked everything and built every path: on
+// a 175 KB SchemaStore schema and a 15 KB document with two errors, 61 µs
+// against 12 for this function (a report from a config validator measured
+// 2 to 2.7x against the default validator on 84 to 234 KB schemas, and
+// guessed at the position pass, which costs 11). The program's closure
+// values are written out as declarations, the runtime helpers it shares
+// with every other program as their source, and a oneOf/anyOf branch
+// verdict compiled on its own as a module of its own inside an IIFE. Null
+// where a value has no source form (a custom format, a keyword check), and
+// the module keeps the older collector.
+const ONE_PASS_RT = new Set(['_cpLen', '_A', '_ap', '_sr', '_srX', '_ER', '_EE', '_SRT', '_FB', '_VF', '__ataSafeRe']);
+function onePassCore(validator, opts) {
+  if (validator._userFormats && Object.keys(validator._userFormats).length) return null;
+  const schemaObj = typeof validator._schemaObj === 'object' ? validator._schemaObj : null;
+  if (schemaObj === null) return null;
+  let emit;
+  try {
+    // No schema map, as for the older collector: a module carries one
+    // document. (The program could embed what a remote reference resolves to,
+    // but the wrapper that applies defaults around a module cannot see into
+    // another document, and would then answer differently from the runtime.)
+    emit = compileToJSCombined(schemaObj, VALID_RESULT, null, null, {
+      // runtimeShape: the program the runtime runs, literal for literal (the
+      // other shape of this generator is not what validate() runs and is
+      // not held to the suite); the codes and links its literals leave out
+      // are added once in _ER below.
+      moduleShape: true, emit: true, runtimeShape: true, noCounting: true,
+      resultShape: { Rejection: function (e) { this.valid = false; this.errors = e; }, empty: Object.freeze([]), sort: (e) => e, fallback: () => ABORT_SHAPE, verdict: null },
+    });
+  } catch { return null; }
+  if (!emit || typeof emit !== 'object') return null;
+  const rt = require('./combined-runtime');
+  const { DEQ_HELPER, PTR_ESC_HELPER, OWN_HELPER_CODE } = require('./js-compiler')._helperSources;
+  // The helpers' source without their comments and indentation.
+  const compact = (fn) => fn.toString().replace(/^\s*\/\/.*$/mg, '').replace(/\n\s*/g, '\n').replace(/\n+/g, '\n');
+  const decls = [];
+  const args = [];
+  const own = new Set();
+  const addOwn = (n) => { if (own.has(n)) return; own.add(n); if (n === '_h' || n === '_hall') addOwn('_hop'); if (n === '_ok') { addOwn('_PN'); addOwn('_hop'); } decls.push(OWN_HELPER_CODE[n]); };
+  let usesSafeRe = emit.usesSafeRe, usesCollapse = false;
+  for (let i = 0; i < emit.names.length; i++) {
+    const name = emit.names[i], val = emit.values[i];
+    if (name === 'R') { args.push('VALID'); continue; }
+    if (name === '_cpLen') { args.push('_cpLen'); continue; }
+    if (name === '__ataSafeRe') { usesSafeRe = true; args.push('__ataSafeRe'); continue; }
+    if (name === '_A') { decls.push('const _A={mo:true,lo:-1,on:0,os:[]};'); args.push('_A'); continue; }
+    if (name === '_ap') { decls.push(compact(rt.multiBranch) + '\nconst _ap=' + compact(rt.ap) + ';'); args.push('_ap'); continue; }
+    if (name === '_sr') { decls.push('const _sr=' + compact(rt.sr) + ';'); args.push('_sr'); continue; }
+    // The checked sort compares with the reader, which a module has no use for.
+    if (name === '_srX') { args.push('null'); continue; }
+    // Rejections: the plain shape every module reports, with the code and the
+    // documentation link the runtime would derive from the keyword.
+    if (name === '_ER') { args.push('_ER'); continue; }
+    if (name === '_EE') { args.push('Object.freeze([])'); continue; }
+    if (name === '_SRT') { args.push('function(e){return e}'); continue; }
+    if (name === '_FB') { args.push('function(){return ABORT}'); continue; }
+    if (name === '_VF') { args.push('null'); continue; }
+    if (name === '_PN') { addOwn('_PN'); args.push('_PN'); continue; }
+    if (name === '_OP' || name === '_gp') { addOwn('_PN'); args.push(name); continue; }
+    if (name === '_hop' || name === '_h' || name === '_ok' || name === '_hall') { addOwn(name); args.push(name); continue; }
+    if (name === '_pe') { decls.push(PTR_ESC_HELPER); args.push('_pe'); continue; }
+    if (name === '_deq') { decls.push(DEQ_HELPER); args.push('_deq'); continue; }
+    if (name === '_anT') { decls.push('function _anT(){return true}'); args.push('_anT'); continue; }
+    if (name === '_anF') { decls.push('function _anF(){return false}'); args.push('_anF'); continue; }
+    if (name === '_rb') { decls.push('function _rb(S,m){if(S.length!==m)S.length=m}'); args.push('_rb'); continue; }
+    if (name === '__ataCollapse' || name === '__ataMulti') { usesCollapse = true; args.push(name); continue; }
+    const expr = serializeClosure(val, name);
+    if (expr === null) return null;
+    decls.push(`const ${name}=${expr};`);
+    args.push(name);
+  }
+  if (usesCollapse) decls.unshift(require('./branch-collapse').embedSource());
+  const core = `${decls.join('\n')}\nreturn (function(${emit.names.join(',')}){${emit.source}})(${args.join(',')});`;
+  // The keywords and formats the program can report, for the code table.
+  const keywords = new Set(), formats = new Set();
+  for (const m of core.matchAll(/keyword:'([A-Za-z$]+)'/g)) keywords.add(m[1]);
+  for (const m of core.matchAll(/format:'([A-Za-z0-9-]+)'/g)) formats.add(m[1]);
+  return { core, usesSafeRe, keywords, formats };
+}
+// A closure value as source: a pattern, a name set, a frozen error literal,
+// or a verdict compiled on its own (compileToJSCodegen output, which carries
+// its source and its own closures). Null for anything else.
+function serializeClosure(val, name) {
+  if (val === null || val === undefined) return String(val);
+  if (val && val.__ataSafe) return `__ataSafeRe(${JSON.stringify(val.source)})`;
+  if (val instanceof RegExp) return `new RegExp(${JSON.stringify(val.source)}${val.flags ? ', ' + JSON.stringify(val.flags) : ''})`;
+  if (val instanceof Set) return `new Set(${JSON.stringify([...val])})`;
+  if (Array.isArray(val)) return JSON.stringify(val);
+  if (typeof val === 'function') {
+    if (typeof val._source !== 'string') return null;
+    const inner = [];
+    if (val._closures) {
+      for (const { name: n, val: v } of val._closures) {
+        if (n === '__ataSafeRe') continue;
+        const e = serializeClosure(v, n);
+        if (e === null) return null;
+        inner.push(`const ${n}=${e};`);
+      }
+    }
+    return `(function(){${inner.join('\n')}\n${val._preambleSource || ''}return function(d){${val._source}}})()`;
+  }
+  if (typeof val === 'object') {
+    // A frozen error literal of a static site: it gets its code and link
+    // here, once, since the module runs in strict mode and could not add
+    // them to a frozen object when it is reported.
+    let v = val;
+    if (typeof val.keyword === 'string' && typeof val.schemaPath === 'string' && val.code === undefined) {
+      // The same rule as enrich (lib/enrich-error.js): a property that
+      // dependentRequired asks for is `required` with code ATA7005.
+      const c = val.keyword === 'required' && val.schemaPath.endsWith('/dependentRequired') ? 'ATA7005' : require('./error-codes').codeFor(val.keyword, val.params && val.params.format);
+      if (c !== null) v = Object.assign({ code: c }, val, { docUrl: 'https://ata-validator.com/e/' + c });
+    }
+    try { const t = JSON.stringify(v); if (t === undefined) return null; return `Object.freeze(${t})`; } catch { return null; }
+  }
+  if (typeof val === 'number' || typeof val === 'boolean' || typeof val === 'string') return JSON.stringify(val);
+  return null;
+}
+// keyword -> code for the one-pass module's rejections (lib/error-codes.js),
+// holding only the keywords and formats the program can report.
+function codeTableSource(keywords, formats) {
+  const { CODES } = require('./error-codes');
+  const byKw = {}, byFmt = {};
+  // The same first-writer rule as codeFor in lib/error-codes.js.
+  for (const code of Object.keys(CODES).sort()) {
+    const c = CODES[code];
+    if (keywords.has(c.keyword) && byKw[c.keyword] === undefined) byKw[c.keyword] = code;
+    if (c.keyword === 'format' && c.format && formats.has(c.format) && byFmt[c.format] === undefined) byFmt[c.format] = code;
+  }
+  return `const _ataKw = ${JSON.stringify(byKw)};\nconst _ataFmt = ${JSON.stringify(byFmt)};\nfunction _ataCode(k, f) { if (k === 'format' && f) { const h = _ataFmt[f]; return h === undefined ? 'ATA3099' : h; } const h = _ataKw[k]; return h === undefined ? null : h; }\n`;
+}
+
+const ABORT_SHAPE = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ code: 'ATA9000', message: 'validation failed', keyword: '__abort_early__', path: '' })]) });
+
 function toStandaloneModule(validator, opts) {
   assertEmittable(validator, 'toStandaloneModule');
   validator._ensureCompiled();
@@ -219,7 +358,36 @@ function toStandaloneModule(validator, opts) {
   let errCore = '';
   let jsErrFn = null;
   const sourceFrames = new Map();
-  if (!abortEarly) {
+  // Schema-source frames are attached by the older collector only; a module
+  // built with them keeps it. Otherwise the one-pass function takes the
+  // error path when asked for (`onePass: true`) and when the older collector
+  // declines the schema, where the module reported one stub error before.
+  // Not by default elsewhere: the one-pass program carries a verdict per
+  // subtree and a counting copy per branch, and its module is 1.3 to 1.7
+  // times the older one, gzipped, which a bundle notices more than it
+  // notices a rejected document's cost. A build that validates large
+  // documents against large schemas asks for it.
+  let onePass = null;
+  const wantOnePass = opts && opts.onePass === true ? 'always' : (opts && (opts.onePass === false || opts.noOnePass)) ? 'never' : 'auto';
+  // Asked for explicitly, the one-pass function wins over schema-source
+  // frames, which `ata compile` writes by default outside production; the
+  // caller is told, since it asked for both.
+  if (wantOnePass === 'always' && source && sourceMap && schemaFile) {
+    if (opts && typeof opts.onWarning === 'function') opts.onWarning('schema-source frames are not written with the one-pass error function; the module carries the one-pass function and no frames (pass --no-source to silence this)', { kind: 'source-frames' });
+  }
+  if (!abortEarly && (wantOnePass === 'always' || !(source && sourceMap && schemaFile)) && wantOnePass !== 'never') {
+    let errLen = 1;
+    if (wantOnePass === 'auto') {
+      const probe = compileToJSCodegenWithErrors(typeof validator._schemaObj === 'object' ? validator._schemaObj : {}, null, validator._userFormats, null);
+      errLen = probe && probe._errSource ? probe._errSource.length : 0;
+    }
+    if (wantOnePass === 'always' || errLen === 0) onePass = onePassCore(validator, opts);
+  }
+  if (onePass !== null) {
+    errCore = `function _ataStamp(e) { for (let i = 0; i < e.length; i++) { const x = e[i]; if (x.code === undefined) { const c = x.keyword === 'required' && typeof x.schemaPath === 'string' && x.schemaPath.endsWith('/dependentRequired') ? 'ATA7005' : _ataCode(x.keyword, x.params && x.params.format); if (c !== null) { x.code = c; x.docUrl = 'https://ata-validator.com/e/' + c; } } else if (x.docUrl === undefined) x.docUrl = 'https://ata-validator.com/e/' + x.code; if (x.branchErrors !== undefined) _ataStamp(x.branchErrors); } }\n` +
+      `const _ER = function(e) { _ataStamp(e); this.valid = false; this.errors = e; };\n` +
+      `${codeTableSource(onePass.keywords, onePass.formats)}const _vC = (function() {\n${onePass.core}\n})();\n`;
+  } else if (!abortEarly) {
     jsErrFn = compileToJSCodegenWithErrors(
       typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
       null,
@@ -314,9 +482,11 @@ function toStandaloneModule(validator, opts) {
   const fmt = emitFormatDecls(jsFn._formatClosures, opts && opts.formatMode, 'const');
   const formatDecls = fmt.decls;
 
-  const validBody = errCore
-    ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
-    : 'return _fn(data) ? VALID : ABORT';
+  const validBody = onePass !== null
+    ? 'return _vC(data)'
+    : errCore
+      ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
+      : 'return _fn(data) ? VALID : ABORT';
 
   // parse(): validate, then hand back a copy holding only the properties the
   // schema declares. Off by default: it costs bytes in every emitted module,
@@ -417,7 +587,7 @@ function validateJSON(text) {
 // Re-run the build after upgrading ata: the version above is what wrote this.
 ${degradedNote}'use strict';
 ${_CP_LEN_SOURCE}
-${safeRePrelude(jsFn, jsErrFn)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+${safeRePrelude(jsFn, jsErrFn, onePass !== null && onePass.usesSafeRe ? { _usesSafeRe: true } : null)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
 const ABORT = Object.freeze({
   valid: false,
   errors: Object.freeze([Object.freeze({

package/lib/combined-runtime.js

@@ -139,7 +139,7 @@ function _anF () { return false }
 function _rb (S, m) { if (S.length !== m) S.length = m }
 
 module.exports = {
-  apState, ap, sr, srX,
+  apState, ap, sr, srX, multiBranch,
   _PN, _OP, _gp, _hop, _h, _ok, _hall, _pe, _anT, _anF, _rb,
 }
 // Loaded when a program first asks for them: a schema without const, enum,

package/lib/compile-fn.js

@@ -0,0 +1,16 @@
+'use strict'
+
+// The one place the package turns generated source into a function. Every
+// generator (the verdict, error and one-pass generators, the JSON text
+// scanner, the standalone-module probes) calls this instead of `new Function`
+// itself, so a reader auditing what the package evaluates has one file to
+// read, and a supply-chain scanner reports one site rather than seven files.
+// `Function` is looked up at the call, not captured here, so an environment
+// that blocks dynamic code (a Content Security Policy, a test that replaces
+// the global) blocks this too, and the caller falls back to the interpreted
+// engine as before.
+function compileFunction (...args) {
+  return new Function(...args)
+}
+
+module.exports = { compileFunction }

package/lib/enrich-error.js

@@ -254,9 +254,17 @@ function enrich (rawErr, opts) {
   // that answered wrote, the generator's internal ordering key included.
   if (rawErr.branchErrors) out.branchErrors = rawErr.branchErrors.map((b) => enrich(b, data !== undefined ? { data } : null));
 
+  // The frames come from the position map, which is a walk of the document.
+  // Given lazily (validateJSON's rejections), the walk waits for the first
+  // read of any error's `dataFrame` or `anchor`: a caller that reads the
+  // messages and paths never pays for it, and one that reads every frame
+  // pays once, as before. Given eagerly, the fields are set as before.
+  const named = (rawErr.params && (rawErr.params.additionalProperty || rawErr.params.unevaluatedProperty)) || null;
   if (positions && positions[path]) {
     const p = positions[path];
     out.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
+  } else if (!positions && opts && opts.lazyPositions) {
+    defineLazyFrames(out, path, named, opts.lazyPositions);
   }
 
   // Attach schema source frame when the validator was constructed with a
@@ -286,7 +294,6 @@ function enrich (rawErr, opts) {
   // adds the key span so a caret can sit on the property that is wrong rather
   // than on the object containing it.
   if (opts && opts.positions) {
-    const named = (rawErr.params && (rawErr.params.additionalProperty || rawErr.params.unevaluatedProperty)) || null;
     const own = opts.positions[path];
     const child = named ? opts.positions[(path === '' ? '' : path) + '/' + named] : null;
     const src = child || own;
@@ -303,4 +310,42 @@ function enrich (rawErr, opts) {
   return out;
 }
 
+// `dataFrame` and `anchor` as accessors that resolve the position map on the
+// first read of either, on any error of the list (the map is shared through
+// `lazy`), and then become plain data properties, or go away when the map has
+// no entry for the error, which is the shape the eager path gives. Both are
+// enumerable, so JSON.stringify and a deep comparison read them as values;
+// a write replaces the accessor the way an assignment to a plain field would.
+function defineLazyFrames (out, path, named, lazy) {
+  let done = false;
+  let frames = null;
+  const resolve = () => {
+    if (done) return frames;
+    done = true;
+    const positions = lazy();
+    const own = positions ? positions[path] : null;
+    const dataFrame = own ? { byteOffset: own.byteOffset, length: own.length, line: own.line, col: own.col, text: own.text } : undefined;
+    const child = positions && named ? positions[(path === '' ? '' : path) + '/' + named] : null;
+    const src = child || own;
+    let anchor;
+    if (src) {
+      anchor = { line: src.line, col: src.col, length: src.length };
+      if (src.keyOffset !== undefined) {
+        anchor.keyLine = src.keyLine;
+        anchor.keyCol = src.keyCol;
+        anchor.keyLength = src.keyLength;
+      }
+    }
+    frames = { dataFrame, anchor };
+    if (dataFrame !== undefined) Object.defineProperty(out, 'dataFrame', { value: dataFrame, enumerable: true, configurable: true, writable: true });
+    else delete out.dataFrame;
+    if (anchor !== undefined) Object.defineProperty(out, 'anchor', { value: anchor, enumerable: true, configurable: true, writable: true });
+    else delete out.anchor;
+    return frames;
+  };
+  const settable = (name) => (v) => Object.defineProperty(out, name, { value: v, enumerable: true, configurable: true, writable: true });
+  Object.defineProperty(out, 'dataFrame', { get () { return resolve().dataFrame; }, set: settable('dataFrame'), enumerable: true, configurable: true });
+  Object.defineProperty(out, 'anchor', { get () { return resolve().anchor; }, set: settable('anchor'), enumerable: true, configurable: true });
+}
+
 module.exports = { enrich, reprValue, expectedFor, detailFor, rankFor, MISSING, DOC_BASE };

package/lib/env.js

@@ -0,0 +1,13 @@
+'use strict'
+
+// The one place the package reads an environment variable. Everything the
+// package honours is listed here: the diagnostic switches the generators
+// read, the engine override, and NODE_ENV for the CLI's source-map default.
+// Read at the call, not at load, so a test or a host that sets one after
+// requiring the package is still heard; absent `process` (a browser) every
+// read is undefined.
+function env (name) {
+  return typeof process !== 'undefined' && process.env ? process.env[name] : undefined
+}
+
+module.exports = { env }

package/lib/interpreter.js

@@ -10,7 +10,9 @@ const { collapseBranches } = require('./branch-collapse');
 // looked-up format, a flag per keyword group) so the walk itself reads no
 // schema properties; codegen and the native engine remain the fast paths.
 
-const { compileSafe } = require('./safe-regex');
+// Read on the first pattern (see lib/js-compiler.js for why).
+let _safeRe = null;
+const compileSafe = (src) => (_safeRe || (_safeRe = require('./safe-regex'))).compileSafe(src);
 
 const SCHEMA_KEYWORDS = {
   single: ['additionalProperties', 'contains', 'propertyNames', 'if', 'then', 'else', 'not', 'items', 'unevaluatedItems', 'unevaluatedProperties'],