ata-validator 1.28.0 → 1.30.0

package/README.md

@@ -703,6 +703,9 @@ npm run test:suite
 
 ## Project
 
+- [CHANGELOG.md](CHANGELOG.md) records every release. It is kept in the
+  repository and not shipped in the npm package, where its history had grown to
+  about 13% of the install.
 - [CONTRIBUTING.md](CONTRIBUTING.md) explains how to build the project and what a
   pull request needs before it can be merged.
 - [GOVERNANCE.md](GOVERNANCE.md) says who decides what, which changes the project

package/build.d.ts

@@ -144,8 +144,10 @@ export function bundleCompact(schemas: unknown[], options?: BundleStandaloneOpti
  * Stable content hash of a schema, 16 hex characters, over a canonical JSON
  * form (keys sorted at every level). Every module from
  * {@link toStandaloneModule} exports its own `schemaHash`; comparing that
- * against `schemaHash(currentSchema)` tells a build the module is stale.
- * An integrity aid, not a security boundary.
+ * against `schemaHash(currentSchema)` tells a build the schema has changed.
+ * It does not tell the build that ata has changed, since an upgrade leaves
+ * the hash matching, so compare the module's `ataVersion` against the
+ * installed version as well. An integrity aid, not a security boundary.
  */
 export function schemaHash(schema: unknown): string;
 

package/index.js

@@ -462,11 +462,18 @@ const { rankFor: schemaOrderRank, ordinalFor: schemaOrdinal } = require('./lib/s
 // that carry only message and path, such as the Standard Schema bridge.
 // Prototype accessors, not per-instance ones: see LazyRejection.
 class RichRejection {
-  constructor(result, data, positions, self, root, enrich) {
+  // `rawInput` is the JSON text validateJSON was given, or null for validate(data).
+  // The position map it implies is built in the `errors` getter, not here: it is
+  // a full walk of the document, it is only ever read through an error's
+  // dataFrame, and building it on every rejection cost a caller that reads
+  // `.valid` about 460 microseconds on a 50 KB document. Holding the text rather
+  // than reading `self._lastRawInput` later also keeps the result independent of
+  // what the instance does after this call returns.
+  constructor(result, data, rawInput, self, root, enrich) {
     this.valid = false;
     this._result = result;
     this._data = data;
-    this._positions = positions;
+    this._rawInput = rawInput;
     this._self = self;
     this._root = root;
     this._enrich = enrich;
@@ -490,11 +497,17 @@ Object.defineProperty(RichRejection.prototype, 'errors', {
       const enrich = this._enrich;
       let raw = this._result.errors || [];
       if (raw.length > 1) raw = sortErrorsBySchemaOrder(this._root, raw);
+      // The position map, resolved now that an error is actually being read.
+      let positions = null;
+      if (enrich && raw.length && this._rawInput != null) {
+        positions = self._pos().targeted(this._rawInput, wantedPointersFor(raw));
+        if (positions) self._posCache.reset();
+      }
       // One options object for the whole list, not one per error.
       const opts = enrich && raw.length
         ? {
             data: this._data,
-            positions: this._positions,
+            positions,
             schemaPositions: self._schemaPositions,
             schemaFile: self._source ? self._source.path : undefined,
           }
@@ -518,6 +531,123 @@ Object.defineProperty(RichRejection.prototype, 'errors', {
   },
 });
 
+// The rejection validateJSON returns. Everything the text path adds over
+// validate(data), the value tree enrichment needs, the position map, the
+// diagnostic payload, happens on first access to `.errors`. Reading `.valid`
+// touches none of it. The JSON text is held here rather than read back off the
+// validator, so the result does not depend on what the instance does next.
+class LazyJsonRejection {
+  constructor(result, jsonStr, self, enrich) {
+    this.valid = false;
+    this._result = result;
+    this._jsonStr = jsonStr;
+    this._self = self;
+    this._enrich = enrich;
+    this._cached = null;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+}
+Object.defineProperty(LazyJsonRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._cached !== null) return this._cached;
+    const self = this._self;
+    const enrich = this._enrich;
+    const jsonStr = this._jsonStr;
+    // Reading the inner errors realizes the inner lazy layer, if there was one.
+    const raw = this._result.errors || [];
+    if (!raw.length) { this._cached = raw; return raw; }
+
+    // The enrich pass plucks `received` from the value tree and the suggestion
+    // engine (required-typo, format hints, coercion nudges) walks it too.
+    let parsedData;
+    try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
+
+    // Errors the inner path already enriched carry a docUrl: only enrich() sets
+    // one. `code` is not a safe signal, because branch-collapse attaches codes
+    // to raw errors, and detecting on it left every collapsed oneOf/anyOf error
+    // unenriched on the text path.
+    if (!raw[0] || !raw[0].docUrl) {
+      const positions = self._pos().targeted(jsonStr, wantedPointersFor(raw));
+      // Declaration order, as validate() applies it; the text path used to
+      // enrich in emission order.
+      const ordered = raw.length > 1 ? sortErrorsBySchemaOrder(self._schemaObj, raw) : raw;
+      const enrichOpts = {
+        data: parsedData,
+        positions,
+        schemaPositions: self._schemaPositions,
+        schemaFile: self._source ? self._source.path : undefined,
+      };
+      const enriched = ordered.map((e) => enrich(e, enrichOpts));
+      if (enriched.length > 1) attachRelated(enriched);
+      attachDiagnosticSource(enriched, {
+        data: parsedData,
+        text: jsonStr,
+        positions,
+        schema: self._schemaObj,
+        mutatesInput: self._mutatesInput === true,
+      });
+      if (positions) self._posCache.reset();
+      this._cached = enriched;
+      return enriched;
+    }
+
+    // Already enriched, so the frames are usually attached too. Only a gap in
+    // them is worth another walk of the document: resolving the map to discover
+    // there was nothing to fill cost a second full walk on every rejection.
+    if (raw.some((e) => e && !e.dataFrame)) {
+      const positions = self._pos().targeted(jsonStr, wantedPointersFor(raw.filter((e) => e && !e.dataFrame)));
+      if (positions) {
+        for (const e of raw) {
+          if (e && !e.dataFrame) {
+            const path = e.path != null ? e.path : (e.instancePath || '');
+            const p = positions[path];
+            if (p) e.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
+          }
+        }
+        self._posCache.reset();
+      }
+    }
+    if (raw.length > 1) attachRelated(raw);
+    attachDiagnosticSource(raw, {
+      data: parsedData,
+      text: jsonStr,
+      schema: self._schemaObj,
+      mutatesInput: self._mutatesInput === true,
+    });
+    this._cached = raw;
+    return raw;
+  },
+});
+
+// The pointers a set of errors will ask the position map about. lib/enrich-error
+// looks up the error's own path, and for an additional or unevaluated property
+// the child pointer named in `params`, unescaped, which is the form it asks for.
+// The escaped form goes in too: including a pointer that is never read costs
+// nothing, and the cache answers anything outside this set from the full map
+// rather than reporting no position.
+function wantedPointersFor (errors) {
+  const wanted = new Set();
+  for (const e of errors) {
+    if (!e) continue;
+    const path = e.path != null ? e.path : (e.instancePath || '');
+    wanted.add(path);
+    if (e.instancePath != null && e.instancePath !== path) wanted.add(e.instancePath);
+    const params = e.params;
+    const named = params && (params.additionalProperty || params.unevaluatedProperty);
+    if (typeof named === 'string') {
+      wanted.add(path + '/' + named);
+      if (named.indexOf('~') !== -1 || named.indexOf('/') !== -1) {
+        wanted.add(path + '/' + named.replace(/~/g, '~0').replace(/\//g, '~1'));
+      }
+    }
+  }
+  return wanted;
+}
+
 // A raw error without the `_o` ordering key, for the legacy error shape.
 function stripOrdinal(e) {
   if (e === null || typeof e !== 'object' || e._o === undefined) return e;
@@ -1345,10 +1475,32 @@ class Validator {
         // The factory bakes the error function in as an argument and never
         // calls it for a document that passes, so a resolver here costs the
         // accepted path nothing and keeps the compile off the first call.
-        const hybridFn = jsFn._hybridFactory(VALID_RESULT, errPreferCombined);
+        // Until the first rejection this is the hybrid: the verdict function,
+        // with the error resolver baked in and never called for a document that
+        // passes. That keeps the combined function's compile off the first call,
+        // which is two thirds of what a first call costs.
+        //
+        // From the first rejection on, the combined function answers directly.
+        // It decides and collects in one pass, so the verdict pass in front of it
+        // was validating the document a second time: 134.1 microseconds against
+        // its 45.3 on a 1000-user array. Swapping rather than starting there keeps
+        // the lazy compile, and swapping at all is only free because the combined
+        // function now costs what the verdict function costs on accepted
+        // documents (1.02x on that array, 0.99x on a small body) since
+        // additionalProperties stopped materialising its key array. The
+        // indirection this needs measured inside the noise at both sizes.
+        let impl = null;
+        const onReject = (data) => {
+          const combined = combinedIfSafe();
+          if (combined) { impl = combined; return combined(data); }
+          return errOnly(data);
+        };
+        const hybridFn = jsFn._hybridFactory(VALID_RESULT, onReject);
+        impl = hybridFn;
+        const run = (data) => impl(data);
         this.validate = preprocess
-          ? (data) => { preprocess(data); return hybridFn(data); }
-          : hybridFn;
+          ? (data) => { preprocess(data); return run(data); }
+          : run;
       } else {
         // No hybrid factory, so the assembly needs the function itself rather
         // than a reference it can call later: build it now.
@@ -1425,7 +1577,11 @@ class Validator {
         : jsonValidateInner;
       this.validateJSON = useSimdjsonForLarge && native && !preprocess
         ? (jsonStr) => {
-            if (jsonStr.length >= SIMDJSON_THRESHOLD) {
+            // `_skipNativeFast` is set by the scanner short-circuit below when it
+            // has already decided the document is invalid. The encode and the
+            // native call would run only to return false, and the error path
+            // underneath does not need them.
+            if (jsonStr.length >= SIMDJSON_THRESHOLD && this._skipNativeFast !== true) {
               this._ensureNative();
               const buf = Buffer.from(jsonStr);
               if (native.rawFastValidate(this._fastSlot, buf))
@@ -1681,15 +1837,15 @@ class Validator {
         // abortEarly returns the shared ATA9000 stub; preserve it as-is so the
         // perf fast path stays allocation-free and the documented code stays stable.
         if (result && result.valid === false && result !== ABORT_EARLY_RESULT) {
-          // Positions come from the raw input when validateJSON set one;
-          // resolved eagerly since the cache is reset per call.
-          const positions = (enrich && self._lastRawInput != null) ? self._pos().get(self._lastRawInput) : null;
-          if (positions) self._posCache.reset();
+          // The raw input travels with the rejection when validateJSON set one.
+          // The map it implies is built on first access to `.errors`, so a
+          // caller reading only `.valid` does not pay for a document walk.
+          const rawInput = enrich ? self._lastRawInput : null;
           // One instance of a class with prototype accessors. An object
           // literal with a getter here cost a closure plus an accessor
           // definition on every rejection, several hundred nanoseconds
           // before any error was read.
-          return new RichRejection(result, data, positions, self, root, enrich);
+          return new RichRejection(result, data, rawInput, self, root, enrich);
         }
         return result;
       };
@@ -1700,74 +1856,23 @@ class Validator {
       if (this._richErrors && this.validateJSON) {
         const innerJson = this.validateJSON;
         this.validateJSON = (jsonStr) => {
+          // The inner path reads _lastRawInput to hand the raw text to the
+          // rejection it builds. Cleared as soon as it returns: the rejection
+          // carries the text itself, so nothing outlives the call.
           this._lastRawInput = jsonStr;
           let result;
           try {
             result = innerJson(jsonStr);
           } finally {
-            // Don't clear here; the enrich step below needs the cache. We
-            // clear after enrich, or in the early-return path.
+            this._lastRawInput = null;
           }
-          if (result && !result.valid && result.errors && result.errors.length) {
-            // If errors came from the inner path that already ran through the
-            // wrapped this.validate (codegen jsonValidateFn -> validate path),
-            // they may already be enriched. Detect by presence of `docUrl`:
-            // only enrich() sets it. `code` is not a safe signal because
-            // branch-collapse attaches codes to raw errors, and detecting on
-            // it left every collapsed oneOf/anyOf error unenriched on the
-            // text path.
-            const first = result.errors[0];
-            // Re-parse the input once so the enrich pass can pluck `received`
-            // and feed the suggestion engine (required-typo, format hints,
-            // coercion nudges all need the live value tree), and so the
-            // diagnostic payload carries the data on both paths below.
-            let parsedData;
-            try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
-            if (!first || !first.docUrl) {
-              const positions = (this._lastRawInput != null) ? this._pos().get(this._lastRawInput) : null;
-              // Declaration order, as validate() applies it; the text path
-              // used to enrich in emission order.
-              const ordered = result.errors.length > 1 ? sortErrorsBySchemaOrder(this._schemaObj, result.errors) : result.errors;
-              const enrichOpts = {
-                data: parsedData,
-                positions,
-                schemaPositions: this._schemaPositions,
-                schemaFile: this._source ? this._source.path : undefined,
-              };
-              const enriched = ordered.map((e) => enrich(e, enrichOpts));
-              if (enriched.length > 1) attachRelated(enriched);
-              attachDiagnosticSource(enriched, {
-                data: parsedData,
-                text: jsonStr,
-                positions,
-                schema: this._schemaObj,
-                mutatesInput: this._mutatesInput === true,
-              });
-              if (positions) this._posCache.reset();
-              this._lastRawInput = null;
-              return { valid: false, errors: enriched };
-            }
-            // Already-enriched path: still attach dataFrame if missing.
-            const positions = (this._lastRawInput != null) ? this._pos().get(this._lastRawInput) : null;
-            if (positions) {
-              for (const e of result.errors) {
-                if (e && !e.dataFrame) {
-                  const path = e.path != null ? e.path : (e.instancePath || '');
-                  const p = positions[path];
-                  if (p) e.dataFrame = { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text };
-                }
-              }
-              this._posCache.reset();
-            }
-            if (result.errors.length > 1) attachRelated(result.errors);
-            attachDiagnosticSource(result.errors, {
-              data: parsedData,
-              text: jsonStr,
-              schema: this._schemaObj,
-              mutatesInput: this._mutatesInput === true,
-            });
+          // Every diagnostic the text path adds is deferred. Deciding here
+          // whether there is anything to add would mean reading `result.errors`,
+          // and on the codegen path that realizes the inner lazy layer, which is
+          // the document walk this exists to avoid.
+          if (result && result.valid === false) {
+            return new LazyJsonRejection(result, jsonStr, this, enrich);
           }
-          this._lastRawInput = null;
           return result;
         };
       }
@@ -1925,8 +2030,23 @@ class Validator {
               };
           return self.isValidJSON(jsonStr);
         };
-        if (options.abortEarly) {
+        // validateJSON gets the same short-circuit isValidJSON has. The verdict is
+        // a property of the text, and the scanner reads the text once and
+        // allocates nothing; above the simdjson threshold the path underneath
+        // encoded the whole document to a Buffer and called the native validator
+        // instead, which measured 340 microseconds against the scanner's 191 on a
+        // 149 KB config, the same against the published addon as against a local
+        // build.
+        //
+        // An accepted document stops at the scanner. A rejected one still has to
+        // produce errors, so it goes on to the path below, which is the
+        // rich-errors wrapper and everything under it; the flag only tells that
+        // path to skip an encode and a native call that would return false. Doing
+        // it the other way, returning errors from the inner function directly,
+        // would hand back errors that never passed through enrichment.
+        {
           const validateByParsing = this.validateJSON;
+          const abortEarly = !!options.abortEarly;
           this.validateJSON = (jsonStr) => {
             const scan = self._ensureScanner();
             if (scan === undefined) return validateByParsing(jsonStr);
@@ -1935,7 +2055,15 @@ class Validator {
               if (typeof text === 'string') {
                 const r = scan(text);
                 if (r === 1) return VALID_RESULT;
-                if (r === 0) return ABORT_EARLY_RESULT;
+                if (r === 0) {
+                  if (abortEarly) return ABORT_EARLY_RESULT;
+                  self._skipNativeFast = true;
+                  try {
+                    return validateByParsing(text);
+                  } finally {
+                    self._skipNativeFast = false;
+                  }
+                }
               }
               return validateByParsing(text);
             };

package/lib/aot-impl.js

@@ -14,8 +14,9 @@
 //   loadBundle(Validator, mods, schemas, opts)
 
 const { compileToJSCodegenWithErrors, compileToJSCodegen, unevalContributions } = require('./js-compiler');
-const { buildDataPositionMap } = require('./data-positions');
+const { buildTargetedPositionMap } = require('./data-positions');
 const { schemaHash } = require('./schema-hash');
+const ATA_VERSION = require('./version');
 const SAFE_REGEX_SOURCE = require('./safe-regex-source');
 
 // Embedded verbatim in standalone modules so the output file has no runtime
@@ -119,7 +120,7 @@ function toStandalone(validator) {
   const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
 
   const closureSrc = closureDeclLines(jsFn).join('\n');
-  return `// Auto-generated by ata-validator — do not edit
+  return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit
 'use strict';
 ${_CP_LEN_SOURCE}
 ${safeRePrelude(jsFn, jsErrFn)}${preambleSrc}
@@ -594,10 +595,15 @@ function toStandaloneModule(validator, opts) {
   // dataFrame (byte offset, line, col, source line) to every error by
   // walking the original text once. Off by default for the same reason as
   // parse(): it costs bytes in every emitted module. Ask for it with
-  // { positions: true }. The walker is the runtime's buildDataPositionMap,
+  // { positions: true }. The walker is the runtime's buildTargetedPositionMap,
   // embedded verbatim via toString so the two cannot drift; that is why the
-  // function in lib/data-positions.js must stay self-contained.
-  const positionsCore = !(opts && opts.positions) ? '' : `const _ataPosMap = ${buildDataPositionMap.toString()};
+  // function in lib/data-positions.js must stay self-contained. It is given the
+  // pointers the errors name, which is the only thing this module looks up, so a
+  // subtree that cannot hold one is scanned to its end and never walked: framing
+  // an error went from 8.02x a JSON.parse of the document to 1.72x, and 3.11x in
+  // the worst case of a pointer at the very end. It is also 125 characters
+  // smaller than the full-map builder it replaces.
+  const positionsCore = !(opts && opts.positions) ? '' : `const _ataPosMap = ${buildTargetedPositionMap.toString()};
 function _ataFrame(p) { return { byteOffset: p.byteOffset, length: p.length, line: p.line, col: p.col, text: p.text }; }
 function validateJSON(text) {
   const s = String(text);
@@ -605,13 +611,15 @@ function validateJSON(text) {
   try { data = JSON.parse(s); } catch (e) {
     const nl = s.indexOf(String.fromCharCode(10));
     let frame = { byteOffset: 0, length: s.length, line: 1, col: 1, text: nl === -1 ? s : s.slice(0, nl) };
-    try { const m = _ataPosMap(s); if (m['']) frame = _ataFrame(m['']); } catch (_) {}
+    try { const m = _ataPosMap(s, new Set([''])); if (m['']) frame = _ataFrame(m['']); } catch (_) {}
     return { valid: false, errors: [{ code: 'ATA9001', message: 'invalid JSON document', keyword: '__parse__', path: '', instancePath: '', dataFrame: frame }] };
   }
   const r = validate(data);
   if (r.valid || !r.errors || !r.errors.length) return r;
   let map;
-  try { map = _ataPosMap(s); } catch (_) { return r; }
+  const _want = new Set();
+  for (const e of r.errors) _want.add(e.instancePath != null ? e.instancePath : (e.path || ''));
+  try { map = _ataPosMap(s, _want); } catch (_) { return r; }
   const errors = r.errors.map((e) => {
     const ptr = e.instancePath != null ? e.instancePath : (e.path || '');
     const p = map[ptr];
@@ -627,10 +635,15 @@ function validateJSON(text) {
   // can compare it against schemaHash(currentSchema) and know the module is
   // stale without embedding its own fingerprint.
   const hashSrc = schemaHash(validator._rawSchema !== undefined ? validator._rawSchema : validator._schemaObj);
-  const hashDecl = `const schemaHash = ${JSON.stringify(hashSrc)};\n`;
+  // The schema hash answers "is this module built from a different schema" and
+  // nothing else. Upgrading ata and not re-running the generate step leaves the
+  // hash matching, so the stale module reads as current. The module cannot ask
+  // the installed ata itself, since it imports nothing, so it carries the
+  // version that wrote it and a build compares that too.
+  const hashDecl = `const schemaHash = ${JSON.stringify(hashSrc)};\nconst ataVersion = ${JSON.stringify(ATA_VERSION)};\n`;
 
   let names = fmt.exportsSetFormats ? baseNames + ', setFormats' : baseNames;
-  names += ', schemaHash';
+  names += ', schemaHash, ataVersion';
   if (positionsCore) names += ', validateJSON';
   const parseAlias = cloneExpr ? ', _ataParse as parse' : '';
   const parseProp = cloneExpr ? ', parse: _ataParse' : '';
@@ -644,8 +657,9 @@ function validateJSON(text) {
   if (opts && opts.parse && !cloneExpr) {
     degradedNote += '// NOTE: parse() was requested but could not be generated for this schema;\n// the module has no parse export. Validate and strip with the runtime Validator.\n';
   }
-  return `// Auto-generated by ata-validator — do not edit.
+  return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit.
 // Schema is embedded; runtime has zero dependency on ata-validator.
+// Re-run the build after upgrading ata: the version above is what wrote this.
 ${degradedNote}'use strict';
 ${_CP_LEN_SOURCE}
 ${safeRePrelude(jsFn, jsErrFn)}${schemaSourceConst}const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
@@ -786,10 +800,10 @@ function bundleStandalone(Validator, schemas, opts) {
     : '';
   if (format === 'esm') {
     const extra = bundleInjects ? 'export { validators, setFormats };' : 'export { validators };';
-    return `// Auto-generated by ata-validator — do not edit\n${safeEmbed}${registry}const R=${R};\nconst validators=${arr};\nexport default validators;\n${extra}\n`;
+    return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit\n${safeEmbed}${registry}const R=${R};\nconst validators=${arr};\nexport default validators;\n${extra}\n`;
   }
   const attach = bundleInjects ? 'module.exports.setFormats=setFormats;\n' : '';
-  return `'use strict';\n${safeEmbed}${registry}var R=${R};\nmodule.exports=[${fns.join(',')}];\n${attach}`;
+  return `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit\n'use strict';\n${safeEmbed}${registry}var R=${R};\nmodule.exports=[${fns.join(',')}];\n${attach}`;
 }
 
 // Compact bundle: deduplicated code. Shared template functions + per-schema params.
@@ -898,8 +912,8 @@ function bundleCompact(Validator, schemas, opts) {
   // Generate compact bundle
   const isEsm = format === 'esm';
   let out = isEsm
-    ? '// Auto-generated by ata-validator — do not edit\n'
-    : "'use strict';\n";
+    ? `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit\n`
+    : `// Auto-generated by ata-validator ${ATA_VERSION}, do not edit\n'use strict';\n`;
   if (bundleUsesSafeRe) out += getSafeRegexEmbed() + '\n';
   if (sharedDecls.length) out += sharedDecls.join('\n') + '\n';
   const declKW = isEsm ? 'const' : 'var';

package/lib/data-position-cache.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { buildDataPositionMap } = require('./data-positions');
+const { buildDataPositionMap, buildTargetedPositionMap } = require('./data-positions');
 
 /**
  * Memoize the position map for the duration of a single validate() call.
@@ -12,7 +12,50 @@ function createCache () {
   const wm = new WeakMap();
   const sm = new Map(); // strings can't go in WeakMap; clear after each validate
   let lastInput = null;
-  return {
+  const cache = {
+    /**
+     * The entries for a known set of pointers, which is what a rejection needs:
+     * recording one per node in the document was the dominant cost of reading an
+     * error's frame.
+     *
+     * The caller derives `wanted` from the errors, and a derivation that misses a
+     * pointer must not cost a frame, so the result answers any pointer outside
+     * the set by building the full map once and reading from that. A wrong
+     * derivation is then slow rather than silently short of frames, which is the
+     * only acceptable direction for this trade: a missing caret is the failure
+     * nobody reports.
+     */
+    targeted (input, wanted) {
+      if (input == null) return null;
+      if (!wanted || wanted.size === 0) return null;
+      const already = typeof input === 'string'
+        ? sm.get(input)
+        : (Buffer.isBuffer(input) ? wm.get(input) : undefined);
+      if (already) return already;
+      let filtered;
+      try {
+        filtered = buildTargetedPositionMap(input, wanted);
+      } catch {
+        return null;
+      }
+      let full;
+      const fallback = (key) => {
+        if (wanted.has(key)) return undefined; // asked for, absent from the document
+        if (full === undefined) full = cache.get(input) || null;
+        return full ? full[key] : undefined;
+      };
+      return new Proxy(filtered, {
+        get (target, key) {
+          if (typeof key !== 'string') return target[key];
+          if (key in target) return target[key];
+          return fallback(key);
+        },
+        has (target, key) {
+          if (typeof key !== 'string') return key in target;
+          return (key in target) || fallback(key) !== undefined;
+        },
+      });
+    },
     get (input) {
       if (input == null) return null;
       if (typeof input === 'string') {
@@ -38,6 +81,7 @@ function createCache () {
       lastInput = null;
     },
   };
+  return cache;
 }
 
 module.exports = { createCache };