@jarenjs/json 0.9.2 → 0.34.2

package/src/pointer.js

@@ -1,13 +1,21 @@
 //#region JSON Pointer (RFC 6901) + Relative JSON Pointer
 // JSON Pointer: https://datatracker.ietf.org/doc/html/rfc6901
-// Relative JSON Pointer:
-// https://datatracker.ietf.org/doc/html/draft-luff-relative-json-pointer-00
+// Relative JSON Pointer: draft-handrews-relative-json-pointer-01, the
+// revision JSON Schema 2020-12 normatively references:
+// https://datatracker.ietf.org/doc/html/draft-handrews-relative-json-pointer-01
+//
+// The newer draft-bhutton-relative-json-pointer-00 adds an index-
+// manipulation form (`0+1`, `1-1`) that this grammar deliberately does not
+// accept: the official format suite still asserts `+1/foo/bar` INVALID, so
+// accepting it would have to arrive together with a dialect gate for the
+// `relative-json-pointer` format tester.
 //
 // This module implements JSON Pointer as a two-stage compiler, mirroring
 // the JSONPath engine in path.js:
 //
 //   1. `parseJSONPointer` / `parseRelativeJSONPointer` - strict, single-pass
-//      char-code parsers enforcing the full RFC 6901 / draft-luff grammar.
+//      char-code parsers enforcing the full RFC 6901 / relative-pointer
+//      grammar.
 //   2. `compileJSONPointer` / `compileRelativeJSONPointer` /
 //      `compileDataRef` - compile the parsed form into specialized getter
 //      closures. All decisions (member name decoding, array index parsing,
@@ -24,7 +32,8 @@ import {
   isDigitCode,
 } from '@jarenjs/core/scan';
 
-import { NOTHING } from './segments.js';
+import { NOTHING, scanArrayIndex } from './segments.js';
+import { LabeledSyntaxError } from './errors.js';
 
 /**
  * Sentinel for the absence of a value, as distinct from the JSON value
@@ -39,12 +48,9 @@ const hasOwn = Object.hasOwn;
  * Error thrown when a (relative) JSON Pointer is not valid RFC 6901 /
  * draft-luff-relative-json-pointer syntax.
  */
-export class JSONPointerSyntaxError extends SyntaxError {
+export class JSONPointerSyntaxError extends LabeledSyntaxError {
   constructor(message, source, position) {
-    super(`Invalid JSON Pointer: ${message} at position ${position} in '${source}'`);
-    this.name = 'JSONPointerSyntaxError';
-    this.source = source;
-    this.position = position;
+    super('JSONPointerSyntaxError', 'JSON Pointer', message, source, position);
   }
 }
 
@@ -171,38 +177,99 @@ export function parseRelativeJSONPointer(pointer) {
   return { levels, hash: false, segments: scanSegments(pointer, pos) };
 }
 
-//#endregion
+const RE_TILDE = /~/g;
+const RE_SLASH = /\//g;
+const RE_ESCAPED_SLASH = /~1/g;
+const RE_ESCAPED_TILDE = /~0/g;
 
-//#region compiler
+/**
+ * Encode a single reference token for use inside an RFC 6901 JSON
+ * Pointer: `~` becomes `~0` and `/` becomes `~1` (RFC 6901 section 3).
+ * The write-side inverse of the parser's decode; the escape-free common
+ * case returns the input unchanged.
+ * @param {string|number} segment - The raw member name or array index
+ * @returns {string} The encoded reference token
+ * @example
+ * encodeJSONPointerSegment('a/b'); // 'a~1b'
+ */
+export function encodeJSONPointerSegment(segment) {
+  const s = String(segment);
+  return (s.indexOf('~') < 0 && s.indexOf('/') < 0)
+    ? s
+    : s.replace(RE_TILDE, '~0').replace(RE_SLASH, '~1');
+}
 
-// Array indexes are bounded by the maximum array length (2^32 - 1), so a
-// valid index has at most 10 digits and is strictly below 2^32 - 1.
-const MAX_ARRAY_INDEX = 4294967294;
+/**
+ * Decode one RFC 6901 reference token: `~1` becomes `/` and `~0` becomes
+ * `~`. The order is normative (RFC 6901 section 4) and not an accident of
+ * implementation — decoding `~0` first would turn `~01` into `~1` and then
+ * into `/`, so a member literally named `~1` would come back as `/`.
+ * The escape-free common case returns the input unchanged.
+ * @param {string} token - One encoded reference token (no `/` separators)
+ * @returns {string} The decoded member name
+ * @example
+ * decodeJSONPointerSegment('a~1b'); // 'a/b'
+ */
+export function decodeJSONPointerSegment(token) {
+  return token.indexOf('~') < 0
+    ? token
+    : token.replace(RE_ESCAPED_SLASH, '/').replace(RE_ESCAPED_TILDE, '~');
+}
 
 /**
- * Scan `source[start..end)` as an RFC 6901 array index: `0`, or a digit
- * sequence without leading zeros. Returns -1 when the range is not a
- * valid index (`-` is never a valid read index).
+ * Format decoded reference tokens as an RFC 6901 JSON Pointer; the
+ * inverse of `parseJSONPointer`. An empty array formats as the empty
+ * (whole-document) pointer.
+ * @param {(string|number)[]} segments - Decoded reference tokens
+ * @returns {string} The JSON Pointer
+ * @example
+ * formatJSONPointer(['a/b', 0]); // '/a~1b/0'
  */
-function scanArrayIndex(source, start, end) {
-  const digits = end - start;
-  if (digits === 0 || digits > 10)
-    return -1;
-  const first = source.charCodeAt(start);
-  if (!isDigitCode(first))
-    return -1;
-  if (first === CC_0)
-    return digits === 1 ? 0 : -1;
-  let index = first - CC_0;
-  for (let i = start + 1; i < end; i++) {
-    const c = source.charCodeAt(i);
-    if (!isDigitCode(c))
-      return -1;
-    index = index * 10 + (c - CC_0);
+export function formatJSONPointer(segments) {
+  let out = '';
+  for (let i = 0; i < segments.length; i++)
+    out += '/' + encodeJSONPointerSegment(segments[i]);
+  return out;
+}
+
+/**
+ * Parse a JSON Pointer into a path array, narrowing every canonical array
+ * index to a number and leaving all other tokens as decoded strings.
+ *
+ * RFC 6901 has no types: `/items/0/id` addresses element 0 of an array and
+ * member `"0"` of an object with the same token. This function resolves that
+ * lexically, not against a document — a token is a number when it is `0` or a
+ * digit sequence without leading zeros within the array-index range, which is
+ * the same rule the pointer compiler uses to pre-parse indexes. `"01"`,
+ * `"1e0"`, `"-"` and `"1abc"` therefore stay strings.
+ *
+ * The result is the `(string|number)[]` shape that error reporters and
+ * diffing tools use for data locations, so it pairs directly with a
+ * validation error's `instancePath`. `formatJSONPointer` is the inverse.
+ * @param {string} pointer - The JSON Pointer (e.g. `/store/book/0`)
+ * @returns {(string|number)[]} Decoded tokens with array indexes as numbers
+ * @throws {JSONPointerSyntaxError} When the pointer violates the grammar
+ * @example
+ * parseJSONPointerPath('/items/0/id');  // ['items', 0, 'id']
+ * parseJSONPointerPath('/items/01');    // ['items', '01']
+ * parseJSONPointerPath('/a~1b');        // ['a/b']
+ */
+export function parseJSONPointerPath(pointer) {
+  const segments = parseJSONPointer(pointer);
+  /** @type {(string|number)[]} */
+  const path = segments;
+  for (let i = 0; i < segments.length; i++) {
+    const token = segments[i];
+    const index = scanArrayIndex(token, 0, token.length);
+    if (index !== -1) path[i] = index;
   }
-  return index <= MAX_ARRAY_INDEX ? index : -1;
+  return path;
 }
 
+//#endregion
+
+//#region compiler
+
 /**
  * One pointer hop: an array is addressed by the pre-parsed index, an
  * object by the pre-decoded member name (own properties only), anything
@@ -247,6 +314,28 @@ function compileSegmentsGetter(segments) {
       return v === NOTHING ? NOTHING : hop(v, name1, index1);
     };
   }
+  const name2 = segments[2];
+  const index2 = scanArrayIndex(name2, 0, name2.length);
+  if (slen === 3) {
+    return function pointerGetter3(root) {
+      const v0 = hop(root, name0, index0);
+      if (v0 === NOTHING) return NOTHING;
+      const v1 = hop(v0, name1, index1);
+      return v1 === NOTHING ? NOTHING : hop(v1, name2, index2);
+    };
+  }
+  const name3 = segments[3];
+  const index3 = scanArrayIndex(name3, 0, name3.length);
+  if (slen === 4) {
+    return function pointerGetter4(root) {
+      const v0 = hop(root, name0, index0);
+      if (v0 === NOTHING) return NOTHING;
+      const v1 = hop(v0, name1, index1);
+      if (v1 === NOTHING) return NOTHING;
+      const v2 = hop(v1, name2, index2);
+      return v2 === NOTHING ? NOTHING : hop(v2, name3, index3);
+    };
+  }
   const names = segments;
   const indexes = new Array(slen);
   for (let i = 0; i < slen; i++)
@@ -326,11 +415,15 @@ function decodeSegmentRange(source, start, end, tilde) {
 /**
  * The last segment of `dataPath.slice(0, end)`, decoded lazily: the
  * common escape-free case allocates nothing beyond the result slice.
- * At the root (`end === 0`) the name of the location is `''`.
+ *
+ * The root (`end === 0`) has no name, so it yields NOTHING rather than
+ * `''` — `''` is a member name a document can genuinely have (`{"": 1}`
+ * at `/`), and returning it for the root too would make the two
+ * indistinguishable to the caller.
  */
 function lastSegmentOf(dataPath, end) {
   if (end === 0)
-    return '';
+    return NOTHING;
   const start = dataPath.lastIndexOf('/', end - 1) + 1;
   for (let i = start; i < end; i++) {
     if (dataPath.charCodeAt(i) === CC_TILDE)
@@ -339,6 +432,34 @@ function lastSegmentOf(dataPath, end) {
   return dataPath.slice(start, end);
 }
 
+/**
+ * Read and validate the `hashIndex` compile option, defaulting to the
+ * historical `'string'`. An unknown value is rejected rather than ignored:
+ * silently falling back would hand a caller who meant `'number'` the exact
+ * behavior they were opting out of.
+ * @param {{ hashIndex?: string }} [options]
+ * @returns {'string'|'number'}
+ */
+function readHashIndexOption(options) {
+  if (options === undefined || options === null)
+    return 'string';
+  const mode = options.hashIndex;
+  if (mode === undefined || mode === 'string')
+    return 'string';
+  if (mode === 'number')
+    return 'number';
+  throw new TypeError(
+    `hashIndex must be 'string' or 'number', got ${JSON.stringify(mode)}`);
+}
+
+/**
+ * The exclusive end of the *parent* of the location `dataPath.slice(0, end)`,
+ * or -1 when that location is the root and so has no parent.
+ */
+function parentEndOf(dataPath, end) {
+  return end === 0 ? -1 : dataPath.lastIndexOf('/', end - 1);
+}
+
 /**
  * Walk `root` along the location path prefix `path.slice(0, end)`.
  * Segments are decoded lazily per hop (escape-free segments are sliced
@@ -382,23 +503,65 @@ function walkPointerPrefix(root, path, end) {
  *
  * The relative part (level count, `#` form, trailing segments) compiles
  * once; per call only `dataPath` - the current location in `dataRoot` as
- * an RFC 6901 pointer - varies. The `#` form resolves to the member name
- * or array index of the location **as a string** (`''` at the root),
- * matching the historical behavior relied on by the validator's `$data`
- * keyword.
+ * an RFC 6901 pointer - varies.
+ *
+ * The root has no name: `0#` there yields `JSONPOINTER_NOTHING`, not `''`,
+ * so it stays distinguishable from the member named `''` (`{"": 1}` at
+ * `/`), which is a name a document can genuinely have.
+ *
+ * ### The `#` form and `hashIndex`
+ *
+ * Relative JSON Pointer says `#` yields the member *name* for an object
+ * member and the *index* — a number — for an array element. Telling those
+ * apart requires looking at the container, so the two modes cost different
+ * things and you choose per compile:
+ *
+ * - `hashIndex: 'string'` (**default**) answers from `dataPath` alone and
+ *   never touches `dataRoot`: an array position comes back as the string
+ *   `'1'`. This is the historical behavior the validator's `$data` keyword
+ *   relies on, and it is a string operation — tens of nanoseconds.
+ * - `hashIndex: 'number'` is the draft's answer. It walks to the parent of
+ *   the location to see whether it is an array, and returns `1` rather than
+ *   `'1'` when it is. Object member names are unaffected. When the parent
+ *   cannot be reached (the location does not exist in `dataRoot`) it falls
+ *   back to the string, because nothing proves the position is an index.
+ *
+ * Neither mode verifies that the location itself exists; the caller is
+ * expected to pass a location it actually reached. The non-`#` form must
+ * walk regardless, because it returns the value.
  *
  * @param {string} pointer - The relative pointer (e.g. `1/sibling`, `0#`)
+ * @param {{ hashIndex?: 'string'|'number' }} [options] - `hashIndex`
+ *   selects what the `#` form yields for an array position (default
+ *   `'string'`)
  * @returns {RelativeJsonPointerResolver} resolver returning
  *   the addressed value, or `JSONPOINTER_NOTHING`
  * @throws {JSONPointerSyntaxError} When the pointer is not valid
+ * @throws {TypeError} When `hashIndex` is neither `'string'` nor `'number'`
  * @example
  * const resolve = compileRelativeJSONPointer('1/limits');
  * resolve({ limits: { min: 2 } , value: 5 }, '/value'); // { min: 2 }
+ * @example
+ * const spec = compileRelativeJSONPointer('0#', { hashIndex: 'number' });
+ * spec({ a: ['x', 'y'] }, '/a/1'); // 1  (the number, per the draft)
  */
-export function compileRelativeJSONPointer(pointer) {
+export function compileRelativeJSONPointer(pointer, options = undefined) {
   const { levels, hash, segments } = parseRelativeJSONPointer(pointer);
+  const numericHash = readHashIndexOption(options) === 'number';
   if (hash) {
-    return function relativeHashResolver(dataRoot, dataPath) {
+    if (!numericHash) {
+      return function relativeHashResolver(dataRoot, dataPath) {
+        if (typeof dataPath !== 'string')
+          dataPath = '';
+        else if (dataPath.length !== 0 && dataPath.charCodeAt(0) !== CC_SLASH)
+          return NOTHING;
+        const end = trimLevels(dataPath, levels);
+        if (end < 0)
+          return NOTHING;
+        return lastSegmentOf(dataPath, end);
+      };
+    }
+    return function relativeHashIndexResolver(dataRoot, dataPath) {
       if (typeof dataPath !== 'string')
         dataPath = '';
       else if (dataPath.length !== 0 && dataPath.charCodeAt(0) !== CC_SLASH)
@@ -406,7 +569,19 @@ export function compileRelativeJSONPointer(pointer) {
       const end = trimLevels(dataPath, levels);
       if (end < 0)
         return NOTHING;
-      return lastSegmentOf(dataPath, end);
+      const name = lastSegmentOf(dataPath, end);
+      if (name === NOTHING)
+        return NOTHING;
+      // An index is only an index when its container is an array; the name
+      // of a `{"1": …}` member is the string "1" in every mode.
+      const parentEnd = parentEndOf(dataPath, end);
+      if (parentEnd < 0)
+        return name;
+      const parent = walkPointerPrefix(dataRoot, dataPath, parentEnd);
+      if (!Array.isArray(parent))
+        return name;
+      const index = scanArrayIndex(name, 0, name.length);
+      return index < 0 ? name : index;
     };
   }
   const getter = compileSegmentsGetter(segments);
@@ -430,19 +605,25 @@ export function compileRelativeJSONPointer(pointer) {
  * Pointer, a leading `/` an absolute JSON Pointer, and `''` the root.
  *
  * @param {string} ref - The reference string
+ * @param {{ hashIndex?: 'string'|'number' }} [options] - forwarded to
+ *   {@link compileRelativeJSONPointer}; only the relative forms read it
  * @returns {RelativeJsonPointerResolver} resolver returning
  *   the addressed value, or `JSONPOINTER_NOTHING`
  * @throws {JSONPointerSyntaxError} When the reference is none of the
  *   accepted forms
+ * @throws {TypeError} When `hashIndex` is neither `'string'` nor `'number'`
  */
-export function compileDataRef(ref) {
+export function compileDataRef(ref, options = undefined) {
   if (typeof ref !== 'string')
     throw new JSONPointerSyntaxError('a data reference must be a string', String(ref), 0);
+  // Validate the option even on the forms that ignore it, so a typo is a
+  // compile-time error wherever it appears rather than only on `N#` refs.
+  readHashIndexOption(options);
   if (ref.length === 0)
     return getRoot;
   const c = ref.charCodeAt(0);
   if (isDigitCode(c))
-    return compileRelativeJSONPointer(ref);
+    return compileRelativeJSONPointer(ref, options);
   if (c === CC_SLASH)
     return compileSegmentsGetter(scanSegments(ref, 0));
   throw new JSONPointerSyntaxError('a data reference must be empty, a JSON Pointer or a Relative JSON Pointer', ref, 0);