@jarenjs/json 0.9.2 → 0.34.2

package/schemas/jaren-query.schema.json

@@ -64,9 +64,10 @@
       "format": "json-path"
     },
     "variablePathString": {
-      "description": "A variable-rooted path: '$name' with name matching [A-Za-z_][A-Za-z0-9_]*, optionally followed by RFC 9535 segments. Only the head is pattern-checked; the full segment grammar is enforced by the compiler (JQ0004).",
+      "description": "A variable-rooted path: '$name' with name matching [A-Za-z_][A-Za-z0-9_]*, optionally followed by RFC 9535 segments. The pattern checks the head; the json-path-segments format asserts the full segment grammar where format assertion is enabled (the compiler enforces it either way, JQ0004).",
       "type": "string",
-      "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*($|[.\\[])"
+      "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*($|[.\\[])",
+      "format": "json-path-segments"
     },
     "arrayConstructor": {
       "description": "An array in expression position constructs an array; element results are concatenated per XQuery sequence flattening.",
@@ -79,6 +80,7 @@
         { "$ref": "#/$defs/mapConstructor" },
         { "$ref": "#/$defs/constPhrase" },
         { "$ref": "#/$defs/mapPhrase" },
+        { "$ref": "#/$defs/callPhrase" },
         { "$ref": "#/$defs/flworPhrase" },
         { "$ref": "#/$defs/somePhrase" },
         { "$ref": "#/$defs/everyPhrase" },
@@ -88,6 +90,8 @@
         { "$ref": "#/$defs/nonEmptyVariadicOperatorPhrase" },
         { "$ref": "#/$defs/conditionalArityOperatorPhrase" },
         { "$ref": "#/$defs/stringJoinPhrase" },
+        { "$ref": "#/$defs/geohashPhrase" },
+        { "$ref": "#/$defs/ternaryOperatorPhrase" },
         { "$ref": "#/$defs/replacePhrase" },
         { "$ref": "#/$defs/schemaOperatorPhrase" }
       ]
@@ -128,10 +132,25 @@
       "minItems": 2,
       "maxItems": 2
     },
+    "callPhrase": {
+      "description": "A registered trusted host function call: ['name', ...argument expressions]. The name must be registered at compile time (options.functions, JQ0010); sequences cross the boundary as arrays, a returned undefined is the empty sequence, a throwing function is JQ2010.",
+      "type": "object",
+      "properties": {
+        "$call": {
+          "type": "array",
+          "minItems": 1,
+          "prefixItems": [{ "type": "string", "minLength": 1 }],
+          "items": { "$ref": "#/$defs/expression" }
+        }
+      },
+      "required": ["$call"],
+      "additionalProperties": false
+    },
     "flworPhrase": {
-      "description": "FLWOR phrase. Clauses apply in the fixed semantic order $for, $let, $as, $where, $groupby, $orderby, $count, $return regardless of JSON key order (D7); interleavings are expressed by nesting phrases. $return is required, plus at least one of $for/$let.",
+      "description": "FLWOR phrase. Clauses apply in the fixed semantic order $fold, $for, $let, $as, $where, $groupby, $orderby, $count, $return regardless of JSON key order (D7); interleavings are expressed by nesting phrases. $return is required, plus at least one of $fold/$for/$let. With $fold the phrase evaluates to the final accumulator instead of the collected $return sequence.",
       "type": "object",
       "properties": {
+        "$fold": { "$ref": "#/$defs/foldBinding" },
         "$for": { "$ref": "#/$defs/forBindings" },
         "$let": { "$ref": "#/$defs/bindingMap" },
         "$as": { "$ref": "#/$defs/asClause" },
@@ -144,16 +163,25 @@
       "required": ["$return"],
       "anyOf": [
         { "required": ["$for"] },
-        { "required": ["$let"] }
+        { "required": ["$let"] },
+        { "required": ["$fold"] }
       ],
       "additionalProperties": false
     },
+    "foldBinding": {
+      "description": "The $fold accumulator: exactly one variable name mapped to the accumulator's initial value, evaluated once in the enclosing scope before the tuple stream starts. $return then names the accumulator's next value per surviving tuple.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/expression" }
+    },
     "variableName": {
       "type": "string",
       "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
     },
     "forBindings": {
-      "description": "Iteration bindings: variable name to source expression or extended {$in, $at} binding. Bindings nest left-to-right in document key order and may be correlated; key-order-hostile producers should nest phrases instead.",
+      "description": "Iteration bindings: variable name to source expression or extended $in binding. Bindings nest left-to-right in document key order and may be correlated; key-order-hostile producers should nest phrases instead.",
       "type": "object",
       "minProperties": 1,
       "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
@@ -166,13 +194,17 @@
       ]
     },
     "extendedForBinding": {
-      "description": "Extended $for binding: iterates $in and binds $at to the 0-based (D6) position variable.",
+      "description": "Extended $for binding. $in is the source; $at binds the 0-based (D6) position variable; $allowing-empty emits one tuple with the variable bound to the empty sequence (position -1) when the source yields no tuple; $window with $size, and optionally $step, iterates tumbling or sliding windows instead of items. Only $in is structurally required: the compiler rejects $size/$step without $window, and $window without $size (JQ0003).",
       "type": "object",
       "properties": {
         "$in": { "$ref": "#/$defs/expression" },
-        "$at": { "$ref": "#/$defs/variableName" }
+        "$at": { "$ref": "#/$defs/variableName" },
+        "$allowing-empty": { "type": "boolean" },
+        "$window": { "enum": ["tumbling", "sliding"] },
+        "$size": { "type": "integer", "minimum": 1 },
+        "$step": { "type": "integer", "minimum": 1 }
       },
-      "required": ["$in", "$at"],
+      "required": ["$in"],
       "additionalProperties": false
     },
     "bindingMap": {
@@ -209,12 +241,13 @@
       ]
     },
     "orderByKeySpec": {
-      "description": "Explicit order key: direction defaults to 'asc', empty-sequence placement to 'least'.",
+      "description": "Explicit order key: direction defaults to 'asc', empty-sequence placement to 'least'. A $collation names a registered pure compare function (options.collations, JQ0010) applied to string keys; the default stays code-point order.",
       "type": "object",
       "properties": {
         "$key": { "$ref": "#/$defs/expression" },
         "$dir": { "enum": ["asc", "desc"] },
-        "$empty": { "enum": ["least", "greatest"] }
+        "$empty": { "enum": ["least", "greatest"] },
+        "$collation": { "type": "string", "minLength": 1 }
       },
       "required": ["$key"],
       "additionalProperties": false
@@ -248,10 +281,15 @@
         "enum": [
           "$exists", "$empty", "$not", "$neg",
           "$count", "$sum", "$avg", "$min", "$max",
-          "$distinct", "$reverse", "$sort", "$head", "$tail",
+          "$distinct", "$reverse", "$sort", "$head", "$tail", "$entries", "$from-entries",
           "$upper", "$lower", "$string-length", "$normalize-space",
           "$string", "$number", "$boolean",
-          "$is-string", "$is-number", "$is-boolean", "$is-null", "$is-array", "$is-object"
+          "$is-string", "$is-number", "$is-boolean", "$is-null", "$is-array", "$is-object",
+          "$is-date", "$is-time", "$is-datetime", "$is-duration",
+          "$year", "$month", "$day", "$hours", "$minutes", "$seconds",
+          "$offset", "$epoch", "$datetime",
+          "$week", "$week-year", "$quarter", "$weekday",
+          "$bbox", "$area", "$length", "$centroid"
         ]
       },
       "additionalProperties": { "$ref": "#/$defs/expression" }
@@ -266,7 +304,9 @@
           "$eq", "$ne", "$lt", "$le", "$gt", "$ge",
           "$add", "$sub", "$mul", "$div", "$idiv", "$mod",
           "$contains", "$starts-with", "$ends-with", "$match", "$search",
-          "$index-of", "$range", "$get", "$default"
+          "$index-of", "$range", "$get",
+          "$start-of", "$end-of", "$date-format",
+          "$distance", "$within", "$bbox-intersects", "$default"
         ]
       },
       "additionalProperties": {
@@ -304,12 +344,12 @@
       }
     },
     "conditionalArityOperatorPhrase": {
-      "description": "Operators taking two or three operand expressions: $if [cond, then, else?], $substring [str, start, len?], $subsequence [seq, start, len?].",
+      "description": "Operators taking two or three operand expressions: $if [cond, then, else?], $substring [str, start, len?], $subsequence [seq, start, len?], $date-add / $date-sub [date, duration] or [date, amount, unit].",
       "type": "object",
       "minProperties": 1,
       "maxProperties": 1,
       "propertyNames": {
-        "enum": ["$if", "$substring", "$subsequence"]
+        "enum": ["$if", "$substring", "$subsequence", "$date-add", "$date-sub"]
       },
       "additionalProperties": {
         "type": "array",
@@ -318,6 +358,20 @@
         "maxItems": 3
       }
     },
+    "geohashPhrase": {
+      "description": "$geohash [value] or [value, precision]: a GeoJSON value as a base-32 cell string. Precision is an integer from 1 to 12 (default 9); a value that is not a bare position is represented by its centroid.",
+      "type": "object",
+      "properties": {
+        "$geohash": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/expression" },
+          "minItems": 1,
+          "maxItems": 2
+        }
+      },
+      "required": ["$geohash"],
+      "additionalProperties": false
+    },
     "stringJoinPhrase": {
       "description": "$string-join [seq, separator?]: one or two operand expressions.",
       "type": "object",
@@ -332,6 +386,19 @@
       "required": ["$string-join"],
       "additionalProperties": false
     },
+    "ternaryOperatorPhrase": {
+      "description": "Operators whose value is an array of exactly three operand expressions: $date-diff [from, to, unit].",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": { "enum": ["$date-diff"] },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/expression" },
+        "minItems": 3,
+        "maxItems": 3
+      }
+    },
     "replacePhrase": {
       "description": "$replace [input, pattern, replacement]: exactly three operand expressions (I-Regexp has no flags argument, D5).",
       "type": "object",

package/src/basic.js

@@ -199,7 +199,7 @@ export function isValidRelativeJSONPointer(str) {
 //   \.[a-zA-Z_][a-zA-Z0-9_]*| - dot notation (e.g., $.store)
 //   \.[*]| - dot wildcard (e.g., $.*)
 //   \[\s*(?:'[^']*'|"[^"]*"|\d+|\*|\?[^\]]*|\d*:\d*(?::\d*)?)\s*\] - bracket notation
-const CONST_REGEXP_JSONPATH = /^(\$|@)(?:\.\.[a-zA-Z_][a-zA-Z0-9_]*|\.\.|\.[a-zA-Z_][a-zA-Z0-9_]*|\.[*]|\[\s*(?:'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|\d+|\*|\?[^\]]*|\d*:\d*(?::\d*)?|\d+(?:\s*,\s*\d+)*|'(?:[^'\\]|\\.)*'(?:\s*,\s*'(?:[^'\\]|\\.)*')*|\"(?:[^"\\]|\\.)*\"(?:\s*,\s*\"(?:[^"\\]|\\.)*\")*)\s*\])*$/;
+const CONST_REGEXP_JSONPATH = /^(\$|@)(?:\.\.[a-zA-Z_][a-zA-Z0-9_]*|\.\.|\.[a-zA-Z_][a-zA-Z0-9_]*|\.[*]|\[\s*(?:'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|\d+|\*|\?[^\]]*|\d*:\d*(?::\d*)?|\d+(?:\s*,\s*\d+)*|'(?:[^'\\]|\\.)*'(?:\s*,\s*'(?:[^'\\]|\\.)*')*|"(?:[^"\\]|\\.)*"(?:\s*,\s*"(?:[^"\\]|\\.)*")*)\s*\])*$/;
 
 /**
  * Validates a JSONPath expression string per RFC 9535.

package/src/canonical.js

@@ -0,0 +1,170 @@
+//#region Canonical JSON (RFC 8785 / JCS)
+// JSON Canonicalization Scheme
+// https://www.rfc-editor.org/rfc/rfc8785.html
+//
+// Deterministic serialization for hashing and signing: two structurally
+// equal JSON values always produce byte-identical output, so a hash or
+// signature over the text is a hash or signature over the value.
+//
+// The package already had two stable serializers before this one, and
+// neither is JCS. Both stay as they are, because both are load-bearing
+// where they live:
+//
+//   - `stableKeyString` (query/runtime.js) is a grouping/ordering KEY.
+//     It emits `NaN` and `Infinity` by name so that NaN groups with NaN
+//     per the XQuery grouping rule - which JCS forbids outright, since
+//     neither is a JSON number.
+//   - `stableStringify` (@jarenjs/core/object) is a cache/memo
+//     fingerprint. It follows `JSON.stringify` conventions: `NaN`
+//     becomes `null`, `undefined` members are dropped.
+//
+// Silently dropping or coercing a value is exactly right for a memo key
+// and exactly wrong for a signature, so this module rejects instead:
+// every input that is not JSON data is an error, never a guess.
+
+import { encodeJSONPointerSegment } from './pointer.js';
+
+const hasOwn = Object.hasOwn;
+
+// In a Unicode-mode pattern a well-formed surrogate pair is one code
+// point, so this matches only UNPAIRED surrogates.
+const RE_LONE_SURROGATE = /\p{Surrogate}/u;
+
+/**
+ * Error thrown when a value cannot be canonicalized because it is not
+ * JSON data (RFC 8785 section 3.2.1). `dataPath` is an RFC 6901 JSON
+ * Pointer to the offending value, so a rejected document says which
+ * member was at fault rather than only that one was.
+ *
+ * Extends `TypeError`: passing a non-JSON value to a canonicalizer is a
+ * programming error, the same class `JSON.stringify` raises for a
+ * BigInt or a cycle.
+ */
+export class JsonCanonicalizeError extends TypeError {
+  constructor(message, dataPath) {
+    super(`${message} at ${dataPath === '' ? 'the document root' : dataPath}`);
+    this.name = 'JsonCanonicalizeError';
+    this.dataPath = dataPath;
+  }
+}
+
+function fail(message, dataPath) {
+  throw new JsonCanonicalizeError(message, dataPath);
+}
+
+// RFC 6901 escaping for the diagnostic pointer only.
+function appendPath(path, token) {
+  return path + '/' + encodeJSONPointerSegment(token);
+}
+
+function serializeString(value, path) {
+  if (RE_LONE_SURROGATE.test(value))
+    fail('a string with an unpaired surrogate is not valid Unicode', path);
+  // Section 3.2.2.2 is the JSON string escape discipline with the
+  // shortest possible escapes and no escaping of non-ASCII - which is
+  // precisely what ECMAScript's JSON.stringify emits for a string.
+  return JSON.stringify(value);
+}
+
+function serializeNumber(value, path) {
+  if (!Number.isFinite(value))
+    fail(`${value === value ? String(value) : 'NaN'} is not a JSON number`, path);
+  // Section 3.2.2.3 mandates ECMAScript's Number::toString, which is
+  // what String() is - including `-0` serializing as `0`.
+  return String(value);
+}
+
+function serializeValue(value, path, stack) {
+  if (value === null)
+    return 'null';
+
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      return serializeNumber(value, path);
+    case 'string':
+      return serializeString(value, path);
+    case 'object':
+      break;
+    case 'undefined':
+      return fail('undefined is not a JSON value', path);
+    case 'bigint':
+      return fail('a BigInt is not a JSON number', path);
+    default: // 'function', 'symbol'
+      return fail(`a ${typeof value} is not a JSON value`, path);
+  }
+
+  if (stack.has(value))
+    fail('a circular reference cannot be canonicalized', path);
+  stack.add(value);
+
+  let out;
+  if (Array.isArray(value)) {
+    out = '[';
+    for (let i = 0; i < value.length; i++) {
+      if (i > 0)
+        out += ',';
+      // an array hole reads as undefined, which is not a JSON value
+      out += serializeValue(value[i], path + '/' + i, stack);
+    }
+    out += ']';
+  }
+  else {
+    // A signing primitive must not guess. A class instance would walk
+    // as its own enumerable fields (a Date as `{}`, a Map as `{}`),
+    // which is a silently wrong signature rather than a loud error, so
+    // only plain objects are JSON objects here. `toJSON` is
+    // deliberately not consulted for the same reason: the value that
+    // gets signed is the value that was passed in.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype)
+      fail(`a ${value.constructor?.name ?? 'non-plain'} instance is not a JSON object`, path);
+    // Section 3.2.3: members sorted by the UTF-16 code units of their
+    // names, which is what the default string sort compares.
+    const keys = Object.keys(value).sort();
+    out = '{';
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      /* c8 ignore next 2 -- Object.keys only yields own keys */
+      if (!hasOwn(value, key))
+        continue;
+      if (i > 0)
+        out += ',';
+      out += serializeString(key, path) + ':'
+        + serializeValue(value[key], appendPath(path, key), stack);
+    }
+    out += '}';
+  }
+
+  stack.delete(value);
+  return out;
+}
+
+/**
+ * Serialize a JSON value to its canonical form (RFC 8785 / JCS): object
+ * members sorted by the UTF-16 code units of their names, numbers in
+ * the ECMAScript `Number::toString` form, strings with the shortest
+ * JSON escapes and no escaping of non-ASCII, and no insignificant
+ * whitespace. Two structurally equal values always produce identical
+ * text, which is what makes the result safe to hash or sign.
+ *
+ * Unlike `JSON.stringify`, nothing is dropped or coerced: `undefined`,
+ * a function, a symbol, a BigInt, `NaN`, `Infinity`, an unpaired
+ * surrogate, a circular reference and a class instance are all errors,
+ * because a canonicalizer that quietly rewrote its input would produce
+ * a signature over a document nobody sent.
+ *
+ * @param {any} value - The JSON value to canonicalize
+ * @returns {string} The canonical JSON text
+ * @throws {JsonCanonicalizeError} When the value is not JSON data
+ * @example
+ * canonicalizeJson({ b: 1, a: [2, 3] }); // '{"a":[2,3],"b":1}'
+ * canonicalizeJson({ 'ä': 1, 'a': 2 }); // '{"a":2,"ä":1}'
+ * canonicalizeJson(1e21); // '1e+21'
+ */
+export function canonicalizeJson(value) {
+  return serializeValue(value, '', new Set());
+}
+
+//#endregion

package/src/cow.js

@@ -0,0 +1,106 @@
+//#region copy-on-write machinery (package-internal)
+// The shared copy-on-write core of the JSON Patch engine (patch.js) and
+// the standalone write operations (write.js). Like segments.js, this
+// module is package-internal and is deliberately not listed in the
+// package exports. The value-level primitives it builds on
+// (isJsonContainer, shallowCloneJson, cloneJson) are pure JSON helpers
+// and live in @jarenjs/core/object.
+//
+// An application of writes carries a state `{ root, owned }` where
+// `owned` is the set of nodes this application created and may mutate
+// freely (`null` = in-place mode: every node is owned). The first write
+// along a path shallow-clones the spine from the root down; later writes
+// find the spine in the owned set and mutate the clones in place. The
+// input document is never touched.
+//
+// Step encoding shared by the walk/read helpers: a location is a pair of
+// parallel arrays `names`/`indexes`.
+//   - RFC 6901 form (patch.js, pointer targets): `names[i]` is the
+//     decoded token, `indexes[i]` its pre-scanned array-index form
+//     (-1 = not a valid index). One token, two forms.
+//   - Typed form (JSONPath-derived targets): a name selector stores
+//     `names[i] = name, indexes[i] = -1`; an index selector stores
+//     `names[i] = null, indexes[i] = index` (negative = from the end).
+// `readSteps` resolves either form; the callers own their walk loops so
+// each module raises its own error types.
+
+import { isJsonContainer, shallowCloneJson } from '@jarenjs/core/object';
+
+const hasOwn = Object.hasOwn;
+
+/**
+ * The mutable state of one write application. `owned` is the set of
+ * nodes this application created and may mutate freely; `null` means
+ * in-place mode (every node is owned).
+ */
+export function makeState(root, owned) {
+  return { root, owned };
+}
+
+/** Ensure the root is owned before the first write into it. */
+export function ownedRoot(state) {
+  const root = state.root;
+  const owned = state.owned;
+  if (owned === null || !isJsonContainer(root) || owned.has(root))
+    return root;
+  const clone = shallowCloneJson(root);
+  owned.add(clone);
+  state.root = clone;
+  return clone;
+}
+
+/**
+ * Return an owned version of `child`, writing the clone back into the
+ * (already owned) parent slot when one is taken.
+ */
+export function ownedChild(state, parent, child, key) {
+  const owned = state.owned;
+  if (owned === null || !isJsonContainer(child) || owned.has(child))
+    return child;
+  const clone = shallowCloneJson(child);
+  owned.add(clone);
+  // the slot was just read through hasOwn/index, so plain assignment
+  // never reaches a prototype '__proto__' setter
+  parent[key] = clone;
+  return clone;
+}
+
+/**
+ * The concrete array index a step addresses in `parent`, or -1 when the
+ * step cannot address an array element. Typed index steps resolve
+ * negative indexes from the end; the RFC 6901 form never does.
+ */
+export function stepArrayIndex(parent, name, index) {
+  if (name === null)
+    return index < 0 ? parent.length + index : index;
+  return index;
+}
+
+/**
+ * Read the location `steps[0..len)` in `root` without cloning anything.
+ * Returns the shared NOTHING-style `miss` sentinel value passed in when
+ * the location does not exist (callers pick their own sentinel).
+ */
+export function readSteps(root, names, indexes, len, miss) {
+  let v = root;
+  for (let i = 0; i < len; i++) {
+    if (Array.isArray(v)) {
+      const idx = stepArrayIndex(v, names[i], indexes[i]);
+      if (idx < 0 || idx >= v.length)
+        return miss;
+      v = v[idx];
+    }
+    else if (typeof v === 'object' && v !== null) {
+      const name = names[i];
+      if (name === null || !hasOwn(v, name))
+        return miss;
+      v = v[name];
+    }
+    else {
+      return miss;
+    }
+  }
+  return v;
+}
+
+//#endregion

package/src/errors.js

@@ -0,0 +1,68 @@
+//#region Jaren shared error bases
+// Shared constructors for the coded error classes of the json package.
+// Each engine keeps its own exported class (the `name` and `message`
+// shapes are public API); these bases only centralize the constructor
+// bodies that were byte-identical across engines. The `name` is passed
+// as a string literal because the bundle is minified and a mangled
+// class name must not leak into `error.name`.
+
+import { CodedError } from '@jarenjs/core/errors';
+
+/**
+ * Base for errors that carry a stable `code` and a `docPath`, an RFC
+ * 6901 JSON Pointer into the offending document. A wrapped error is
+ * exposed through the native `cause` option when one is given. This is
+ * the positional adapter over `@jarenjs/core`'s {@link CodedError}: a
+ * trailing `undefined` cause means "no cause" (no own property), per
+ * the base's contract.
+ */
+export class CodedDocPathError extends CodedError {
+  /**
+   * @param {string} name - The public class name for `error.name`
+   * @param {string} code - Stable diagnosis code
+   * @param {string} reason - What is wrong (bare; the message is composed)
+   * @param {string} docPath - JSON Pointer into the offending document
+   * @param {unknown} [cause] - Wrapped error, when there is one
+   */
+  constructor(name, code, reason, docPath, cause = undefined) {
+    super(name, code, reason, docPath,
+      cause === undefined ? undefined : { cause });
+  }
+}
+
+/**
+ * Base for syntax errors over a source string: `source` and `position`
+ * locate the offending token, and the message is prefixed with a
+ * human-readable language label. Deliberately NOT a {@link CodedError}:
+ * this family carries no stable code and locates by source offset, not
+ * by document pointer.
+ */
+export class LabeledSyntaxError extends SyntaxError {
+  /**
+   * @param {string} name - The public class name for `error.name`
+   * @param {string} label - Language label for the message prefix
+   * @param {string} message - What is wrong
+   * @param {string} source - The offending source text
+   * @param {number} position - 0-based index of the offending token
+   */
+  constructor(name, label, message, source, position) {
+    super(`Invalid ${label}: ${message} at position ${position} in '${source}'`);
+    this.name = name;
+    this.source = source;
+    this.position = position;
+  }
+}
+
+/**
+ * Build a `fail(code, message, docPath)` throw-adapter for a coded
+ * error class; compilers use it to keep rejection one-liners readable.
+ * @param {new (code: string, message: string, docPath: string) => Error} ErrorClass
+ * @returns {(code: string, message: string, docPath: string) => never}
+ */
+export function failerFor(ErrorClass) {
+  return function fail(code, message, docPath) {
+    throw new ErrorClass(code, message, docPath);
+  };
+}
+
+//#endregion

package/src/index.js

@@ -1,4 +1,7 @@
 export * from './basic.js';
+export * from './canonical.js';
 export * from './pointer.js';
+export * from './patch.js';
 export * from './path.js';
+export * from './write.js';
 export * from './query/index.js';