ata-validator 0.18.2 → 0.21.0

package/lib/aot.js

@@ -0,0 +1,410 @@
+'use strict';
+
+// All ahead-of-time (AOT) code generation lives here so the default and browser
+// entries can stay free of `fs`, `path`, `__dirname`, and `pkg-prebuilds`.
+// Browser bundles get `lib/aot.browser.js` instead (see package.json `browser`
+// field), which throws if anyone tries to call an AOT function from the browser.
+//
+// Public surface (called by index.js and ata-validator/build):
+//   toStandalone(validator)
+//   toStandaloneModule(validator, opts)
+//   bundle(Validator, schemas, opts)
+//   bundleStandalone(Validator, schemas, opts)
+//   bundleCompact(Validator, schemas, opts)
+//   loadBundle(Validator, mods, schemas, opts)
+
+const { compileToJSCodegenWithErrors } = require('./js-compiler');
+const SAFE_REGEX_SOURCE = require('./safe-regex-source');
+
+// Embedded verbatim in standalone modules so the output file has no runtime
+// dependency on ata-validator. ASCII fast-path plus surrogate-aware slow path.
+const _CP_LEN_SOURCE = `function _cpLen(s) {
+  const len = s.length;
+  for (let i = 0; i < len; i++) {
+    if (s.charCodeAt(i) >= 0xD800 && s.charCodeAt(i) <= 0xDBFF) {
+      let n = 0; for (const _ of s) n++; return n;
+    }
+  }
+  return len;
+}`;
+
+// The linear-time regex engine, inlined verbatim into standalone output so a
+// compiled module that uses safe `pattern` matchers has no runtime dependency
+// on ata-validator. The engine source is baked into `lib/safe-regex-source.js`
+// at build time (see `scripts/regen-safe-regex-source.js`), so this path has
+// no `fs`/`path`/`__dirname` reads — safe in browser bundles too. The embed
+// strips the strict directive and CommonJS exports and adds the `__ataSafeRe`
+// alias the emitted code calls. The engine has no eval/new Function, so the
+// embed is CSP-safe.
+let _safeRegexEmbed = null;
+function getSafeRegexEmbed() {
+  if (_safeRegexEmbed === null) {
+    const body = SAFE_REGEX_SOURCE
+      .replace(/^'use strict'\s*\n/, '')
+      .replace(/\nmodule\.exports[^\n]*\n?/, '\n');
+    _safeRegexEmbed = body.trimEnd() + '\nconst __ataSafeRe = compileSafe;';
+  }
+  return _safeRegexEmbed;
+}
+
+// Returns the engine embed when any supplied compiled function references the
+// safe matcher (jsFn._usesSafeRe), else an empty string so non-pattern modules
+// pay zero bytes.
+function safeRePrelude(...fns) {
+  return fns.some((f) => f && f._usesSafeRe) ? getSafeRegexEmbed() + '\n' : '';
+}
+
+// --- Standalone pre-compilation ---
+// Generate a JS module string that can be written to a file.
+// On next startup, load with Validator.fromStandalone() -- zero compile time.
+function toStandalone(validator) {
+  validator._ensureCompiled();
+  const jsFn = validator._jsFn;
+  if (!jsFn || !jsFn._source) return null;
+  const src = jsFn._source;
+  const hybridSrc = jsFn._hybridSource || '';
+  const preambleSrc = jsFn._preambleSource || '';
+
+  // Also capture error function source for zero-compile standalone load
+  const jsErrFn = compileToJSCodegenWithErrors(
+    typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
+  );
+  const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
+
+  return `// Auto-generated by ata-validator — do not edit
+'use strict';
+${_CP_LEN_SOURCE}
+${safeRePrelude(jsFn, jsErrFn)}${preambleSrc}
+const boolFn = function(d) {
+  ${src}
+};
+const hybridFactory = function(R, E) {
+  return function(d) {
+    ${hybridSrc}
+  };
+};
+${errSrc ? `const errFn = function(d, _all) {\n  ${errSrc}\n};` : 'const errFn = null;'}
+module.exports = { boolFn, hybridFactory, errFn };
+`;
+}
+
+// --- Fully standalone module ---
+// Generates a self-contained module that can be imported directly without
+// pulling in ata-validator at runtime. Browser bundle gets only the
+// generated validator (~2 KB typical) instead of the 165 KB compiler.
+//
+//   import { validate, isValid } from './user-validator.mjs'
+//   if (isValid(data)) { ... }
+//
+// format: 'esm' | 'cjs'. Default 'esm'.
+// abortEarly: if true, invalid result is a shared stub; smaller output.
+function toStandaloneModule(validator, opts) {
+  validator._ensureCompiled();
+  const jsFn = validator._jsFn;
+  if (!jsFn || !jsFn._source) return null;
+  const format = (opts && opts.format) || 'esm';
+  const abortEarly = !!(opts && opts.abortEarly);
+  const source = !!(opts && opts.source);
+  const sourceMap = opts && opts.sourceMap ? opts.sourceMap : null;
+  const schemaFile = opts && opts.schemaFile ? opts.schemaFile : null;
+  const src = jsFn._source;
+
+  let errCore = '';
+  let jsErrFn = null;
+  if (!abortEarly) {
+    jsErrFn = compileToJSCodegenWithErrors(
+      typeof validator._schemaObj === 'object' ? validator._schemaObj : {},
+      null,
+      validator._userFormats,
+      (source && sourceMap && schemaFile) ? { sourceMap, schemaFile } : null,
+    );
+    const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
+    if (errSrc) {
+      errCore = `const errFn = function(d, _all) {\n  ${errSrc}\n};\n`;
+    }
+  }
+
+  // Schema-source frames are baked as literals inside each emitted error so
+  // consumers don't need a runtime lookup. We still expose the schema file
+  // as a sentinel constant when --source is on — handy for introspection
+  // and visible in source graphs. With --no-source, the constant is omitted
+  // entirely so size budgets and grep-based "is this source-mapped?" checks
+  // both work.
+  const schemaSourceConst = (source && schemaFile)
+    ? `const __ATA_SCHEMA_SOURCE__ = ${JSON.stringify({ file: schemaFile })};\n`
+    : '';
+
+  // Serialize closure vars referenced in _fn body: regex, sub-validators, sets.
+  let closureDecls = '';
+  if (jsFn._closures && jsFn._closures.length > 0) {
+    const lines = [];
+    for (const { name, val } of jsFn._closures) {
+      if (Array.isArray(val)) {
+        lines.push(`const ${name} = ${JSON.stringify(val)};`);
+        continue;
+      }
+      if (val && val.__ataSafe) {
+        lines.push(`const ${name} = __ataSafeRe(${JSON.stringify(val.source)});`);
+      } else if (val instanceof RegExp) {
+        const flags = val.flags;
+        lines.push(`const ${name} = new RegExp(${JSON.stringify(val.source)}${flags ? ', ' + JSON.stringify(flags) : ''});`);
+      } else if (val instanceof Set) {
+        lines.push(`const ${name} = new Set(${JSON.stringify([...val])});`);
+      } else if (typeof val === 'function') {
+        // new Function('_ppv', body) — extract body from toString()
+        const str = val.toString();
+        // Matches: "function anonymous(_ppv\n) {\nbody\n}" or "function(_ppv){body}"
+        const m = str.match(/^function[^(]*\([^)]*\)\s*\{([\s\S]*)\}$/)
+        const body = m ? m[1].trim() : str;
+        lines.push(`const ${name} = function(_ppv) { ${body} };`);
+      }
+    }
+    if (lines.length) closureDecls = lines.join('\n') + '\n';
+  }
+
+  // Hoisted oneOf/anyOf branch checks live in the boolean fn's preamble (the
+  // runtime emits them before the function). The standalone module must declare
+  // them at module scope too, or _fn references undefined names (e.g. _af1_b0).
+  const preambleDecls = jsFn._preambleSource ? jsFn._preambleSource + '\n' : '';
+
+  // User-supplied format functions are referenced as _uf_<name> by both the
+  // boolean (_fn) and error (errFn) bodies. Embed them via Function#toString
+  // so the standalone module stays self-contained.
+  let formatDecls = '';
+  if (jsFn._formatClosures && jsFn._formatClosures.length > 0) {
+    formatDecls = jsFn._formatClosures
+      .map(({ name, fn }) => `const ${name} = ${fn.toString()};`)
+      .join('\n') + '\n';
+  }
+
+  const validBody = errCore
+    ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
+    : 'return _fn(data) ? VALID : ABORT';
+
+  const exports = format === 'esm'
+    ? `export { validate, isValid };\nexport default { validate, isValid };\n`
+    : `module.exports = { validate, isValid };\nmodule.exports.default = module.exports;\n`;
+
+  return `// Auto-generated by ata-validator — do not edit.
+// Schema is embedded; runtime has zero dependency on ata-validator.
+'use strict';
+${_CP_LEN_SOURCE}
+${safeRePrelude(jsFn, jsErrFn)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+const ABORT = Object.freeze({
+  valid: false,
+  errors: Object.freeze([Object.freeze({
+    code: 'ATA9000',
+    message: 'validation failed',
+    keyword: '__abort_early__',
+    path: '',
+  })]),
+});
+${closureDecls}${preambleDecls}${formatDecls}const _fn = function(d) {
+  ${src}
+};
+${errCore}function isValid(data) { return _fn(data); }
+function validate(data) { ${validBody}; }
+${exports}`;
+}
+
+// Bundle multiple validators into a single JS file for fast startup.
+// Usage:
+//   const bundle = Validator.bundle([schema1, schema2, ...]);
+//   fs.writeFileSync('validators.js', bundle);
+//   // On startup:
+//   const validators = Validator.loadBundle(require('./validators.js'), [schema1, schema2, ...]);
+function bundle(Validator, schemas, opts) {
+  const parts = schemas.map((schema) => {
+    const v = new Validator(schema, opts);
+    const standalone = toStandalone(v);
+    if (!standalone) return 'null';
+    return (
+      '(function(){' +
+      standalone
+        .replace("'use strict';", '')
+        .replace('module.exports = ', 'return ') +
+      '})()'
+    );
+  });
+  return "'use strict';\nmodule.exports = [\n" + parts.join(',\n') + '\n];\n';
+}
+
+// Zero-dependency self-contained bundle — no require('ata-validator') needed at runtime.
+// opts.format: 'cjs' (default) or 'esm'.
+// opts.formats: { name: fn } — embedded in the output via Function#toString.
+function bundleStandalone(Validator, schemas, opts) {
+  // Cross-schema $ref resolution: only meaningful when at least one schema has
+  // an $id. Skip the schemas-as-map plumbing when none of them do.
+  const haveIds = schemas.some((s) => s && typeof s === 'object' && s.$id);
+  const bundleOpts = haveIds ? { ...(opts || {}), schemas } : (opts || {});
+  const format = (opts && opts.format) || 'cjs';
+  const R = 'Object.freeze({valid:true,errors:Object.freeze([])})';
+  let bundleUsesSafeRe = false;
+  const fns = schemas.map((schema) => {
+    const v = new Validator(schema, bundleOpts);
+    v._ensureCompiled();
+    const jsFn = v._jsFn;
+    if (!jsFn || !jsFn._hybridSource) return 'null';
+    const jsErrFn = compileToJSCodegenWithErrors(
+      typeof schema === 'string' ? JSON.parse(schema) : schema,
+      v._schemaMap,
+      v._userFormats,
+    );
+    if (jsFn._usesSafeRe || (jsErrFn && jsErrFn._usesSafeRe)) bundleUsesSafeRe = true;
+    const errBody =
+      jsErrFn && jsErrFn._errSource
+        ? jsErrFn._errSource
+        : "return{valid:false,errors:[{code:'error',path:'',message:'validation failed'}]}";
+    // Serialize custom format closures so the bundle has no runtime dep on ata.
+    let preamble = '';
+    if (jsFn._formatClosures) {
+      preamble = jsFn._formatClosures
+        .map(({ name, fn }) => `var ${name}=${fn.toString()};`)
+        .join('\n');
+    }
+    // Include hoisted anyOf/oneOf branch helpers (e.g. `_af1_b0`) so the
+    // bundle output is self-contained. `toStandalone` emits this same source
+    // for single-schema standalone output.
+    if (jsFn._preambleSource) {
+      preamble = preamble ? `${preamble}\n${jsFn._preambleSource}` : jsFn._preambleSource;
+    }
+    if (opts && opts.verbose) {
+      // Embed the schema and a small resolver so errors carry parentSchema.
+      const schemaLit = JSON.stringify(typeof schema === 'string' ? JSON.parse(schema) : schema);
+      return `(function(R){${preamble}var _S=${schemaLit};function _PS(p){if(!p||p[0]!=='#')return undefined;var s=p.slice(1);if(!s)return _S;var ps=s.split('/').filter(Boolean).map(function(x){return x.replace(/~1/g,'/').replace(/~0/g,'~')});var t=_S;for(var i=0;i<ps.length-1;i++){if(t==null||typeof t!=='object')return undefined;t=t[ps[i]]}return t}var E=function(d){var _all=true;${errBody}};var _v=function(d){${jsFn._hybridSource}};return function(d){var r=_v(d);if(r&&r.valid===false&&r.errors){var es=[];for(var i=0;i<r.errors.length;i++){var e=r.errors[i];es.push(Object.assign({},e,{parentSchema:_PS(e.schemaPath)}))}return{valid:false,errors:es}}return r}})(R)`;
+    }
+    return `(function(R){${preamble}var E=function(d){var _all=true;${errBody}};return function(d){${jsFn._hybridSource}}})(R)`;
+  });
+  const arr = `[${fns.join(',')}]`;
+  const safeEmbed = bundleUsesSafeRe ? getSafeRegexEmbed() + '\n' : '';
+  if (format === 'esm') {
+    return `// Auto-generated by ata-validator — do not edit\n${safeEmbed}const R=${R};\nconst validators=${arr};\nexport default validators;\nexport { validators };\n`;
+  }
+  return `'use strict';\n${safeEmbed}var R=${R};\nmodule.exports=[${fns.join(',')}];\n`;
+}
+
+// Compact bundle: deduplicated code. Shared template functions + per-schema params.
+// Much smaller file → faster V8 parse → faster startup.
+// opts.format: 'cjs' (default) or 'esm'.
+function bundleCompact(Validator, schemas, opts) {
+  const haveIds = schemas.some((s) => s && typeof s === 'object' && s.$id);
+  const bundleOpts = haveIds ? { ...(opts || {}), schemas } : (opts || {});
+  const format = (opts && opts.format) || 'cjs';
+  let bundleUsesSafeRe = false;
+  // Analyze schemas and group by structure
+  const entries = schemas.map((schema) => {
+    const v = new Validator(schema, bundleOpts);
+    v._ensureCompiled();
+    const jsFn = v._jsFn;
+    if (!jsFn || !jsFn._hybridSource) return null;
+    const jsErrFn = compileToJSCodegenWithErrors(
+      typeof schema === 'string' ? JSON.parse(schema) : schema,
+      v._schemaMap,
+      v._userFormats,
+    );
+    if (jsFn._usesSafeRe || (jsErrFn && jsErrFn._usesSafeRe)) bundleUsesSafeRe = true;
+    // Hoisted anyOf/oneOf branch helpers (e.g. `_af1_b0`) must travel with the
+    // hybrid body or it references undefined names. Prepending keeps dedup honest:
+    // schemas with different branch sets no longer collide on body alone.
+    const hybrid = jsFn._preambleSource
+      ? `${jsFn._preambleSource}\n${jsFn._hybridSource}`
+      : jsFn._hybridSource;
+    return {
+      hybrid,
+      err: jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : null,
+      fmt: jsFn._formatClosures || null,
+    };
+  });
+
+  // Deduplicate function bodies — many schemas produce identical or near-identical code
+  const bodyMap = new Map(); // body → index
+  const bodies = [];
+  const errMap = new Map();
+  const errBodies = [];
+
+  const indices = entries.map((e) => {
+    if (!e) return [-1, -1];
+    let hi = bodyMap.get(e.hybrid);
+    if (hi === undefined) {
+      hi = bodies.length;
+      bodies.push(e.hybrid);
+      bodyMap.set(e.hybrid, hi);
+    }
+    let ei = -1;
+    if (e.err) {
+      ei = errMap.get(e.err);
+      if (ei === undefined) {
+        ei = errBodies.length;
+        errBodies.push(e.err);
+        errMap.set(e.err, ei);
+      }
+    }
+    return [hi, ei];
+  });
+
+  // Generate compact bundle
+  const isEsm = format === 'esm';
+  let out = isEsm
+    ? '// Auto-generated by ata-validator — do not edit\n'
+    : "'use strict';\n";
+  if (bundleUsesSafeRe) out += getSafeRegexEmbed() + '\n';
+  const declKW = isEsm ? 'const' : 'var';
+  out += `${declKW} R=Object.freeze({valid:true,errors:Object.freeze([])});\n`;
+
+  // User format functions are referenced as _uf_<name> by the hybrid and error
+  // bodies. Collect them across all schemas (deduped by name) and embed via
+  // Function#toString so the bundle stays self-contained.
+  const fmtSeen = new Set();
+  for (const e of entries) {
+    if (!e || !e.fmt) continue;
+    for (const { name, fn } of e.fmt) {
+      if (fmtSeen.has(name)) continue;
+      fmtSeen.add(name);
+      out += `${declKW} ${name}=${fn.toString()};\n`;
+    }
+  }
+
+  // Shared hybrid factories
+  out += `${declKW} H=[\n`;
+  out += bodies
+    .map((b) => `function(R,E){return function(d){${b}}}`)
+    .join(',\n');
+  out += '\n];\n';
+
+  // Shared error functions
+  out += `${declKW} EF=[\n`;
+  out += errBodies.map((b) => `function(d){var _all=true;${b}}`).join(',\n');
+  out += '\n];\n';
+
+  // Build validators from shared templates
+  const arrBody = indices
+    .map(([hi, ei]) => {
+      if (hi < 0) return 'null';
+      if (ei >= 0) return `H[${hi}](R,EF[${ei}])`;
+      return `H[${hi}](R,function(){return{valid:false,errors:[]}})`;
+    })
+    .join(',');
+  if (isEsm) {
+    out += `const validators=[${arrBody}];\nexport default validators;\nexport { validators };\n`;
+  } else {
+    out += `module.exports=[${arrBody}];\n`;
+  }
+
+  return out;
+}
+
+function loadBundle(Validator, mods, schemas, opts) {
+  return schemas.map((schema, i) => {
+    if (mods[i]) return Validator.fromStandalone(mods[i], schema, opts);
+    return new Validator(schema, opts);
+  });
+}
+
+module.exports = {
+  toStandalone,
+  toStandaloneModule,
+  bundle,
+  bundleStandalone,
+  bundleCompact,
+  loadBundle,
+};

package/lib/error-messages.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// Custom error messages via the `errorMessage` keyword.
+//
+// A subschema may declare an `errorMessage` keyword to override the generated
+// `message` on any error it owns:
+//
+//   errorMessage: "single message for any failure of this subschema"
+//   errorMessage: {
+//     <keyword>: "msg",                 // e.g. minimum, type, pattern, format
+//     required: "msg" | { prop: "msg" },// keyed by missing property, or one string
+//     additionalProperties: "msg",
+//     _: "fallback msg",                // used when no keyword-specific entry matches
+//   }
+//
+// Resolution: each error's owning subschema is located from its schemaPath (the
+// keyword is the last pointer segment, the owner is everything before it). If the
+// owner declares an errorMessage, the error's `message` is replaced. Errors are
+// cloned, never mutated, so frozen/shared results stay intact. When no schema in
+// the tree carries an errorMessage the decorator is never installed, so the
+// validate hot path keeps its original cost.
+
+// Locate the schema object that owns the failing keyword. Mirrors
+// resolveSchemaByPath() in index.js: the last pointer segment is the keyword,
+// so the owner is the node reached by walking every segment before it.
+function resolveOwner (rootSchema, schemaPath) {
+  if (!schemaPath || typeof schemaPath !== 'string' || schemaPath[0] !== '#') return undefined;
+  const stripped = schemaPath.slice(1);
+  if (!stripped || stripped === '/') return rootSchema;
+  const parts = stripped.split('/').filter(Boolean).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let target = rootSchema;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (target == null || typeof target !== 'object') return undefined;
+    target = target[parts[i]];
+  }
+  return target;
+}
+
+// Pick the override string for a single error from its owner's errorMessage.
+// Returns undefined when nothing matches, leaving the default message in place.
+function pickMessage (em, err) {
+  if (em == null) return undefined;
+  if (typeof em === 'string') return em;
+  if (typeof em !== 'object') return undefined;
+
+  const kw = err.keyword;
+
+  if (kw === 'required') {
+    const r = em.required;
+    if (typeof r === 'string') return r;
+    if (r && typeof r === 'object') {
+      const prop = err.params && err.params.missingProperty;
+      if (prop != null && typeof r[prop] === 'string') return r[prop];
+    }
+  }
+
+  if (kw != null && typeof em[kw] === 'string') return em[kw];
+  if (typeof em._ === 'string') return em._;
+  return undefined;
+}
+
+// Returns true when the schema string is worth scanning at validate time.
+function schemaHasErrorMessages (schemaStr) {
+  return typeof schemaStr === 'string' && schemaStr.indexOf('"errorMessage"') !== -1;
+}
+
+// Apply overrides across an error array. Returns the same array reference when
+// nothing changed (so callers can cheaply detect a no-op), or a new array with
+// cloned-and-overridden entries.
+function applyErrorMessages (errors, rootSchema) {
+  if (!errors || !errors.length) return errors;
+  let changed = false;
+  const out = new Array(errors.length);
+  for (let i = 0; i < errors.length; i++) {
+    const err = errors[i];
+    out[i] = err;
+    if (!err || typeof err.schemaPath !== 'string') continue;
+    const owner = resolveOwner(rootSchema, err.schemaPath);
+    if (!owner || typeof owner !== 'object') continue;
+    const msg = pickMessage(owner.errorMessage, err);
+    if (msg == null) continue;
+    out[i] = Object.assign({}, err, { message: msg });
+    changed = true;
+  }
+  return changed ? out : errors;
+}
+
+module.exports = { schemaHasErrorMessages, applyErrorMessages, resolveOwner, pickMessage };

package/lib/native-load.browser.js

@@ -0,0 +1,8 @@
+'use strict';
+
+// Browser stub: there is no native addon in the browser. Swapped in via the
+// package.json `browser` field so bundlers never resolve `pkg-prebuilds`.
+
+module.exports = function loadNative() {
+  return null;
+};

package/lib/native-load.js

@@ -0,0 +1,21 @@
+'use strict';
+
+// Locate and load the optional native addon (pkg-prebuilds). Lives in its own
+// module so the default and browser entries can stay free of `pkg-prebuilds`,
+// `__dirname`, and `path` references. In browser bundles this file is replaced
+// with `native-load.browser.js` via the package.json `browser` field, so the
+// `pkg-prebuilds` import never enters the bundle in the first place.
+//
+// Returns the loaded native binding object, or `null` if no prebuild matches
+// (musl/Alpine, unsupported arch, devs running before `npm run build`, etc.).
+// The JS codegen path covers all core validation when this returns null.
+
+module.exports = function loadNative() {
+  try {
+    const path = require('path');
+    const pkg = require('pkg-prebuilds');
+    return pkg(path.join(__dirname, '..'), require('../binding-options'));
+  } catch {
+    return null;
+  }
+};

package/lib/refine.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// Async refinement support for the `/t` builder.
+//
+// JSON Schema is synchronous by design and cannot express a check that needs to
+// await (uniqueness, a remote lookup, cross-field business rules). Those live on
+// the builder via `t.refine(schema, check, opts)`. A refinement is carried on a
+// Symbol key (like the OPTIONAL marker), so it is invisible to Object.keys,
+// JSON.stringify, and ata's codegen: `new Validator(schema)` still performs
+// plain structural validation and ignores refinements entirely.
+//
+// `validateAsync()` (in index.js) runs structural validation first and only
+// awaits the refinements when the value is structurally valid — a refinement
+// body may assume the value already has the right shape.
+
+const REFINE = Symbol.for('ata.t.refine');
+
+// Pull the refinement list off a schema node, or null when there is none.
+function getRefinements (schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  const r = schema[REFINE];
+  return Array.isArray(r) && r.length ? r : null;
+}
+
+// Attach a refinement to a schema, composing with any already present. Returns a
+// new object; the input is not mutated. Enumerable Symbol keys (OPTIONAL, prior
+// refinements) are copied by the spread, then the refinement list is replaced.
+function attach (schema, check, opts) {
+  if (typeof check !== 'function') {
+    throw new TypeError('t.refine(schema, check, opts?) — check must be a function');
+  }
+  const prev = (schema && Array.isArray(schema[REFINE])) ? schema[REFINE] : [];
+  const o = opts || {};
+  const entry = { check, message: o.message, path: o.path || '' };
+  return Object.assign({}, schema, { [REFINE]: prev.concat(entry) });
+}
+
+// Build a single refinement issue in the validator's error shape.
+function issue (entry, message) {
+  return {
+    keyword: 'refine',
+    instancePath: entry.path || '',
+    path: entry.path || '',
+    schemaPath: '',
+    params: {},
+    message: message != null ? message : (entry.message || 'value failed refinement'),
+  };
+}
+
+// Evaluate every refinement against `data`, awaiting async checks concurrently.
+// A check that returns falsy — or throws — yields an issue. Returns the issues
+// array (empty when all pass).
+async function runRefinements (refinements, data) {
+  const issues = [];
+  await Promise.all(refinements.map(async (entry) => {
+    let passed;
+    try {
+      passed = await entry.check(data);
+    } catch (e) {
+      issues.push(issue(entry, entry.message || (e && e.message) || 'refinement threw'));
+      return;
+    }
+    if (!passed) issues.push(issue(entry));
+  }));
+  return issues;
+}
+
+module.exports = { REFINE, getRefinements, attach, runRefinements };

package/lib/safe-regex-source.js

@@ -0,0 +1,8 @@
+'use strict';
+
+// Auto-generated by scripts/regen-safe-regex-source.js — do not edit.
+// Mirrors `lib/safe-regex.js` verbatim so `lib/aot.js` can embed the engine
+// into standalone output without a runtime `fs` read. Kept in sync by
+// `tests/test_safe_regex_source_sync.js`.
+
+module.exports = "'use strict'\n\n// Linear-time regex engine for JSON Schema `pattern`, used in place of JS RegExp\n// so an adversarial input cannot trigger catastrophic backtracking (ReDoS).\n//\n// It is a Pike VM: the pattern compiles to a small instruction program, and the\n// VM simulates all NFA threads in lockstep over the input, deduping by program\n// counter. Runtime is O(input * program), with no backtracking.\n//\n// Supported (the RE2 subset, which is what ata's native path also accepts):\n// literals, ., character classes, \\d \\w \\s \\D \\W \\S, anchors ^ $, quantifiers\n// * + ? {n} {n,} {n,m} (greedy or lazy, same language for a boolean test),\n// groups ( ) (?: ), alternation |. Backreferences and lookaround are not\n// supported by linear engines; compileSafe throws on them so the caller can\n// decide (ata's codegen rejects such schemas rather than risk a hang).\n\nconst WS = [[9, 13], [32, 32], [160, 160]]\nconst DIGIT = [[48, 57]]\nconst WORD = [[48, 57], [65, 90], [97, 122], [95, 95]]\n\nfunction parse (src) {\n  let i = 0\n  const len = src.length\n  const peek = () => src[i]\n  const eof = () => i >= len\n\n  function parseAlt () {\n    const opts = [parseConcat()]\n    while (!eof() && peek() === '|') { i++; opts.push(parseConcat()) }\n    return opts.length === 1 ? opts[0] : { t: 'alt', opts }\n  }\n\n  function parseConcat () {\n    const parts = []\n    while (!eof() && peek() !== '|' && peek() !== ')') parts.push(parseRepeat())\n    if (parts.length === 0) return { t: 'empty' }\n    return parts.length === 1 ? parts[0] : { t: 'concat', parts }\n  }\n\n  function parseRepeat () {\n    let node = parseAtom()\n    while (!eof()) {\n      const ch = peek()\n      if (ch === '*') { i++; node = { t: 'star', child: node } }\n      else if (ch === '+') { i++; node = { t: 'plus', child: node } }\n      else if (ch === '?') { i++; node = { t: 'quest', child: node } }\n      else if (ch === '{') {\n        const saved = i\n        const q = tryQuantifier()\n        if (!q) { i = saved; break }\n        node = { t: 'repeat', child: node, min: q.min, max: q.max }\n      } else break\n      // a trailing ? makes the quantifier lazy; same language for a boolean test\n      if (!eof() && peek() === '?') i++\n    }\n    return node\n  }\n\n  function tryQuantifier () {\n    // assumes current char is '{'\n    i++\n    let min = ''\n    while (!eof() && /[0-9]/.test(peek())) { min += peek(); i++ }\n    if (min === '') return null\n    let max\n    if (peek() === '}') { i++; return { min: +min, max: +min } }\n    if (peek() === ',') {\n      i++\n      let m = ''\n      while (!eof() && /[0-9]/.test(peek())) { m += peek(); i++ }\n      if (peek() !== '}') return null\n      i++\n      max = m === '' ? Infinity : +m\n      return { min: +min, max }\n    }\n    return null\n  }\n\n  function parseAtom () {\n    const ch = peek()\n    if (ch === '(') {\n      i++\n      if (src[i] === '?') {\n        if (src[i + 1] === ':') { i += 2 }\n        else throw new Error('unsupported group (lookaround/named) in pattern')\n      }\n      const child = parseAlt()\n      if (peek() !== ')') throw new Error('unbalanced ( in pattern')\n      i++\n      return { t: 'group', child }\n    }\n    if (ch === '[') return parseClass()\n    if (ch === '.') { i++; return { t: 'any' } }\n    if (ch === '^') { i++; return { t: 'bol' } }\n    if (ch === '$') { i++; return { t: 'eol' } }\n    if (ch === '\\\\') return parseEscape(false)\n    if (ch === ')' || ch === '|') return { t: 'empty' }\n    i++\n    return { t: 'char', c: ch.charCodeAt(0) }\n  }\n\n  function parseClass () {\n    i++ // [\n    let neg = false\n    if (peek() === '^') { neg = true; i++ }\n    const ranges = []\n    while (!eof() && peek() !== ']') {\n      let lo\n      if (peek() === '\\\\') {\n        const esc = parseEscape(true)\n        if (esc.t === 'classpart') { for (const r of esc.ranges) ranges.push(r); continue }\n        lo = esc.c\n      } else { lo = peek().charCodeAt(0); i++ }\n      if (peek() === '-' && src[i + 1] !== ']' && i + 1 < len) {\n        i++ // -\n        let hi\n        if (peek() === '\\\\') { const e = parseEscape(true); hi = e.c } else { hi = peek().charCodeAt(0); i++ }\n        ranges.push([lo, hi])\n      } else {\n        ranges.push([lo, lo])\n      }\n    }\n    if (peek() !== ']') throw new Error('unbalanced [ in pattern')\n    i++\n    return { t: 'class', neg, ranges }\n  }\n\n  function parseEscape (inClass) {\n    i++ // backslash\n    if (eof()) throw new Error('trailing backslash in pattern')\n    const ch = peek(); i++\n    switch (ch) {\n      case 'd': return inClass ? { t: 'classpart', ranges: DIGIT } : { t: 'class', neg: false, ranges: DIGIT }\n      case 'w': return inClass ? { t: 'classpart', ranges: WORD } : { t: 'class', neg: false, ranges: WORD }\n      case 's': return inClass ? { t: 'classpart', ranges: WS } : { t: 'class', neg: false, ranges: WS }\n      case 'D': if (inClass) throw new Error('\\\\D inside a class is not supported'); return { t: 'class', neg: true, ranges: DIGIT }\n      case 'W': if (inClass) throw new Error('\\\\W inside a class is not supported'); return { t: 'class', neg: true, ranges: WORD }\n      case 'S': if (inClass) throw new Error('\\\\S inside a class is not supported'); return { t: 'class', neg: true, ranges: WS }\n      case 'n': return { t: 'char', c: 10 }\n      case 'r': return { t: 'char', c: 13 }\n      case 't': return { t: 'char', c: 9 }\n      case 'f': return { t: 'char', c: 12 }\n      case 'v': return { t: 'char', c: 11 }\n      case '0': return { t: 'char', c: 0 }\n      case 'x': { const h = src.slice(i, i + 2); i += 2; return { t: 'char', c: parseInt(h, 16) } }\n      case 'u': { const h = src.slice(i, i + 4); i += 4; return { t: 'char', c: parseInt(h, 16) } }\n      case 'b': if (inClass) return { t: 'char', c: 8 }; throw new Error('\\\\b word boundary is not supported')\n      default:\n        if (/[1-9]/.test(ch)) throw new Error('backreferences are not supported in pattern')\n        return { t: 'char', c: ch.charCodeAt(0) }\n    }\n  }\n\n  const ast = parseAlt()\n  if (!eof()) throw new Error('unexpected \"' + peek() + '\" in pattern')\n  return ast\n}\n\nfunction compileProg (ast) {\n  const prog = []\n  const emit = (op, extra) => { const idx = prog.length; prog.push(Object.assign({ op }, extra)); return idx }\n\n  function rec (n) {\n    switch (n.t) {\n      case 'empty': break\n      case 'char': emit('char', { c: n.c }); break\n      case 'any': emit('any'); break\n      case 'class': emit('class', { neg: n.neg, ranges: n.ranges }); break\n      case 'bol': emit('bol'); break\n      case 'eol': emit('eol'); break\n      case 'group': rec(n.child); break\n      case 'concat': for (const p of n.parts) rec(p); break\n      case 'alt': {\n        const jmps = []\n        for (let k = 0; k < n.opts.length; k++) {\n          if (k < n.opts.length - 1) {\n            const sp = emit('split', { x: 0, y: 0 })\n            prog[sp].x = prog.length\n            rec(n.opts[k])\n            jmps.push(emit('jmp', { x: 0 }))\n            prog[sp].y = prog.length\n          } else {\n            rec(n.opts[k])\n          }\n        }\n        for (const j of jmps) prog[j].x = prog.length\n        break\n      }\n      case 'star': {\n        const sp = emit('split', { x: 0, y: 0 })\n        prog[sp].x = prog.length\n        rec(n.child)\n        emit('jmp', { x: sp })\n        prog[sp].y = prog.length\n        break\n      }\n      case 'plus': {\n        const start = prog.length\n        rec(n.child)\n        const sp = emit('split', { x: start, y: 0 })\n        prog[sp].y = prog.length\n        break\n      }\n      case 'quest': {\n        const sp = emit('split', { x: 0, y: 0 })\n        prog[sp].x = prog.length\n        rec(n.child)\n        prog[sp].y = prog.length\n        break\n      }\n      case 'repeat': {\n        for (let k = 0; k < n.min; k++) rec(n.child)\n        if (n.max === Infinity) {\n          if (n.min === 0) rec({ t: 'star', child: n.child })\n          else rec({ t: 'star', child: n.child })\n        } else {\n          for (let k = 0; k < n.max - n.min; k++) rec({ t: 'quest', child: n.child })\n        }\n        break\n      }\n    }\n  }\n\n  rec(ast)\n  emit('match')\n  return prog\n}\n\nfunction matchClass (instr, c) {\n  let inside = false\n  const r = instr.ranges\n  for (let k = 0; k < r.length; k++) { if (c >= r[k][0] && c <= r[k][1]) { inside = true; break } }\n  return instr.neg ? !inside : inside\n}\n\nfunction makeRunner (prog) {\n  const n = prog.length\n  const lastGen = new Int32Array(n).fill(-1)\n  let gen = 0\n  const stack = []\n\n  function addThread (list, pc, pos, len) {\n    stack.length = 0\n    stack.push(pc)\n    while (stack.length) {\n      const p = stack.pop()\n      if (lastGen[p] === gen) continue\n      lastGen[p] = gen\n      const I = prog[p]\n      switch (I.op) {\n        case 'jmp': stack.push(I.x); break\n        case 'split': stack.push(I.y); stack.push(I.x); break\n        case 'bol': if (pos === 0) stack.push(p + 1); break\n        case 'eol': if (pos === len) stack.push(p + 1); break\n        default: list.push(p)\n      }\n    }\n  }\n\n  return function test (s) {\n    const len = s.length\n    let clist = []\n    let nlist = []\n    gen++\n    addThread(clist, 0, 0, len)\n    for (let pos = 0; pos <= len; pos++) {\n      const c = pos < len ? s.charCodeAt(pos) : -1\n      gen++\n      nlist.length = 0\n      for (let k = 0; k < clist.length; k++) {\n        const pc = clist[k]\n        const I = prog[pc]\n        if (I.op === 'match') return true\n        else if (I.op === 'char') { if (c === I.c) addThread(nlist, pc + 1, pos + 1, len) }\n        else if (I.op === 'any') { if (c !== -1 && c !== 10) addThread(nlist, pc + 1, pos + 1, len) }\n        else if (I.op === 'class') { if (c !== -1 && matchClass(I, c)) addThread(nlist, pc + 1, pos + 1, len) }\n      }\n      if (pos < len) addThread(nlist, 0, pos + 1, len)\n      const tmp = clist; clist = nlist; nlist = tmp\n    }\n    return false\n  }\n}\n\nfunction compileSafe (pattern) {\n  const prog = compileProg(parse(pattern))\n  const runner = makeRunner(prog)\n  // `__ataSafe` brands the result so the standalone serializer can tell a safe\n  // matcher apart from a RegExp and emit `__ataSafeRe(source)` instead.\n  return { test: runner, source: pattern, __ataSafe: true }\n}\n\n// True when the linear engine can represent `src`. Used by the codegen to decide\n// between the safe matcher and a JS RegExp fallback for patterns outside the\n// supported (RE2) subset (backreferences, lookaround, etc.).\nfunction patternIsSafe (src) {\n  try { compileSafe(src); return true } catch { return false }\n}\n\nmodule.exports = { compileSafe, patternIsSafe }\n";