ata-validator 1.56.0 → 1.57.0

package/README.md

@@ -584,8 +584,11 @@ CLI options:
 | `-f, --format <fmt>` | `esm` | `esm` or `cjs` |
 | `--name <TypeName>` | from filename | Root type name in the `.d.ts` |
 | `--abort-early` | off | Generate the stub-error variant, about a third of the source |
+| `--order` | off | Hand errors out in the runtime's order (schema declaration order), not the order the collector found them in |
 | `--no-types` | off | Skip the `.d.mts` / `.d.cts` output |
 
+A module answers `validate()` as the runtime does, with two differences a caller reading the module directly should know. The runtime fills in `default` values before it checks (`useDefaults` is on unless turned off), and the module does not: where the schema declares a default the module exports `applyDefaults(data)`, the runtime's own pass, to call first. And the module returns its errors in the order its collector found them, which can put a field's `format` error before its `pattern` error, or behind a `$ref` a definition's `required` before its `properties`; `--order` sorts them as the runtime does. It is off by default because it costs bytes: 225 more gzipped for an eight-field form, about 1 KB for a small schema with references, whose key skeleton the module then carries, and 12.6% over 267 SchemaStore schemas. With both, a module matched the runtime's verdict, filled data and error list, in order, on every case of the official suites it compiles (1,500 groups, 5,324 cases across six dialects) and on 1,952 of SchemaStore's sample documents. `fromCompiled()` and modules that share the error runtime sort already and need neither.
+
 For a project with many schemas, `ata build <glob>` compiles them all in one command:
 
 ```bash

package/bin/ata.js

@@ -30,6 +30,9 @@ Compile options:
   --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
+  --order                 Hand errors out in the runtime's order (schema declaration
+                          order) rather than the order they were found in; adds a sort,
+                          and for a schema with $ref its key skeleton
   --source                Embed schema source map (default in development)
   --no-source             Omit source map (default in production, NODE_ENV=production)
 
@@ -45,6 +48,10 @@ Build options:
   --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
+  --order                 Hand errors out in the runtime's order (schema declaration
+                          order) rather than the order they were found in; adds a sort,
+                          and for a schema with $ref its key skeleton (modules that share
+                          the error runtime are in that order already)
   --errors <mode>         Where error detail comes from: auto | inline | shared. auto
                           (default) has modules share one error runtime file when that
                           makes the output smaller; production builds only (--no-source)
@@ -103,6 +110,7 @@ function parseArgs(argv) {
     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 === '--order') { out.opts.order = true; continue; }
     if (a === '--errors') { out.opts.errors = argv[++i]; continue; }
     if (a === '--mode') { out.opts.mode = argv[++i]; continue; }
     if (a === '--base-uri') { out.opts.baseUri = argv[++i]; continue; }
@@ -250,7 +258,7 @@ function cmdCompile(args) {
   }
   const schemaFile = path.relative(process.cwd(), input) || input;
   const compileWarnings = [];
-  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onePass: args.opts.onePass === true ? true : undefined, onWarning: (w) => compileWarnings.push(w) });
+  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile, onePass: args.opts.onePass === true ? true : undefined, order: args.opts.order === true ? true : undefined, onWarning: (w) => compileWarnings.push(w) });
   if (compileWarnings.length > 0) {
     if (args.opts.strict) {
       for (const w of compileWarnings) reportCompileError(input, w);
@@ -277,7 +285,7 @@ function cmdCompile(args) {
     const typeName = args.opts.name || path.basename(input, path.extname(input))
       .replace(/[^A-Za-z0-9_]/g, '_')
       .replace(/^([a-z])/, (m) => m.toUpperCase()) || 'Data';
-    const dts = toTypeScript(schema, { name: typeName });
+    const dts = toTypeScript(schema, { name: typeName, applyDefaults: /\nfunction applyDefaults\(/.test(src) });
     const ext = path.extname(output);
     const dtsExt = ext === '.mjs' ? '.d.mts'
       : ext === '.cjs' ? '.d.cts'
@@ -308,6 +316,7 @@ function cmdBuild(args) {
     suffix: args.opts.suffix,
     abortEarly: !!args.opts.abortEarly,
     onePass: args.opts.onePass === true ? true : undefined,
+    order: args.opts.order === true ? true : undefined,
     errors: args.opts.errors,
     mode: args.opts.mode,
     baseUri: args.opts.baseUri,

package/build.d.ts

@@ -116,6 +116,12 @@ export interface ToStandaloneModuleOptions {
    * older collector either way.
    */
   onePass?: boolean;
+  /**
+   * Hand errors out in the runtime's order, schema declaration order, rather
+   * than the order the collector found them in (`ata compile --order`). Adds a
+   * sort, and for a schema with `$ref` its key skeleton; off by default.
+   */
+  order?: boolean;
   source?: boolean;
   sourceMap?: unknown;
   schemaFile?: string;
@@ -190,7 +196,7 @@ export function compiledSchemaFor(schema: unknown): object;
  * {@link compiledEligible} declines, one the emitter cannot compile, and one
  * whose detailed errors the generator cannot produce.
  */
-export function compiledModuleFor(schema: unknown, opts?: { format?: 'esm' | 'cjs'; errorRuntime?: string }): string | null;
+export function compiledModuleFor(schema: unknown, opts?: { format?: 'esm' | 'cjs'; errorRuntime?: string; order?: boolean }): string | null;
 
 /**
  * The Validator options `fromCompiled()` reproduces, so a plugin can tell

package/lib/aot-build.js

@@ -288,6 +288,7 @@ async function build(opts) {
       format,
       abortEarly: !!opts.abortEarly,
       onePass: opts.onePass === true ? true : undefined,
+      order: opts.order === true ? true : undefined,
       source,
       sourceMap,
       schemaFile,
@@ -465,7 +466,7 @@ async function build(opts) {
         const typeName = stem
           .replace(/[^A-Za-z0-9_]/g, '_')
           .replace(/^([a-z])/, (m) => m.toUpperCase()) || 'Data';
-        const dts = toTypeScript(e.schema, { name: typeName });
+        const dts = toTypeScript(e.schema, { name: typeName, applyDefaults: /\nfunction applyDefaults\(/.test(src) });
         const ext = path.extname(output);
         const dtsExt = ext === '.mjs' ? '.d.mts'
           : ext === '.cjs' ? '.d.cts'
@@ -646,6 +647,10 @@ function compiledModuleFor(schema, opts) {
   try {
     src = aot.toStandaloneModule(validatorFor(schema), {
       format: (opts && opts.format) || 'esm',
+      // Errors in the runtime's order, for a reader that does not sort them
+      // itself (a form resolver); fromCompiled sorts, so a plugin putting
+      // that wrapper around the module leaves it off.
+      order: !!(opts && opts.order === true),
       onWarning: (msg, info) => { if (info && info.kind === 'error-detail') degraded = true; },
     });
   } catch {

package/lib/aot-impl.js

@@ -346,6 +346,20 @@ function codeTableSource(keywords, formats) {
 
 const ABORT_SHAPE = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ code: 'ATA9000', message: 'validation failed', keyword: '__abort_early__', path: '' })]) });
 
+// The runtime's defaults pass (preprocessSource in lib/codegen-engine.js),
+// over the schema the runtime builds it from, as a function the module
+// exports as applyDefaults. Not called by validate(): the runtime fills
+// defaults before checking because useDefaults is on unless turned off, and
+// a module cannot see that option, so the caller who wants the runtime's
+// answer calls applyDefaults(data) first. Empty where the schema has no
+// default, or where the pass declines it (a schema object containing itself).
+function defaultsDecl(validator) {
+  const { resolveSchemaForPreprocess } = require('./validator-core')._internals;
+  let src = null;
+  try { src = require('./codegen-engine').preprocessSource(resolveSchemaForPreprocess(validator._schemaObj, validator._schemaMap), { useDefaults: true }); } catch {}
+  return src === null ? '' : `function applyDefaults(d) {\n${src}\n}\n`;
+}
+
 function toStandaloneModule(validator, opts) {
   assertEmittable(validator, 'toStandaloneModule');
   validator._ensureCompiled();
@@ -374,6 +388,7 @@ function toStandaloneModule(validator, opts) {
   // notices a rejected document's cost. A build that validates large
   // documents against large schemas asks for it.
   let onePass = null;
+  let ordered = false;
   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
@@ -394,14 +409,20 @@ function toStandaloneModule(validator, opts) {
       `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) {
-    // A module returns the collector's errors as they are and never sorts
-    // them, so the ordinal the runtime sorts by (`_o`) has no reader there;
-    // it leaked into every error object a module reported.
+    // With `order: true` the module hands its errors out in the runtime's
+    // order (lib/aot-order.js); without it, in the collector's, as it always
+    // did, since the sort costs every module bytes (12.6% over SchemaStore's,
+    // gzipped, most of it the key skeleton of schemas with references) and a
+    // reader that sorts (fromCompiled) does not need it. Where the module
+    // sorts by each error site's ordinal, the collector writes it (`_o`).
+    const schemaForErrors = typeof validator._schemaObj === 'object' ? validator._schemaObj : {};
+    ordered = !!(opts && opts.order === true);
+    const noOrdinal = !ordered || !require(AOT_ORDER_MODULE).wantsOrdinals(schemaForErrors);
     jsErrFn = compileToJSCodegenWithErrors(
-      typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
+      schemaForErrors,
       null,
       validator._userFormats,
-      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames, noOrdinal: true } : { noOrdinal: true },
+      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile, frames: sourceFrames, noOrdinal } : { noOrdinal },
     );
     const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
     if (errSrc && jsErrFn._errFactory) {
@@ -537,12 +558,22 @@ function toStandaloneModule(validator, opts) {
     // module that only accepts costs no more to load than its verdict.
     compactCore = `let _ataErrs = null;\nfunction _ataErrors(d) { if (_ataErrs === null) _ataErrs = _ataCreateErrors(JSON.parse(${text})${rtOpts ? ', { ' + rtOpts + ' }' : ''}); return _ataErrs(d); }\n`;
   }
+  const orderDecl = errCore && ordered && errorRuntime === null && onePass === null
+    ? require(AOT_ORDER_MODULE).orderDecl(validator._schemaObj)
+    : '';
+  // Asked for and not given: stub errors, the one-pass function, or no error
+  // code generated. The caller is told rather than handed the collector's
+  // order as if it were the runtime's. Errors from the shared runtime come in
+  // the runtime's order already (errorsOf in lib/error-runtime-entry.js).
+  if (opts && opts.order === true && orderDecl === '' && errorRuntime === null && typeof opts.onWarning === 'function') {
+    opts.onWarning('errors are not in the runtime order: order applies to modules with generated error code, not to stub errors or the one-pass function', { kind: 'order' });
+  }
   const validBody = errorRuntime !== null
     ? 'if (_fn(data)) return VALID; const e = _ataErrors(data); return e === null ? ABORT : { valid: false, errors: e }'
     : onePass !== null
     ? 'return _vC(data)'
     : errCore
-      ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
+      ? (orderDecl !== '' ? 'return _fn(data) ? VALID : { valid: false, errors: _ataOrder(errFn(data, true).errors) }' : '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
@@ -625,6 +656,8 @@ function validateJSON(text) {
   const hashDecl = `const schemaHash = ${JSON.stringify(hashSrc)};\nconst ataVersion = ${JSON.stringify(ATA_VERSION)};\n`;
 
   let names = fmt.exportsSetFormats ? baseNames + ', setFormats' : baseNames;
+  const fillDecl = defaultsDecl(validator);
+  if (fillDecl) names += ', applyDefaults';
   names += ', schemaHash, ataVersion';
   if (positionsCore) names += ', validateJSON';
   const parseAlias = cloneExpr ? ', _ataParse as parse' : '';
@@ -657,9 +690,9 @@ const ABORT = Object.freeze({
 ${closureDecls}${sharedBlock}${preambleDecls}${formatDecls}const _fn = function(d) {
   ${src}
 };
-${errCore}${compactCore}function isValid(data) { return _fn(data); }
+${errCore}${orderDecl}${compactCore}function isValid(data) { return _fn(data); }
 function validate(data) { ${validBody}; }
-${parseCore}${positionsCore}${hashDecl}${exports}`;
+${parseCore}${positionsCore}${fillDecl}${hashDecl}${exports}`;
 }
 
 // Why a validator cannot be written as a compact module, or null when it can.
@@ -673,6 +706,8 @@ ${parseCore}${positionsCore}${hashDecl}${exports}`;
 // along: 1.49.0 bundled for such runtimes, and the generator must not break
 // that.
 const ERROR_RUNTIME_MODULE = './error-runtime';
+// Reads the library's files too, at build time (see lib/aot-order.js).
+const AOT_ORDER_MODULE = './aot-order';
 function loadErrorRuntime() { return require(ERROR_RUNTIME_MODULE); }
 
 // The schema hash a module stamps, once per validator: a plugin writes both
@@ -806,9 +841,11 @@ function toSchemaModule(validator, opts) {
     ? `import { createValidator as _ataCreateValidator } from ${spec};\n`
     : `const { createValidator: _ataCreateValidator } = require(${spec});\n`)
     + (regSpec === null ? '' : format === 'esm' ? `import _ataRegistry from ${regSpec};\n` : `const _ataRegistry = require(${regSpec});\n`);
+  const fillDecl = defaultsDecl(validator);
+  const expNames = 'validate, isValid' + (fillDecl ? ', applyDefaults' : '') + ', schemaHash, ataVersion';
   const exp = format === 'esm'
-    ? 'export { validate, isValid, schemaHash, ataVersion };\nexport default { validate, isValid, schemaHash, ataVersion };\n'
-    : 'module.exports = { validate, isValid, schemaHash, ataVersion };\nmodule.exports.default = module.exports;\n';
+    ? `export { ${expNames} };\nexport default { ${expNames} };\n`
+    : `module.exports = { ${expNames} };\nmodule.exports.default = module.exports;\n`;
   return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.
 // Schema module: the schema; the verdict and the errors come from the runtime it imports.
 // Re-run the build after upgrading ata: the version above is what wrote this.
@@ -819,7 +856,7 @@ let _ataV = null;
 function _ataGet() { return _ataV !== null ? _ataV : (_ataV = _ataCreateValidator(${ownId !== null ? 'null' : 'JSON.parse(' + text + ')'}${rtOpts ? ', { ' + rtOpts + ' }' : ''})); }
 function isValid(data) { return _ataGet().isValid(data); }
 function validate(data) { const v = _ataGet(); if (v.isValid(data)) return VALID; const e = v.errors(data); return e === null ? ABORT : { valid: false, errors: e }; }
-const schemaHash = ${JSON.stringify(hashSrc)};
+${fillDecl}const schemaHash = ${JSON.stringify(hashSrc)};
 const ataVersion = ${JSON.stringify(ATA_VERSION)};
 ${exp}`;
 }

package/lib/aot-order.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// How a module written ahead of time hands out its errors in the order the
+// runtime does: schema declaration order (sortErrorsBySchemaOrder in
+// lib/rejections.js). A module used to return them in the order its collector
+// found them, which put `additionalProperties` before `properties` and
+// `format` before `pattern`, and behind a reference a definition's `required`
+// before its `properties`; the first error of a field could differ from the
+// runtime's.
+//
+// The runtime orders by the ordinal of each error's schema path and breaks
+// ties by the path's rank, and comparing ranks alone gives the same order
+// (lib/schema-order.js). Two ways to know them in a module:
+//
+// - Without a reference, the collector writes each error site's ordinal into
+//   the error (`_o`, noteOrdinal in lib/js-compiler-errors.js) and no two
+//   paths share one, so a stable sort by it is the runtime's order.
+// - With one, an error behind a shared definition has its path built when the
+//   definition runs and carries no ordinal, and paths through a `$ref` share
+//   the ordinal of the `$ref`. The module ranks each path itself with
+//   lib/schema-order.js's own functions, embedded as their text so module and
+//   runtime rank with one source, over the schema's skeleton: its schema
+//   objects with every key, subschemas kept, every other value 0, which ranks
+//   every path an error can name exactly as the schema does.
+//
+// Node only, at build time: it reads the library's own files.
+const fs = require('fs');
+const path = require('path');
+
+const _files = new Map();
+function take(file, names) {
+  let src = _files.get(file);
+  if (src === undefined) { src = fs.readFileSync(path.join(__dirname, file), 'utf8'); _files.set(file, src); }
+  return names.map((n) => {
+    const m = new RegExp('^function ' + n + ' ?\\([^]*?^}$', 'm').exec(src);
+    if (m === null) throw new Error('aot-order: lib/' + file + ' has no top-level function ' + n);
+    return m[0].replace(/^\s*\/\/.*\n/gm, '');
+  }).join('\n');
+}
+
+// Keywords whose value is a schema, an array of schemas, or an object of them:
+// the only places an error's schema path goes below a schema object.
+const ONE = new Set(['additionalProperties', 'additionalItems', 'items', 'contains', 'propertyNames', 'if', 'then', 'else', 'not', 'unevaluatedItems', 'unevaluatedProperties']);
+const LIST = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems', 'items']);
+const MAP = new Set(['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas', 'dependencies']);
+
+function skeleton(node) {
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) return 0;
+  const out = {};
+  for (const k of Object.keys(node)) {
+    const v = node[k];
+    let s = 0;
+    if (k === '$ref' && typeof v === 'string') s = v;
+    else if (Array.isArray(v) && LIST.has(k)) s = v.map(skeleton);
+    else if (MAP.has(k) && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      s = {};
+      for (const name of Object.keys(v)) Object.defineProperty(s, name, { value: Array.isArray(v[name]) ? 0 : skeleton(v[name]), enumerable: true, writable: true, configurable: true });
+    } else if (ONE.has(k) && v !== null && typeof v === 'object') s = skeleton(v);
+    Object.defineProperty(out, k, { value: s, enumerable: true, writable: true, configurable: true });
+  }
+  return out;
+}
+
+function hasReference(schemaObj) {
+  const text = JSON.stringify(schemaObj);
+  return text.includes('"$ref"') || text.includes('"$dynamicRef"') || text.includes('"$recursiveRef"');
+}
+
+// Whether the collector should write ordinals into the errors: only where the
+// module sorts by them.
+function wantsOrdinals(schemaObj) { return !hasReference(schemaObj); }
+
+// The sort, by a key per error, stable as the runtime's insertion sort is, and
+// the copies the caller gets, without the ordinal; a collapsed error's branch
+// errors are ordered and copied the same way.
+const ORDER = (key, cmp) => `function _ataOrder(list) {
+  const n = list.length, out = new Array(n), keys = new Array(n);
+  let prev = ${key === '_o' ? '0' : 'null'};
+  for (let i = 0; i < n; i++) {
+    const src = list[i];
+    const { _o, ...e } = src;
+    if (Array.isArray(e.branchErrors)) e.branchErrors = _ataOrder(e.branchErrors);
+    let k = ${key === '_o' ? "typeof src._o === 'number' ? src._o : prev" : '_ataRank(src.schemaPath)'};
+    prev = k;
+    let j = i - 1;
+    while (j >= 0 && ${cmp}) { keys[j + 1] = keys[j]; out[j + 1] = out[j]; j--; }
+    keys[j + 1] = k;
+    out[j + 1] = e;
+  }
+  return out;
+}
+`;
+
+// Source declaring `_ataOrder(errors)`: the errors sorted as the runtime sorts
+// them, without their ordinals.
+function orderDecl(schemaObj) {
+  if (!hasReference(schemaObj)) return ORDER('_o', 'keys[j] > k');
+  const sk = JSON.stringify(skeleton(schemaObj));
+  return `const _ataSkeleton = JSON.parse(${JSON.stringify(sk).replace(/</g, '\\u003c')});
+const _keyIndexCache = new WeakMap();
+const _rankCache = new WeakMap();
+const _documents = new WeakMap();
+const CONFLICT = null;
+${take('schema-order.js', ['keyIndex', 'unescapePointerSegment', 'rankFor', 'computeRank', 'localTarget'])}
+function _ataRank(p) { return rankFor(_ataSkeleton, p); }
+function _ataAfter(a, b) {
+  if (a === null || b === null) return false;
+  const m = Math.min(a.length, b.length);
+  for (let i = 0; i < m; i++) if (a[i] !== b[i]) return a[i] > b[i];
+  return a.length > b.length;
+}
+${ORDER('rank', '_ataAfter(keys[j], k)')}`;
+}
+
+module.exports = { orderDecl, wantsOrdinals };

package/lib/codegen-engine.js

@@ -857,8 +857,10 @@ function emitDefaults(node, ov, lines, st) {
   st.seen.delete(node);
 }
 
-// Generate a fast preprocess function via codegen instead of closure arrays
-function buildPreprocessCodegen(schema, options) {
+// The source of the preprocess pass, or null when there is nothing to do or
+// the closure passes must take the schema. A module written ahead of time
+// embeds it as applyDefaults (lib/aot-impl.js), so it runs the runtime's code.
+function preprocessSource(schema, options) {
   if (typeof schema !== 'object' || schema === null || !schema.properties) return null;
   const lines = [];
 
@@ -889,13 +891,19 @@ function buildPreprocessCodegen(schema, options) {
   // Data may legitimately be null or a non-object (e.g. a `['object','null']`
   // schema), so the per-property mutations must not run on it.
   lines.unshift(`if(d===null||typeof d!=='object')return`);
+  return lines.join('\n');
+}
+
+// Generate a fast preprocess function via codegen instead of closure arrays
+function buildPreprocessCodegen(schema, options) {
+  const src = preprocessSource(schema, options);
+  if (src === null) return null;
   // The pass depends on property names, types, defaults and which objects
   // are closed, not on the constraints the verdict checks, so routes that
   // take the same shape with different limits (a page/limit querystring, an
   // id param) emit the same source. Compiling it is most of what building the
   // pass costs, so the function is kept by its source and compiled once. It
   // holds no state: it rewrites the object it is given and nothing else.
-  const src = lines.join('\n');
   let fn = _preprocessBySource.get(src);
   if (fn === undefined) {
     try {
@@ -1020,6 +1028,7 @@ module.exports = {
   compileVerdict: installCodegenPaths.compileVerdict,
   installScanner: installCodegenPaths.installScanner,
   buildPreprocess: buildPreprocessCodegen,
+  preprocessSource,
   buildParse,
   aot: () => require('./aot.js'),
 };

package/lib/interpreter-core.js

@@ -13,6 +13,34 @@
 let _safeRe = null;
 const compileSafe = (src) => (_safeRe || (_safeRe = require('./safe-regex'))).compileSafe(src);
 
+// A pattern with no group or alternation, few bounded choices in all, and at
+// most one unbounded repeat, on one character or class and only when the
+// pattern starts with `^`, runs in linear time on a backtracking RegExp, so it
+// takes the platform's: built in about a microsecond where the linear engine's
+// automaton took 40 to 100, and faster to test. Every pattern accepted here
+// also gets a RegExp from the code generator (lib/regex-linear.js), so both
+// engines answer with the same matcher; tests/test_regex_plain_linear.js holds
+// that and the answers.
+const PLAIN_ATOM = /(?:\\[dDwWsS\\/.^$|?*+()[\]{}-]|\[\^?(?:[^\\\][^\ud800-\udfff]|\\[dws\\/.^$[\]-])(?:[^\\\][\ud800-\udfff]|\\[dws\\/.^$[\]-])*\]|[^\\[\](){}|*+?^$\ud800-\udfff])(\?|[*+]|\{(\d{1,3})(?:,(\d{1,3}))?\})?/y;
+function plainLinear(src) {
+  const n = src.length, anchored = src[0] === '^';
+  if (n > 256) return false;
+  let i = anchored ? 1 : 0, choices = 1, loops = 0;
+  while (i < n) {
+    if (src[i] === '$' && i === n - 1) return true;
+    PLAIN_ATOM.lastIndex = i;
+    const m = PLAIN_ATOM.exec(src);
+    if (m === null) return false;
+    i = PLAIN_ATOM.lastIndex;
+    const q = m[1];
+    if (q === '?') choices *= 2;
+    else if (q === '*' || q === '+') { if (!anchored || ++loops > 1) return false; }
+    else if (q !== undefined) { const lo = +m[2], hi = m[3] === undefined ? lo : +m[3]; if (hi < lo) return false; choices *= hi - lo + 1; }
+    if (choices > 64) return false;
+  }
+  return true;
+}
+
 const SCHEMA_KEYWORDS = {
   single: ['additionalProperties', 'contains', 'propertyNames', 'if', 'then', 'else', 'not', 'items', 'unevaluatedItems', 'unevaluatedProperties'],
   maps: ['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas'],
@@ -912,6 +940,8 @@ class Interpreter {
         // Unicode property escapes need a real RegExp in unicode mode; the
         // linear engine does not understand them.
         try { re = new RegExp(src, 'u'); } catch { re = new RegExp(src); }
+      } else if (plainLinear(src)) {
+        re = new RegExp(src);
       } else {
         try {
           re = compileSafe(src);
@@ -1534,6 +1564,7 @@ function createInterpreter(schema, options) {
 }
 
 module.exports = { createInterpreter };
+Object.defineProperty(module.exports, '_plainLinear', { value: plainLinear, enumerable: false });
 Object.defineProperty(module.exports, '_setPlanCompiler', { value: setPlanCompiler, enumerable: false });
 Object.defineProperty(module.exports, '_setCompat', { value: setCompat, enumerable: false });
 // The resolver, for the code generator: it resolves references at compile

package/lib/tiering.js

@@ -111,6 +111,7 @@ function createTiering (load) {
   // A call counter for one validator: the TIER_CALLS-th call asks for the
   // generator and has the validator rebuilt once it is in.
   function counter (v) {
+    if (warm === 1) warm = 2;
     let calls = 0, start = 0;
     return () => {
       if (++calls < TIER_CALLS) { if (calls === 1) start = now(); return; }
@@ -123,8 +124,94 @@ function createTiering (load) {
     };
   }
 
+  // A page's first check pays for V8 compiling the engine and the error
+  // builders (3.1 ms of an eight-field form's first submit, 0.4 ms once any
+  // other schema had been checked) and for building its own schema's engine.
+  // Both move to when the page is idle, or 200 ms later where there is no
+  // requestIdleCallback (Safari, workers): one check of a small schema, once
+  // per page and dropped when a validator compiles first, then the engine for
+  // each validator built since, at most eight, kept aside. A validator adopts
+  // it at its first check only if every input is still the same, its schema
+  // text included, so addSchema() or a change to the schema in between is
+  // honored as before.
+  // warm: 0 none, 1 scheduled, 2 done or dropped.
+  let warm = 0, scheduled = false, warming = false, adopted = 0;
+  const pending = [];
+  const shadows = new WeakMap();
+  const idle = (f) => {
+    if (typeof requestIdleCallback === 'function') return requestIdleCallback(f, { timeout: 2000 });
+    const t = setTimeout(f, 200);
+    if (t && typeof t.unref === 'function') t.unref();
+  };
+  function built (v) {
+    if (warming) return;
+    if (warm === 0) warm = 1;
+    if (pending.length < 8 && typeof WeakRef === 'function') pending.push(new WeakRef(v));
+    if (!scheduled) { scheduled = true; idle(run); }
+  }
+  function run (deadline) {
+    scheduled = false;
+    if (warm === 1) {
+      warm = 2;
+      warming = true;
+      try { warmUp(); } catch { /* a warm-up never reaches the page */ }
+      warming = false;
+    }
+    while (pending.length > 0) {
+      if (deadline !== undefined && deadline.timeRemaining() < 1) { scheduled = true; idle(run); return; }
+      const v = pending.shift().deref();
+      if (v === undefined || core._codegenRegistered()) continue;
+      let s = null;
+      try { s = prebuild(v); } catch { /* built as usual at the first check */ }
+      if (s !== null) shadows.set(v, s);
+    }
+  }
+
+  // One check of a small schema, rejected and accepted, compiles the engine's
+  // code for the page: the plan builder, the walk, the regex and format
+  // checks, the error builders.
+  function warmUp () {
+    const v = new core.Validator({
+      type: 'object',
+      properties: {
+        a: { type: 'string', minLength: 2, maxLength: 9, pattern: '^[a-z]+$', format: 'email' },
+        b: { type: 'integer', minimum: 1, maximum: 9 },
+        c: { type: 'array', items: { type: 'string' }, maxItems: 3 },
+        d: { const: true },
+        e: { type: 'object', properties: { f: { type: 'string' } }, required: ['f'] },
+      },
+      required: ['a', 'b'],
+    });
+    void v.validate({ a: '1', b: 0, c: [1], d: false, e: {} }).errors.length;
+    v.validate({ a: 'ab@c.de', b: 2, c: ['x'], d: true, e: { f: 'x' } });
+  }
+
+  // The engine a validator will build at its first check, built now from the
+  // same inputs and kept aside; null where something besides the schema object
+  // decides the build: custom keywords (their compile functions are the
+  // caller's code), registered schemas, a schema that needs rewriting.
+  function prebuild (v) {
+    if (v._initialized || v._keywords !== null || v._schemaMap.size !== 0) return null;
+    const raw = v._rawSchema;
+    const { _interpArgs, _normalizeCallerSchemaUncached } = core._internals;
+    if (raw === null || typeof raw !== 'object' || _normalizeCallerSchemaUncached(raw) !== raw) return null;
+    const args = _interpArgs(v, raw);
+    return { schema: raw, text: JSON.stringify(raw), args, interp: require('./interpreter').createInterpreter(raw, args) };
+  }
+
+  function adopt (v, schemaObj, args) {
+    const s = shadows.get(v);
+    if (s === undefined) return null;
+    shadows.delete(v);
+    if (s.schema !== schemaObj || s.text !== v._schemaStr) return null;
+    for (const k of Object.keys(args)) if (args[k] !== s.args[k]) return null;
+    adopted++;
+    return s.interp;
+  }
+
   // Count the interpreted engine's calls for this validator.
   function watch (v, interp) {
+    if (warm === 1) warm = 2;
     const v0 = interp.validate, i0 = interp.isValid;
     const tick = counter(v);
     interp.validate = (d) => { tick(); return v0.call(interp, d); };
@@ -143,7 +230,7 @@ function createTiering (load) {
     while (draining !== null) await draining;
   }
 
-  return { watch, counter, aotStub, loadCodegen, tierUp, settled, TIER_CALLS, WINDOW_MS, get loading () { return loading; } };
+  return { watch, counter, built, aotStub, loadCodegen, settled, TIER_CALLS, WINDOW_MS, get loading () { return loading; }, get warm () { return warm; }, get adopted () { return adopted; }, adopt };
 }
 
 module.exports = { createTiering, TIER_CALLS };

package/lib/ts-gen.js

@@ -197,6 +197,8 @@ function renderJsDoc(schema, indent) {
 function toTypeScript(schema, opts) {
   const options = opts || {};
   const rootName = toTypeName(options.name || 'Data');
+  // Whether the module beside these types exports applyDefaults (lib/aot-impl.js).
+  const fill = options.applyDefaults === true;
   const defs = schema && (schema.$defs || schema.definitions);
 
   const defLines = [];
@@ -240,9 +242,11 @@ export type Result = ValidResult | InvalidResult;
 
 export declare function isValid(data: unknown): data is ${rootName};
 export declare function validate(data: unknown): Result;
-export declare const schemaHash: string;
+${fill ? `/** Fills in the schema's \`default\` values where a key is missing, as the runtime Validator does before checking. Call it before validate() for the runtime's answer. */
+export declare function applyDefaults(data: unknown): void;
+` : ''}export declare const schemaHash: string;
 export declare const ataVersion: string;
-declare const _default: { validate: typeof validate; isValid: typeof isValid; schemaHash: typeof schemaHash; ataVersion: typeof ataVersion };
+declare const _default: { validate: typeof validate; isValid: typeof isValid; ${fill ? 'applyDefaults: typeof applyDefaults; ' : ''}schemaHash: typeof schemaHash; ataVersion: typeof ataVersion };
 export default _default;
 `;
 }

package/lib/validator-core.js

@@ -333,7 +333,13 @@ function resolveSchemaByPath(rootSchema, schemaPath) {
 //
 // A failing route sees the same handful of schemaPaths over and over, which is
 // what makes the first one worth having.
-const { LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, presentErrors, needsOrdering, sortErrorsBySchemaOrder, stripOrdinal } = require('./rejections');
+// Loaded at the first compile, where every use below is, rather than with the
+// core: with it came the schema order and diagnostic modules, run at import
+// by every page that loads the package, validating or not.
+let LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, presentErrors, needsOrdering, sortErrorsBySchemaOrder, stripOrdinal;
+function _loadRejections() {
+  ({ LazyRejection, RichRejection, LazyJsonRejection, _enrichLazy, presentErrors, needsOrdering, sortErrorsBySchemaOrder, stripOrdinal } = require('./rejections'));
+}
 
 // Text that does not parse, reported the same way on every path and platform:
 // ATA9001 with the parser's own message. The native addon used to say only
@@ -716,6 +722,21 @@ function resolveSchemaForPreprocess(schema, schemaMap) {
 // touched), `format` stripped under `assertFormat: false`, and the custom
 // keyword scan. The accessors then step aside for own data properties, so
 // every later read is a plain field.
+// What the interpreted engine is built from, besides the schema.
+function _interpArgs(self, schemaObj) {
+  const options = self._options;
+  return {
+    schemaMap: self._schemaMap.size > 0 ? self._schemaMap : null,
+    formats: self._userFormats,
+    v1: isV1Dialect(schemaObj),
+    keywords: self._keywords,
+    // compat's coercion where each type is checked (see the interpreter).
+    coerce: self._interpretOnly ? options._coerceInWalk : undefined,
+    discriminator: self._interpretOnly && options._discriminator === true,
+    numberFormats: self._interpretOnly ? options._numberFormats : undefined,
+  };
+}
+
 function _materializeSchema(self) {
   const raw = self._rawSchema;
   const options = self._options;
@@ -895,6 +916,8 @@ class Validator {
     this._verdictTail = null;
     this._validateTail = null;
     this._entryExt = null;
+    // The browser build warms the engine once, when the page is idle (lib/tiering.js).
+    if (_tiering !== null) _tiering.built(this);
 
     // Public methods start as memoized accessors on the prototype; nothing is
     // allocated per instance until one is first read. See _defineLazyMethod
@@ -947,6 +970,7 @@ class Validator {
 
   _ensureCompiled() {
     if (this._initialized) return;
+    if (LazyRejection === undefined) _loadRejections();
     this._ensureVocabularies();
     this._initialized = true;
     // Errors behind a reference into a registered document are ordered as
@@ -1201,17 +1225,10 @@ class Validator {
       // No JS codegen: the interpreted engine, with or without the addon. The
       // buffer APIs come from _installBufferApis on first use, as they do on
       // every other path.
-      const { createInterpreter } = require('./interpreter');
-      const interp = createInterpreter(schemaObj, {
-        schemaMap: this._schemaMap.size > 0 ? this._schemaMap : null,
-        formats: this._userFormats,
-        v1: isV1Dialect(schemaObj),
-        keywords: this._keywords,
-        // compat's coercion where each type is checked (see the interpreter).
-        coerce: this._interpretOnly ? options._coerceInWalk : undefined,
-        discriminator: this._interpretOnly && options._discriminator === true,
-        numberFormats: this._interpretOnly ? options._numberFormats : undefined,
-      });
+      const iargs = _interpArgs(this, schemaObj);
+      // The browser build may have built it while the page was idle, from
+      // the same inputs (lib/tiering.js).
+      const interp = (_tiering !== null && _tiering.adopt(this, schemaObj, iargs)) || require('./interpreter').createInterpreter(schemaObj, iargs);
       this._engine = 'interpreter';
       if (_codegen === null && _tiering !== null && !_forceNapi && !this._v1Dynamic) _tiering.watch(this, interp);
       // A keyword that reads its data's context may also change the data (a
@@ -2506,4 +2523,4 @@ Object.defineProperty(module.exports, '_codegenRegistered', { value: () => _code
 Object.defineProperty(module.exports, '_tiering', { get: () => _tiering, enumerable: false });
 Object.defineProperty(module.exports, '_registerAot', { value: _registerAot, enumerable: false });
 // What the compiled paths in index.js need from this module.
-Object.defineProperty(module.exports, '_internals', { value: { _jsonSyntaxRejection, ABORT_EARLY_RESULT, HYBRID_TIER_CALLS, SIMDJSON_THRESHOLD, VALID_RESULT, _bindEntry, _bindVerdict, _compileCache, _compileCacheSet, _mustReject, _rememberInstance, _verboseWrap, compileCacheKey, getNative, isV1Dialect, resolveSchemaByPath }, enumerable: false });
+Object.defineProperty(module.exports, '_internals', { value: { _interpArgs, _normalizeCallerSchemaUncached, resolveSchemaForPreprocess, _jsonSyntaxRejection, ABORT_EARLY_RESULT, HYBRID_TIER_CALLS, SIMDJSON_THRESHOLD, VALID_RESULT, _bindEntry, _bindVerdict, _compileCache, _compileCacheSet, _mustReject, _rememberInstance, _verboseWrap, compileCacheKey, getNative, isV1Dialect, resolveSchemaByPath }, enumerable: false });

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "JSON Schema validator that compiles to plain JavaScript, still runs where code generation is blocked, and can be compiled away at build time. Passes the full official test suite.",
   "type": "commonjs",
   "main": "index.js",
@@ -185,13 +185,13 @@
     "codegen.d.ts"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.56.0",
-    "@ata-validator/native-darwin-x64": "1.56.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.56.0",
-    "@ata-validator/native-linux-arm64-musl": "1.56.0",
-    "@ata-validator/native-linux-x64-gnu": "1.56.0",
-    "@ata-validator/native-linux-x64-musl": "1.56.0",
-    "@ata-validator/native-win32-x64": "1.56.0"
+    "@ata-validator/native-darwin-arm64": "1.57.0",
+    "@ata-validator/native-darwin-x64": "1.57.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.57.0",
+    "@ata-validator/native-linux-arm64-musl": "1.57.0",
+    "@ata-validator/native-linux-x64-gnu": "1.57.0",
+    "@ata-validator/native-linux-x64-musl": "1.57.0",
+    "@ata-validator/native-win32-x64": "1.57.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"