@jarenjs/json 0.9.2 → 0.34.2

package/src/jslt/packs/stats.js

@@ -0,0 +1,65 @@
+//@ts-check
+/**
+ * @file The statistics pack — aggregators core does not ship as
+ * operators. `sum`/`min`/`max`/`avg`/`count` are ALREADY core query
+ * operators and are NOT re-registered here; this pack adds the summaries
+ * they don't cover. The helpers are small pure functions defined in this
+ * file (their natural home — core carries no statistics module), each a
+ * deterministic function of its array argument.
+ */
+
+/** @param {number[]} xs */
+function mean(xs) {
+  if (xs.length === 0) return undefined;
+  let s = 0;
+  for (const x of xs) s += x;
+  return s / xs.length;
+}
+
+/** Sample variance (n−1). @param {number[]} xs */
+function variance(xs) {
+  if (xs.length < 2) return undefined;
+  const m = mean(xs);
+  let s = 0;
+  for (const x of xs) s += (x - m) * (x - m);
+  return s / (xs.length - 1);
+}
+
+/** @param {number[]} xs */
+function stddev(xs) {
+  const v = variance(xs);
+  return v === undefined ? undefined : Math.sqrt(v);
+}
+
+/** @param {number[]} xs */
+function median(xs) {
+  if (xs.length === 0) return undefined;
+  const sorted = xs.slice().sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/** Linear-interpolation percentile; `p` in [0, 100]. @param {number[]} xs */
+function percentile(xs, p) {
+  if (xs.length === 0) return undefined;
+  const sorted = xs.slice().sort((a, b) => a - b);
+  if (sorted.length === 1) return sorted[0];
+  const rank = (Math.max(0, Math.min(100, p)) / 100) * (sorted.length - 1);
+  const lo = Math.floor(rank);
+  const hi = Math.ceil(rank);
+  if (lo === hi) return sorted[lo];
+  return sorted[lo] + (sorted[hi] - sorted[lo]) * (rank - lo);
+}
+
+const aggNum = (signature, fn) => ({ kind: 'agg', signature, result: 'number', fn, pushable: false });
+
+export const statsPack = {
+  name: 'stats',
+  entries: {
+    $mean: aggNum(['seq<number>'], mean),
+    $median: aggNum(['seq<number>'], median),
+    $variance: aggNum(['seq<number>'], variance),
+    $stddev: aggNum(['seq<number>'], stddev),
+    $percentile: aggNum(['seq<number>', 'number'], percentile),
+  },
+};

package/src/jslt/registry.js

@@ -0,0 +1,200 @@
+//@ts-check
+/**
+ * @file The JSLT operator/aggregator registry (Ring 1): the
+ * `@jarenjs/formats` + `JarenValidator.addFormats` experience for the
+ * query/JSLT vocabulary. A caller composes packs of pure functions
+ * (`@jarenjs/core` math, finance, statistics) into a registry and gets
+ * a compiler bound to them — the operators then work in JSLT, in the
+ * query engine, and in linq-over-memory (which compiles to query
+ * documents).
+ *
+ * The mechanism is the engine's existing `options.extensions` seam (the
+ * same one the JSLT layer uses internally for `$apply`) plus
+ * `options.functions` (the `$call` registry). This file only TRANSLATES
+ * plain-data pack entries into those two shapes and holds them in an
+ * immutable-by-copy builder — so a pack never imports the operator ABI,
+ * exactly the decoupling `@jarenjs/formats` has from `@jarenjs/validate`.
+ *
+ * Entry kinds: `op` (scalar `$`-operator over scalar
+ * operands), `agg` (an operator whose declared `seq` operands are folded
+ * to arrays before the call — the generalization of core `$sum`'s fold),
+ * and `fn` (a bare `$call` function, the low-level escape). The published
+ * closed vocabulary is unchanged: without a registry a document using a
+ * pack operator fails `JQ0002` exactly as before.
+ */
+
+import { EMPTY, Seq, seqOf, firstItem } from '../query/runtime.js';
+import { CARD_OPT, CARD_MANY, isReservedQueryName } from '../query/normalize.js';
+import { JsonQueryRuntimeError } from '../query/errors.js';
+import { compileJsonQuery } from '../query/index.js';
+import { compileJsltStylesheet } from './index.js';
+
+const hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const RESULT_OPT = () => CARD_OPT;
+const RESULT_MANY = () => CARD_MANY;
+const RT_NUMBER = () => 'number';
+
+/** Normalize an operand-kind token to `'seq'` or `'scalar'`. */
+function operandKind(token) {
+  return typeof token === 'string' && token.startsWith('seq') ? 'seq' : 'scalar';
+}
+
+/**
+ * Translate one pack entry into an `options.extensions` operator entry
+ * (the shape `query/operators.js` uses). The compile gathers each `seq`
+ * operand into a JS array (`EMPTY`→`[]`, a lone value→`[value]`, a
+ * `Seq`→its items) and reads each scalar operand as a single value
+ * (`EMPTY` propagates to an empty result), calls the pure function, and
+ * wraps the result — a scalar as one item, an array under a `seq` result
+ * as a `Seq`. A throwing function becomes the coded runtime error
+ * `JQ2010`, never a crash.
+ * @param {string} name
+ * @param {{ signature: string[], result: string, fn: Function }} entry
+ */
+function toExtensionEntry(name, entry) {
+  const sig = entry.signature.map(operandKind);
+  const arity = sig.length;
+  const seqResult = operandKind(entry.result) === 'seq';
+  const fn = entry.fn;
+  const params = arity === 1
+    ? 'expr'
+    : { kinds: new Array(arity).fill('expr'), min: arity };
+  return {
+    params,
+    result: seqResult ? RESULT_MANY : RESULT_OPT,
+    resultType: RT_NUMBER,
+    compile: (gets, args, docPath) => (f) => {
+      const call = new Array(arity);
+      for (let i = 0; i < arity; i++) {
+        const v = gets[i](f);
+        if (sig[i] === 'seq') {
+          call[i] = v === EMPTY ? [] : v instanceof Seq ? v.items.slice() : [v];
+        }
+        else {
+          if (v === EMPTY) return EMPTY; // a missing scalar operand → empty result
+          call[i] = v instanceof Seq ? firstItem(v) : v;
+        }
+      }
+      let out;
+      try {
+        out = fn(...call);
+      }
+      catch (err) {
+        throw new JsonQueryRuntimeError('JQ2010',
+          `registered operator '${name}' failed: ${err?.message ?? String(err)}`,
+          docPath);
+      }
+      if (seqResult) {
+        if (!Array.isArray(out)) return out === undefined || out === null ? EMPTY : out;
+        return out.length === 0 ? EMPTY : seqOf(out);
+      }
+      return out === undefined ? EMPTY : out;
+    },
+  };
+}
+
+/** Validate a pack's shape (host programming error → TypeError). */
+function validatePack(pack) {
+  if (pack === null || typeof pack !== 'object'
+    || typeof pack.name !== 'string' || pack.name === ''
+    || pack.entries === null || typeof pack.entries !== 'object') {
+    throw new TypeError('a pack must be { name: string, entries: object }');
+  }
+  for (const [name, entry] of Object.entries(pack.entries)) {
+    if (entry === null || typeof entry !== 'object' || typeof entry.fn !== 'function') {
+      throw new TypeError(`pack '${pack.name}' entry '${name}' must carry a function 'fn'`);
+    }
+    const kind = entry.kind ?? (entry.signature?.some((s) => operandKind(s) === 'seq') ? 'agg' : 'op');
+    if (kind !== 'fn') {
+      if (name.charCodeAt(0) !== 0x24) {
+        throw new TypeError(`pack '${pack.name}' operator '${name}' must start with '$'`);
+      }
+      if (!Array.isArray(entry.signature) || entry.signature.length === 0) {
+        throw new TypeError(`pack '${pack.name}' operator '${name}' needs a non-empty signature`);
+      }
+    }
+  }
+}
+
+/**
+ * Build an immutable JSLT operator registry. `.use(pack)` returns a NEW
+ * registry with the pack merged (a value, not a mutable singleton, so
+ * the functional spirit of the compilers is preserved). A name that
+ * collides with the core vocabulary, or with an already-registered name,
+ * throws a `TypeError` at `.use()` time — a host programming error, never
+ * a `JQ` document error.
+ * @param {{ extensions: Record<string, any>, functions: Record<string, Function>,
+ *   meta: Record<string, any>, packs: string[] }} [state]
+ */
+export function createJsltRegistry(state) {
+  const base = state ?? { extensions: {}, functions: {}, meta: {}, packs: [] };
+
+  const use = (pack) => {
+    validatePack(pack);
+    const extensions = { ...base.extensions };
+    const functions = { ...base.functions };
+    const meta = { ...base.meta };
+    for (const [name, entry] of Object.entries(pack.entries)) {
+      if (hasOwn(extensions, name) || hasOwn(functions, name)) {
+        throw new TypeError(`operator '${name}' is already registered (pack '${pack.name}')`);
+      }
+      const kind = entry.kind
+        ?? (entry.signature?.some((s) => operandKind(s) === 'seq') ? 'agg' : 'op');
+      if (kind === 'fn') {
+        functions[name] = entry.fn;
+      }
+      else {
+        if (isReservedQueryName(name)) {
+          throw new TypeError(`operator '${name}' collides with the core vocabulary`);
+        }
+        extensions[name] = toExtensionEntry(name, entry);
+      }
+      meta[name] = {
+        pack: pack.name, kind,
+        signature: entry.signature ?? null, result: entry.result ?? null,
+        pushable: entry.pushable ?? false, fn: entry.fn,
+      };
+    }
+    return createJsltRegistry({
+      extensions, functions, meta, packs: [...base.packs, pack.name],
+    });
+  };
+
+  // frozen once per registry instance, so identity-based compile caching
+  // (jslt/index.js cachedTransform) hits across calls with the same
+  // registry; only a caller's OWN extensions/functions force a fresh
+  // merged object.
+  const frozenExtensions = Object.freeze({ ...base.extensions });
+  const frozenFunctions = Object.freeze({ ...base.functions });
+
+  /** The `{ extensions, functions }` a compile call needs, merged over a
+   * caller's own options — the stable frozen objects when the caller
+   * added none (the common case). */
+  const mergedOptions = (opts) => {
+    const userExt = opts?.extensions && Object.keys(opts.extensions).length > 0;
+    const userFns = opts?.functions && Object.keys(opts.functions).length > 0;
+    return {
+      ...opts,
+      extensions: userExt ? { ...opts.extensions, ...base.extensions } : frozenExtensions,
+      functions: userFns ? { ...opts.functions, ...base.functions } : frozenFunctions,
+    };
+  };
+
+  return Object.freeze({
+    use,
+    /** Every registered operator/function name (for docs, AI, errors). */
+    names: () => [...Object.keys(base.extensions), ...Object.keys(base.functions)],
+    /** The raw `{ extensions, functions }` for a manual compile call. */
+    toOptions: () => ({ extensions: { ...base.extensions }, functions: { ...base.functions } }),
+    /** The SQL-pushable subset, as `{ name -> meta }` (consumed by the db
+     * in Rings 2–3; here it is just the data). */
+    forSql: () => Object.fromEntries(
+      Object.entries(base.meta).filter(([, m]) => m.pushable !== false)),
+    /** The full registration metadata (Rings 2–3, tooling). */
+    describe: () => ({ ...base.meta }),
+    /** Compile a JSLT stylesheet bound to this registry. */
+    compile: (stylesheet, opts) => compileJsltStylesheet(stylesheet, mergedOptions(opts)),
+    /** Compile a bare query document bound to this registry (linq-over-memory). */
+    compileQuery: (document, opts) => compileJsonQuery(document, mergedOptions(opts)),
+  });
+}

package/src/jslt/stylesheet.js

@@ -4,6 +4,9 @@
 // schema, and body closures are compiled by dispatch.js.
 
 import { JsltCompileError } from './errors.js';
+import { failerFor } from '../errors.js';
+import { encodeJSONPointerSegment } from '../pointer.js';
+import { isJsonObject } from '@jarenjs/core/object';
 
 const hasOwn = Object.hasOwn;
 const ENVELOPE_KEYS = new Set(['$jslt', 'rules', 'unmatched', 'modes']);
@@ -11,40 +14,28 @@ const RULE_KEYS = new Set(['match', 'mode', 'priority', 'body']);
 const MATCH_KEYS = new Set(['path', 'schema']);
 const MODE_KEYS = new Set(['unmatched']);
 
-function isObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function escapeToken(token) {
-  if (token.indexOf('~') < 0 && token.indexOf('/') < 0)
-    return token;
-  return token.replace(/~/g, '~0').replace(/\//g, '~1');
-}
-
-function fail(code, message, docPath) {
-  throw new JsltCompileError(code, message, docPath);
-}
+const fail = failerFor(JsltCompileError);
 
 function isDisposition(value) {
   return value === 'share' || value === 'fresh' || value === 'error';
 }
 
 function normalizeModes(value, docPath) {
-  if (!isObject(value))
+  if (!isJsonObject(value))
     fail('JT0001', "'modes' must be an object", docPath);
   const modes = new Map();
   const names = Object.keys(value);
   for (let i = 0; i < names.length; i++) {
     const name = names[i];
-    const modePath = docPath + '/' + escapeToken(name);
+    const modePath = docPath + '/' + encodeJSONPointerSegment(name);
     const config = value[name];
-    if (!isObject(config))
+    if (!isJsonObject(config))
       fail('JT0001', `mode '${name}' must be an object`, modePath);
     const keys = Object.keys(config);
     for (let j = 0; j < keys.length; j++) {
       if (!MODE_KEYS.has(keys[j]))
         fail('JT0001', `unknown mode member '${keys[j]}'`,
-          modePath + '/' + escapeToken(keys[j]));
+          modePath + '/' + encodeJSONPointerSegment(keys[j]));
     }
     if (!hasOwn(config, 'unmatched'))
       fail('JT0001', `mode '${name}' requires 'unmatched'`, modePath + '/unmatched');
@@ -69,7 +60,7 @@ function normalizeMatch(value, matchPath) {
       schemaDocPath: '',
     });
   }
-  if (!isObject(value))
+  if (!isJsonObject(value))
     fail('JT0003', "'match' must be a JSONPath string or an object", matchPath);
 
   const keys = Object.keys(value);
@@ -78,7 +69,7 @@ function normalizeMatch(value, matchPath) {
   for (let i = 0; i < keys.length; i++) {
     if (!MATCH_KEYS.has(keys[i]))
       fail('JT0003', `unknown match member '${keys[i]}'`,
-        matchPath + '/' + escapeToken(keys[i]));
+        matchPath + '/' + encodeJSONPointerSegment(keys[i]));
   }
   const hasPath = hasOwn(value, 'path');
   const hasSchema = hasOwn(value, 'schema');
@@ -98,14 +89,14 @@ function normalizeMatch(value, matchPath) {
 
 function normalizeRule(value, index, rulesPath) {
   const rulePath = rulesPath + '/' + index;
-  if (!isObject(value))
+  if (!isJsonObject(value))
     fail('JT0002', 'a stylesheet rule must be an object', rulePath);
 
   const keys = Object.keys(value);
   for (let i = 0; i < keys.length; i++) {
     if (!RULE_KEYS.has(keys[i]))
       fail('JT0002', `unknown rule member '${keys[i]}'`,
-        rulePath + '/' + escapeToken(keys[i]));
+        rulePath + '/' + encodeJSONPointerSegment(keys[i]));
   }
   if (!hasOwn(value, 'body'))
     fail('JT0002', "a stylesheet rule requires 'body'", rulePath + '/body');
@@ -153,12 +144,12 @@ export function normalizeJsltStylesheet(doc) {
     sourceRules = doc;
     rulesPath = '';
   }
-  else if (isObject(doc)) {
+  else if (isJsonObject(doc)) {
     const keys = Object.keys(doc);
     for (let i = 0; i < keys.length; i++) {
       if (!ENVELOPE_KEYS.has(keys[i]))
         fail('JT0001', `unknown stylesheet member '${keys[i]}'`,
-          '/' + escapeToken(keys[i]));
+          '/' + encodeJSONPointerSegment(keys[i]));
     }
     if (!hasOwn(doc, '$jslt'))
       fail('JT0001', "the stylesheet envelope requires '$jslt'", '/$jslt');

package/src/jtlt/desugar.js

@@ -20,13 +20,12 @@
 // pair unambiguously.
 
 import { JtltCompileError } from './errors.js';
+import { failerFor } from '../errors.js';
 
 const DOLLAR = 0x24;
 const BUILTIN_PRIORITY = -1e308;
 
-function fail(code, message, docPath) {
-  throw new JtltCompileError(code, message, docPath);
-}
+const fail = failerFor(JtltCompileError);
 
 // Collect every statically declared `$apply` target mode inside a plain
 // JSON expression tree. `$apply` mode arguments are literal strings by

package/src/jtlt/errors.js

@@ -3,17 +3,15 @@
 // stable `code` and a `docPath`, an RFC 6901 JSON Pointer into the template
 // document. Wrapped JSLT/query errors are exposed through `cause`.
 
+import { CodedDocPathError } from '../errors.js';
+
 /**
  * Error thrown when a JTLT template is rejected at compile time
  * (`TL0xxx` codes).
  */
-export class JtltCompileError extends Error {
+export class JtltCompileError extends CodedDocPathError {
   constructor(code, message, docPath, cause = undefined) {
-    super(`${code}: ${message} at ${docPath}`,
-      cause === undefined ? undefined : { cause });
-    this.name = 'JtltCompileError';
-    this.code = code;
-    this.docPath = docPath;
+    super('JtltCompileError', code, message, docPath, cause);
   }
 }
 
@@ -21,13 +19,9 @@ export class JtltCompileError extends Error {
  * Error thrown when rendering with a compiled JTLT template fails
  * (`TL2xxx` codes).
  */
-export class JtltRuntimeError extends Error {
+export class JtltRuntimeError extends CodedDocPathError {
   constructor(code, message, docPath, cause = undefined) {
-    super(`${code}: ${message} at ${docPath}`,
-      cause === undefined ? undefined : { cause });
-    this.name = 'JtltRuntimeError';
-    this.code = code;
-    this.docPath = docPath;
+    super('JtltRuntimeError', code, message, docPath, cause);
   }
 }
 

package/src/jtlt/index.js

@@ -8,6 +8,7 @@
 // reimplemented.
 
 import { deepFreezeCopy } from '../query/normalize.js';
+import { createOptionVariantCache, identityOf } from '../option-variants.js';
 import {
   compileJsltStylesheet,
   JsltCompileError,
@@ -85,41 +86,23 @@ export function compileJtltStylesheet(doc, options = {}) {
   return render;
 }
 
-const TEMPLATE_CACHE = new WeakMap();
+const TEMPLATE_CACHE = createOptionVariantCache();
 
 function cachedRender(template, options) {
-  let record = TEMPLATE_CACHE.get(template);
-  if (record === undefined) {
-    record = {
-      defaultRender: null,
-      variants: null,
-    };
-    TEMPLATE_CACHE.set(template, record);
-  }
-
+  // The FULL option tuple keys the cache. `compileJtltStylesheet`
+  // forwards its options to the JSLT compiler, which also honours
+  // `memo` and `pathFunctions` — the old two-field comparison dropped
+  // both, so a one-call render with `pathFunctions` compiled without
+  // them (a live cache-poisoning bug, fixed by keying on everything).
   const compileTypeTest = typeof options?.compileTypeTest === 'function'
     ? options.compileTypeTest
     : null;
   const maxDepth = options?.maxDepth === undefined ? 1024 : options.maxDepth;
-  if (compileTypeTest === null && maxDepth === 1024) {
-    if (record.defaultRender === null)
-      record.defaultRender = compileJtltStylesheet(template);
-    return record.defaultRender;
-  }
-
-  let variants = record.variants;
-  if (variants === null) {
-    variants = [];
-    record.variants = variants;
-  }
-  for (let i = 0; i < variants.length; i++) {
-    const variant = variants[i];
-    if (variant.compileTypeTest === compileTypeTest && variant.maxDepth === maxDepth)
-      return variant.render;
-  }
-  const render = compileJtltStylesheet(template, options);
-  variants.push({ compileTypeTest, maxDepth, render });
-  return render;
+  const memo = options?.memo === true;
+  const pathFunctions = options?.pathFunctions == null ? null : options.pathFunctions;
+  const key = `${identityOf(compileTypeTest)}|${maxDepth}|${memo ? 1 : 0}|${identityOf(pathFunctions)}`;
+  return TEMPLATE_CACHE.getOrCompile(template, key,
+    () => compileJtltStylesheet(template, options));
 }
 
 /**

package/src/jtlt/template.js

@@ -6,6 +6,9 @@
 // drift apart.
 
 import { JtltCompileError } from './errors.js';
+import { failerFor } from '../errors.js';
+import { encodeJSONPointerSegment } from '../pointer.js';
+import { isJsonObject } from '@jarenjs/core/object';
 
 const hasOwn = Object.hasOwn;
 const ENVELOPE_KEYS = new Set(['$jtlt', 'output', 'rules']);
@@ -16,30 +19,18 @@ const OUTPUT_METHODS = new Set(['text', 'xml']);
 // built-in rules, which sit at -1e308 - beneath every user rule.
 export const RESERVED_PRIORITY_FLOOR = -1e307;
 
-function isObject(value) {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function escapeToken(token) {
-  if (token.indexOf('~') < 0 && token.indexOf('/') < 0)
-    return token;
-  return token.replace(/~/g, '~0').replace(/\//g, '~1');
-}
-
-function fail(code, message, docPath) {
-  throw new JtltCompileError(code, message, docPath);
-}
+const fail = failerFor(JtltCompileError);
 
 function normalizeRule(value, index, rulesPath) {
   const rulePath = rulesPath + '/' + index;
-  if (!isObject(value))
+  if (!isJsonObject(value))
     fail('TL0002', 'a template rule must be an object', rulePath);
 
   const keys = Object.keys(value);
   for (let i = 0; i < keys.length; i++) {
     if (!RULE_KEYS.has(keys[i]))
       fail('TL0002', `unknown rule member '${keys[i]}'`,
-        rulePath + '/' + escapeToken(keys[i]));
+        rulePath + '/' + encodeJSONPointerSegment(keys[i]));
   }
   if (!hasOwn(value, 'body'))
     fail('TL0002', "a template rule requires 'body'", rulePath + '/body');
@@ -56,7 +47,7 @@ function normalizeRule(value, index, rulesPath) {
         rulePath + '/priority');
   }
   const hasMatch = hasOwn(value, 'match');
-  if (hasMatch && typeof value.match !== 'string' && !isObject(value.match))
+  if (hasMatch && typeof value.match !== 'string' && !isJsonObject(value.match))
     fail('TL0002', "'match' must be a JSONPath string or an object", rulePath + '/match');
 
   return Object.freeze({
@@ -87,12 +78,12 @@ export function normalizeJtltTemplate(doc) {
     sourceRules = doc;
     rulesPath = '';
   }
-  else if (isObject(doc)) {
+  else if (isJsonObject(doc)) {
     const keys = Object.keys(doc);
     for (let i = 0; i < keys.length; i++) {
       if (!ENVELOPE_KEYS.has(keys[i]))
         fail('TL0001', `unknown template member '${keys[i]}'`,
-          '/' + escapeToken(keys[i]));
+          '/' + encodeJSONPointerSegment(keys[i]));
     }
     if (!hasOwn(doc, '$jtlt'))
       fail('TL0001', "the template envelope requires '$jtlt'", '/$jtlt');

package/src/option-variants.js

@@ -0,0 +1,54 @@
+//@ts-check
+/**
+ * @file Per-document compilation-variant caching, shared by the JSLT
+ * and JTLT one-call entry points. A document compiles differently under
+ * different options, so the cache key is the FULL option tuple — every
+ * option that changes what compiles must be part of the derived key, or
+ * a second call with different options silently reuses the first
+ * compilation (the cache-poisoning bug the JTLT cache had before the
+ * health pass). Identity-compared option values (hook functions,
+ * function-extension registries) are interned to stable per-process ids
+ * so the key is a flat string and lookup is O(1) instead of a linear
+ * scan over an unbounded variants array.
+ */
+
+import { createBoundedCache, createWeakCache } from '@jarenjs/core/cache';
+
+/** @type {WeakMap<object, number>} */
+const IDENTITY_IDS = new WeakMap();
+let nextIdentityId = 1;
+
+/**
+ * A stable per-process id for an identity-compared option value.
+ * `null`/`undefined` share id 0 ("absent").
+ * @param {any} value
+ * @returns {number}
+ */
+export function identityOf(value) {
+  if (value == null) return 0;
+  let id = IDENTITY_IDS.get(value);
+  if (id === undefined) {
+    id = nextIdentityId++;
+    IDENTITY_IDS.set(value, id);
+  }
+  return id;
+}
+
+/**
+ * A two-axis compilation cache: documents by identity (weak, entries
+ * die with the document), variants per document by derived option key
+ * (bounded LRU — the old variants array grew without bound).
+ * @param {number} [limitPerDocument] - variant bound per document
+ * @returns {{ getOrCompile: (document: object, key: string, compile: () => any) => any }}
+ */
+export function createOptionVariantCache(limitPerDocument = 16) {
+  const byDocument = createWeakCache();
+  const newVariants = () => createBoundedCache(limitPerDocument);
+  return {
+    getOrCompile(document, key, compile) {
+      const variants = /** @type {import('@jarenjs/core/cache').BoundedCache<string, any>} */ (
+        byDocument.getOrCreate(document, newVariants));
+      return variants.getOrCreate(key, compile);
+    },
+  };
+}