ata-validator 1.49.0 → 1.51.0

package/lib/public-api.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// The public names of the package, shared by index.js (with the code
+// generator) and index.edge.js (without it), so the two entries export the
+// same thing.
+const core = require('./validator-core.js');
+
+
+
+// The parts no Validator calls: TypeScript generation, the error renderers,
+// the spec output format, the retry message for language models, the schema
+// description and the suggestion helper. ata-validator/lite leaves them out.
+// Each loads its module on first call. None of them is on the path to a first
+// validated request, and together they were about a sixth of what requiring
+// the package cost.
+function toTypeScript (...a) { return require('./ts-gen').toTypeScript(...a); }
+function renderPretty (...a) { return require('./render-pretty').renderPretty(...a); }
+function renderCompact (...a) { return require('./render-compact').renderCompact(...a); }
+function toOutput (...a) { return require('./output-format').toOutput(...a); }
+function toRetryMessage (...a) { return require('./retry-message').toRetryMessage(...a); }
+function describeSchema (...a) { return require('./describe-schema').describeSchema(...a); }
+function renderJSON (...a) { return require('./render-json').renderJSON(...a); }
+
+// Walk a JSON pointer (RFC 6901 escapes) into a data tree. Mirrors the helper
+// inside lib/suggestions.js, kept local to avoid exporting an internal.
+function _walkPointer (root, pointer) {
+  if (!pointer) return root;
+  const parts = pointer.replace(/^\//, '').split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let cur = root;
+  for (const p of parts) { if (cur == null) return undefined; cur = cur[p]; }
+  return cur;
+}
+
+// Post-hoc suggestion enrichment for AOT-compiled validators. The standalone
+// modules do not embed the suggestion engine, so consumers who want
+// suggestions pass the error array through this after validation.
+function attachSuggestions (errors, data) {
+  if (!errors) return errors;
+  const { suggestFor } = require('./suggestions');
+  const { reprValue } = require('./enrich-error');
+  for (const e of errors) {
+    if (!e || e.suggestion) continue;
+    let received = e.received;
+    if (received === undefined && data !== undefined) {
+      const ptr = e.instancePath != null ? e.instancePath : (e.path || '');
+      const raw = _walkPointer(data, ptr);
+      if (raw !== undefined || ptr === '') received = reprValue(raw);
+    }
+    const probe = received !== undefined && e.received === undefined
+      ? Object.assign({}, e, { received })
+      : e;
+    const s = suggestFor(probe, data);
+    if (s) e.suggestion = s;
+  }
+  // AOT modules import nothing, so this is their only route to a frame. The
+  // caller holds the original object and ran no preprocessing through here.
+  require('./diagnostic-source').setDiagnosticSource(errors, { data, mutatesInput: false });
+  return errors;
+}
+
+module.exports = {
+  Validator: core.Validator,
+  compile: core.compile,
+  validate: core.validate,
+  validateAsync: core.validateAsync,
+  parseAsync: core.parseAsync,
+  version: core.version,
+  createPaddedBuffer: core.createPaddedBuffer,
+  SIMDJSON_PADDING: core.SIMDJSON_PADDING,
+  parseJSON: core.parseJSON,
+  toTypeScript,
+  defineSchema: core.defineSchema,
+  renderPretty,
+  renderCompact,
+  toOutput,
+  toRetryMessage,
+  describeSchema,
+  renderJSON,
+  attachSuggestions, // internal: used by the renderers; not public API
+};

package/lib/schema-order.js

@@ -57,17 +57,53 @@ function rankFor(rootSchema, schemaPath) {
   return rank;
 }
 
+// The documents a root's references reach beyond itself, id to schema, from
+// the validators that own the root (the `schemas` option, addSchema) or a
+// schema module's registry. Several validators of one root schema register
+// their maps into one; an id that two of them give different schemas makes the
+// root resolve nothing outside itself, as it did before any was registered.
+const _documents = new WeakMap();
+const CONFLICT = new Map();
+function registerDocuments(rootSchema, map) {
+  if (rootSchema === null || typeof rootSchema !== 'object' || !map || map.size === 0) return;
+  const had = _documents.get(rootSchema);
+  if (had === CONFLICT) return;
+  if (had === undefined) { _documents.set(rootSchema, new Map(map)); _rankCache.delete(rootSchema); return; }
+  let added = false;
+  for (const [id, doc] of map) {
+    const cur = had.get(id);
+    if (cur === undefined) { had.set(id, doc); added = true; } else if (cur !== doc) { _documents.set(rootSchema, CONFLICT); _rankCache.delete(rootSchema); return; }
+  }
+  if (added) _rankCache.delete(rootSchema);
+}
+
+function withoutEmptyFragment(uri) {
+  return uri.endsWith('#') ? uri.slice(0, -1) : uri;
+}
+
+function resolveUri(ref, base) {
+  try { return base ? new URL(ref, base).href : new URL(ref).href; } catch { return null; }
+}
+
 function computeRank(rootSchema, schemaPath) {
   const rank = [];
   let node = rootSchema;
   let start = 1;
   let hops = 0;
+  const docs = _documents.get(rootSchema);
+  // The document the walk is in and the base URI references resolve against,
+  // for following a reference into another document.
+  let doc = rootSchema;
+  // A root without an $id can still name another document by absolute URI.
+  const follow = docs !== undefined && docs !== CONFLICT;
+  let base = follow && typeof rootSchema.$id === 'string' ? resolveUri(rootSchema.$id, null) : null;
   while (start <= schemaPath.length) {
     let end = schemaPath.indexOf('/', start);
     if (end < 0) end = schemaPath.length;
     if (end === start) { start = end + 1; continue; }
     const seg = unescapePointerSegment(schemaPath.slice(start, end));
     if (node == null || typeof node !== 'object') break;
+    if (follow && node !== doc && !Array.isArray(node) && typeof node.$id === 'string' && node.$id[0] !== '#') base = resolveUri(node.$id, base);
     if (Array.isArray(node)) {
       const idx = Number(seg);
       if (!Number.isInteger(idx) || idx < 0 || idx >= node.length) break;
@@ -80,7 +116,11 @@ function computeRank(rootSchema, schemaPath) {
         // naming it. Ranking the rest inside the target, as if the target sat
         // under the `$ref` key, orders errors behind a reference by the
         // target's declaration order, as they are ordered inline.
-        const target = hops < 64 ? localTarget(rootSchema, node) : null;
+        let target = hops < 64 ? localTarget(doc, node) : null;
+        if (target === null && hops < 64 && follow) {
+          const remote = remoteTarget(docs, base, node);
+          if (remote !== null) { target = remote.node; doc = remote.doc; base = remote.base; }
+        }
         if (target === null) break;
         hops++;
         rank.push(keyIndex(node, '$ref'));
@@ -95,6 +135,28 @@ function computeRank(rootSchema, schemaPath) {
   return rank;
 }
 
+// The schema a node's `$ref` names in a registered document: { node, doc,
+// base }, or null when it names none (an anchor, an unknown document).
+function remoteTarget(docs, base, node) {
+  const ref = node.$ref;
+  if (typeof ref !== 'string' || ref.charCodeAt(0) === 35) return null;
+  const abs = resolveUri(ref, base);
+  if (abs === null) return null;
+  const hash = abs.indexOf('#');
+  const uri = hash < 0 ? abs : abs.slice(0, hash);
+  let target = docs.get(uri);
+  if (target === undefined) target = docs.get(uri + '#');
+  if (target === undefined) {
+    for (const [id, s] of docs) if (withoutEmptyFragment(resolveUri(id, null) || '') === uri) { target = s; break; }
+  }
+  if (target === null || typeof target !== 'object') return null;
+  const frag = hash < 0 ? '' : abs.slice(hash + 1);
+  if (frag === '') return { node: target, doc: target, base: uri };
+  if (frag.charCodeAt(0) !== 47) return null;
+  const t = localTarget(target, { $ref: '#' + frag });
+  return t === null ? null : { node: t, doc: target, base: uri };
+}
+
 // The schema a node's `$ref` names, when it is a pointer into this document.
 function localTarget(rootSchema, node) {
   const ref = node.$ref;
@@ -191,4 +253,4 @@ function ordinalFor(rootSchema, schemaPath) {
 const _missCache = new WeakMap();
 const MISS_CACHE_LIMIT = 4096;
 
-module.exports = { rankFor, ordinalFor, unescapePointerSegment };
+module.exports = { rankFor, ordinalFor, unescapePointerSegment, registerDocuments };

package/lib/schema-runtime-entry.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// The runtime a schema module (`ata build --mode schema`) imports: the verdict
+// and the errors both come from the interpreted engine walking the embedded
+// schema, so a module is its schema and a few lines. Smaller and quicker to
+// load than generated code, slower per check once warm; see docs/API.md.
+// One interpreter per schema answers both, so the schema is prepared once.
+// It loads lib/interpreter.js, which brings the plan compiler for schemas
+// used often (TIER in lib/interpreter-core.js).
+const { createInterpreter } = require('./interpreter');
+const { errorsOf, interpreterOptions } = require('./error-runtime-entry');
+
+// A registry is the array of schemas a build writes beside schema modules
+// whose schemas reference each other by `$id` (ata-registry.mjs). It becomes
+// one Map, id to schema, shared by every module of the build.
+const _maps = new WeakMap();
+function registryMap(registry) {
+  let map = _maps.get(registry);
+  if (map === undefined) {
+    map = new Map();
+    for (const s of registry) map.set(s.$id, s);
+    _maps.set(registry, map);
+  }
+  return map;
+}
+
+// options.registry and options.id: the module's schema is the registry entry
+// with that `$id`, and its references resolve against the registry.
+function createValidator(schema, codeOf, options) {
+  const opts = interpreterOptions(options);
+  if (options && options.registry) {
+    const map = registryMap(options.registry);
+    if (schema === null || schema === undefined) schema = map.get(options.id);
+    opts.schemaMap = map;
+    opts.flat = false;
+    require('./schema-order').registerDocuments(schema, map);
+  }
+  const interp = createInterpreter(schema, opts);
+  return {
+    isValid: (data) => interp.isValid(data),
+    errors: (data) => errorsOf(interp, schema, codeOf, data),
+  };
+}
+
+module.exports = { createValidator };

package/lib/schema-strip.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// A copy of a schema without the keywords that only describe it (title,
+// description, examples and the like), for a compact module that embeds its
+// schema so the shared error runtime can walk it. Validation never reads
+// these, and in a typical published schema they are most of the bytes.
+//
+// Only schema positions are touched. An `enum`, a `const` or any keyword this
+// file does not know is copied as it is, so a value that happens to hold a
+// "description" key keeps it. If a local `$ref` points through a keyword that
+// would be removed, nothing is removed: the reference has to land where it
+// did.
+
+const DROP = new Set([
+  'title', 'description', '$comment', 'examples', 'default', 'deprecated',
+  'readOnly', 'writeOnly', 'markdownDescription', 'deprecationMessage',
+  'enumDescriptions', 'markdownEnumDescriptions', 'defaultSnippets',
+]);
+
+const SINGLE = new Set([
+  'additionalProperties', 'contains', 'propertyNames', 'if', 'then', 'else', 'not',
+  'items', 'unevaluatedItems', 'unevaluatedProperties', 'additionalItems', 'contentSchema',
+]);
+const MAPS = new Set(['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas']);
+const LISTS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+
+function dropped(key) {
+  return DROP.has(key) || key.startsWith('x-');
+}
+
+function setOwn(o, k, v) {
+  // A key named __proto__ has to stay an own property.
+  if (k === '__proto__') Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });
+  else o[k] = v;
+}
+
+function unescape(seg) {
+  return seg.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+// True when some local reference walks through a key that would be dropped.
+function refsIntoDropped(node, seen) {
+  if (node === null || typeof node !== 'object') return false;
+  if (seen.has(node)) return false;
+  seen.add(node);
+  if (Array.isArray(node)) {
+    for (const x of node) if (refsIntoDropped(x, seen)) return true;
+    return false;
+  }
+  for (const k of ['$ref', '$dynamicRef', '$recursiveRef']) {
+    const r = node[k];
+    if (typeof r !== 'string') continue;
+    const hash = r.indexOf('#');
+    if (hash < 0) continue;
+    let frag;
+    try { frag = decodeURIComponent(r.slice(hash + 1)); } catch { return true; }
+    if (!frag.startsWith('/')) continue;
+    for (const seg of frag.slice(1).split('/')) if (dropped(unescape(seg))) return true;
+  }
+  for (const k of Object.keys(node)) if (refsIntoDropped(node[k], seen)) return true;
+  return false;
+}
+
+// keepTitle: the node is a branch of anyOf or oneOf, whose title names the
+// branch in the collapsed error (params.closestName).
+function stripSchema(node, keepTitle) {
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) return node;
+  const out = {};
+  for (const k of Object.keys(node)) {
+    if (dropped(k) && !(keepTitle === true && k === 'title')) continue;
+    const v = node[k];
+    if (SINGLE.has(k)) {
+      setOwn(out, k, Array.isArray(v) ? v.map((x) => stripSchema(x, false)) : stripSchema(v, false));
+    } else if (MAPS.has(k) && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      const m = {};
+      for (const name of Object.keys(v)) setOwn(m, name, stripSchema(v[name], false));
+      setOwn(out, k, m);
+    } else if (LISTS.has(k) && Array.isArray(v)) {
+      const branches = k === 'anyOf' || k === 'oneOf';
+      setOwn(out, k, v.map((x) => stripSchema(x, branches)));
+    } else if (k === 'dependencies' && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      const m = {};
+      for (const name of Object.keys(v)) setOwn(m, name, Array.isArray(v[name]) ? v[name] : stripSchema(v[name], false));
+      setOwn(out, k, m);
+    } else if (k === 'propertyDependencies' && v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      const m = {};
+      for (const name of Object.keys(v)) {
+        const inner = v[name];
+        if (inner === null || typeof inner !== 'object' || Array.isArray(inner)) { setOwn(m, name, inner); continue; }
+        const mi = {};
+        for (const val of Object.keys(inner)) setOwn(mi, val, stripSchema(inner[val], false));
+        setOwn(m, name, mi);
+      }
+      setOwn(out, k, m);
+    } else {
+      setOwn(out, k, v);
+    }
+  }
+  return out;
+}
+
+// A compact or schema module strips its schema three times on the way out
+// (the reference check, the module, the flat-index check): once per schema
+// object. A validator's schema object does not change after it compiles.
+const _stripped = new WeakMap();
+function stripAnnotations(schema) {
+  if (schema === null || typeof schema !== 'object') return schema;
+  const hit = _stripped.get(schema);
+  if (hit !== undefined) return hit;
+  const out = refsIntoDropped(schema, new Set()) ? schema : stripSchema(schema, false);
+  _stripped.set(schema, out);
+  return out;
+}
+
+module.exports = { stripAnnotations };

package/lib/tools.mjs

@@ -0,0 +1,21 @@
+// The package's tools as ES modules, one import each, for the entries a
+// bundler reads (index.browser.mjs, index.edge.mjs): an application that
+// imports only Validator leaves TypeScript generation, the renderers, the
+// output format, the retry message and the schema description out of its
+// bundle. Through index.js they load on first call instead, which a bundler
+// cannot see, so it kept all of them.
+import tsGen from './ts-gen.js';
+import renderPrettyMod from './render-pretty.js';
+import renderCompactMod from './render-compact.js';
+import outputFormat from './output-format.js';
+import retryMessage from './retry-message.js';
+import describe from './describe-schema.js';
+import renderJsonMod from './render-json.js';
+
+export function toTypeScript (...a) { return tsGen.toTypeScript(...a); }
+export function renderPretty (...a) { return renderPrettyMod.renderPretty(...a); }
+export function renderCompact (...a) { return renderCompactMod.renderCompact(...a); }
+export function toOutput (...a) { return outputFormat.toOutput(...a); }
+export function toRetryMessage (...a) { return retryMessage.toRetryMessage(...a); }
+export function describeSchema (...a) { return describe.describeSchema(...a); }
+export function renderJSON (...a) { return renderJsonMod.renderJSON(...a); }

package/lib/validator-core.js

@@ -25,6 +25,14 @@ function _registerCodegen(engine) {
   _codegen = engine;
   ({ compileToJS, compileToJSCodegen, compileToJSCodegenWithErrors, compileToJSCombined } = engine.jsCompiler);
 }
+// The ahead-of-time loaders without the code generator: the edge entry
+// (index.edge.js) registers lib/aot.browser.js here, so modules written by
+// `ata build` or Validator.bundle() load where generated code cannot run.
+// The emitters stay out, as they do in a browser bundle of the full package.
+let _aotLoader = null;
+function _registerAot(load) {
+  _aotLoader = load;
+}
 const { draftCode, normalizeDraft2019, normalizeDraft7, normalizeNullable, normalizeExclusiveBounds, stripFormatAssertions } = require("./draft7");
 const { enabledKeywords, stripDisabledKeywords } = require("./vocabularies");
 const { needsNormalization } = require("./schema-scan");
@@ -856,6 +864,9 @@ class Validator {
     if (this._initialized) return;
     this._ensureVocabularies();
     this._initialized = true;
+    // Errors behind a reference into a registered document are ordered as
+    // they would be inline: the ordering follows the reference there.
+    if (this._schemaMap && this._schemaMap.size > 0) require('./schema-order').registerDocuments(this._schemaObj, this._schemaMap);
 
     const schemaObj = this._schemaObj;
     const options = this._options;
@@ -1599,7 +1610,7 @@ class Validator {
   static fromStandalone(mod, schema, opts) {
     // It loads what Validator.bundleStandalone() writes, and compiles an error
     // function when the module carries none, so it goes with those methods.
-    if (_codegen === null) throw new TypeError('Validator.fromStandalone is not part of ata-validator/lite, like the bundle methods it loads for. Import it from ata-validator, or import a module from `ata build` directly.');
+    if (_codegen === null && _aotLoader === null) throw new TypeError('Validator.fromStandalone is not part of ata-validator/lite, like the bundle methods it loads for. Import it from ata-validator, or import a module from `ata build` directly.');
     const options = opts || {};
     const schemaObj = typeof schema === "string" ? JSON.parse(schema) : schema;
 
@@ -1635,7 +1646,9 @@ class Validator {
     });
     if (mod.errFn) {
       errFn = (d) => mod.errFn(d, true);
-    } else {
+    } else if (compileToJSCodegenWithErrors !== undefined) {
+      // Without the code generator (the edge entry) a module that carries no
+      // error function reports the stub above.
       const jsErrFn = compileToJSCodegenWithErrors(schemaObj);
       if (jsErrFn) {
         try {
@@ -1783,8 +1796,9 @@ function version() {
 // generated module shapes; browser bundles get `lib/aot.browser.js` (a stub
 // that throws) via the package.json `browser` field.
 function _aot() {
-  if (_codegen === null) throw new TypeError('The ahead-of-time bundle methods are not part of ata-validator/lite. Import them from ata-validator.');
-  return _codegen.aot();
+  if (_codegen !== null) return _codegen.aot();
+  if (_aotLoader !== null) return _aotLoader();
+  throw new TypeError('The ahead-of-time bundle methods are not part of ata-validator/lite. Import them from ata-validator.');
 }
 Validator.bundle = function (schemas, opts) {
   return _aot().bundle(Validator, schemas, opts);
@@ -2195,7 +2209,7 @@ function _buildParse(self) {
   // isValidObject, which runs them, and a property they check with instanceof
   // is carried over as it is (see clone-emit).
   const extended = self._verdictTail !== null || self._validateTail !== null;
-  if (_codegen === null) return decline('ata-validator/lite has no code generator to build the copy with', 'Use parse() from ata-validator, or validate(); a valid result carries the input as it is.');
+  if (_codegen === null) return decline('this entry has no code generator to build the copy with', 'Use validate(); a valid result carries the input as it is.');
   return _codegen.buildParse(self, decline, extended);
 }
 
@@ -2369,5 +2383,6 @@ module.exports = {
 // How an entry registers the code generator. Not enumerable, so the exported
 // surface of `require('ata-validator')` is what it was.
 Object.defineProperty(module.exports, '_registerCodegen', { value: _registerCodegen, 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 });

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.49.0",
+  "version": "1.51.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",
@@ -8,6 +8,16 @@
   "types": "index.d.ts",
   "exports": {
     ".": {
+      "workerd": {
+        "types": "./index.d.ts",
+        "import": "./index.edge.mjs",
+        "require": "./index.edge.js"
+      },
+      "edge-light": {
+        "types": "./index.d.ts",
+        "import": "./index.edge.mjs",
+        "require": "./index.edge.js"
+      },
       "types": "./index.d.ts",
       "browser": {
         "import": "./index.browser.mjs",
@@ -54,6 +64,11 @@
       "import": "./lite.mjs",
       "require": "./lite.js"
     },
+    "./error-runtime": {
+      "types": "./error-runtime.d.ts",
+      "import": "./error-runtime.mjs",
+      "require": "./error-runtime.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -123,6 +138,8 @@
     "index.mjs",
     "index.node.mjs",
     "index.browser.mjs",
+    "index.edge.js",
+    "index.edge.mjs",
     "index.d.ts",
     "aot.js",
     "aot.mjs",
@@ -147,18 +164,21 @@
     "lite.js",
     "lite.mjs",
     "lite.d.ts",
+    "error-runtime.js",
+    "error-runtime.mjs",
+    "error-runtime.d.ts",
     "bin/",
     "README.md",
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.49.0",
-    "@ata-validator/native-darwin-x64": "1.49.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.49.0",
-    "@ata-validator/native-linux-arm64-musl": "1.49.0",
-    "@ata-validator/native-linux-x64-gnu": "1.49.0",
-    "@ata-validator/native-linux-x64-musl": "1.49.0",
-    "@ata-validator/native-win32-x64": "1.49.0"
+    "@ata-validator/native-darwin-arm64": "1.51.0",
+    "@ata-validator/native-darwin-x64": "1.51.0",
+    "@ata-validator/native-linux-arm64-gnu": "1.51.0",
+    "@ata-validator/native-linux-arm64-musl": "1.51.0",
+    "@ata-validator/native-linux-x64-gnu": "1.51.0",
+    "@ata-validator/native-linux-x64-musl": "1.51.0",
+    "@ata-validator/native-win32-x64": "1.51.0"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"