@swaggerexpert/jsonpath 3.2.5 → 4.0.0

package/es/evaluate/utils/i-regexp.mjs

@@ -0,0 +1,113 @@
+/**
+ * I-Regexp (RFC 9485) utilities for JSONPath match() and search() functions.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9485 - I-Regexp specification
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.1 - match() function
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.2 - search() function
+ */
+
+const regexpCache = new Map();
+
+/**
+ * Validate and transform I-Regexp pattern to ECMAScript regex pattern.
+ * Returns null if pattern contains non-I-Regexp features:
+ * - Backreferences (\1, \2, etc.)
+ * - Lookahead/lookbehind assertions
+ * - Named capture groups
+ * - Word boundaries outside character classes
+ *
+ * Transforms `.` to `[^\n\r]` outside character classes (I-Regexp semantics).
+ *
+ * @param {string} pattern
+ * @returns {string | null} - Transformed pattern or null if invalid
+ */
+const transformIRegexp = pattern => {
+  let result = '';
+  let inCharClass = false;
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+
+    // Handle escape sequences
+    if (ch === '\\' && i + 1 < pattern.length) {
+      const next = pattern[i + 1];
+
+      // Reject backreferences (\1-\9)
+      if (next >= '1' && next <= '9') return null;
+
+      // Reject word boundaries outside character classes
+      if (!inCharClass && (next === 'b' || next === 'B')) return null;
+      result += ch + next;
+      i += 2;
+      continue;
+    }
+
+    // Track character class boundaries
+    if (ch === '[' && !inCharClass) {
+      inCharClass = true;
+      result += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === ']' && inCharClass) {
+      inCharClass = false;
+      result += ch;
+      i += 1;
+      continue;
+    }
+
+    // Check for lookahead/lookbehind/named groups: (?=, (?!, (?<=, (?<!, (?<name>
+    if (ch === '(' && i + 2 < pattern.length && pattern[i + 1] === '?') {
+      const next2 = pattern[i + 2];
+      // Reject lookahead (?= (?!
+      if (next2 === '=' || next2 === '!') return null;
+      // Check for lookbehind or named groups
+      if (next2 === '<' && i + 3 < pattern.length) {
+        const next3 = pattern[i + 3];
+        // Reject lookbehind (?<= (?<!
+        if (next3 === '=' || next3 === '!') return null;
+        // Reject named capture groups (?<name>
+        if (/[a-zA-Z]/.test(next3)) return null;
+      }
+    }
+
+    // Transform `.` to `[^\n\r]` outside character classes
+    if (ch === '.' && !inCharClass) {
+      result += '[^\\n\\r]';
+      i += 1;
+      continue;
+    }
+    result += ch;
+    i += 1;
+  }
+  return result;
+};
+
+/**
+ * Construct a RegExp from I-Regexp pattern.
+ * Validates the pattern, transforms it, and caches the result.
+ *
+ * @param {string} pattern - I-Regexp pattern
+ * @param {boolean} [anchor=false] - If true, anchor pattern with ^(?:...)$
+ * @returns {RegExp | null} - Compiled regex or null if invalid
+ */
+export const constructRegex = (pattern, anchor = false) => {
+  const cacheKey = anchor ? `anchored:${pattern}` : `unanchored:${pattern}`;
+  if (regexpCache.has(cacheKey)) {
+    return regexpCache.get(cacheKey);
+  }
+  const transformed = transformIRegexp(pattern);
+  if (transformed === null) {
+    regexpCache.set(cacheKey, null);
+    return null;
+  }
+  try {
+    const finalPattern = anchor ? `^(?:${transformed})$` : transformed;
+    const regex = new RegExp(finalPattern, 'u');
+    regexpCache.set(cacheKey, regex);
+    return regex;
+  } catch {
+    regexpCache.set(cacheKey, null);
+    return null;
+  }
+};

package/es/evaluate/visitors/bracketed-selection.mjs

@@ -0,0 +1,29 @@
+/**
+ * Bracketed selection visitor.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.5.1
+ *
+ * A bracketed selection contains one or more selectors.
+ * Each selector's results are concatenated.
+ */
+import visitSelector from "./selector.mjs";
+/**
+ * Visit a bracketed selection.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} node - AST node
+ * @param {object[]} node.selectors - Array of selector AST nodes
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitBracketedSelection = (ctx, value, node, emit) => {
+  const {
+    selectors
+  } = node;
+
+  // Visit each selector and emit its results
+  for (const selector of selectors) {
+    visitSelector(ctx, value, selector, emit);
+  }
+};
+export default visitBracketedSelection;

package/es/evaluate/visitors/filter-selector.mjs

@@ -0,0 +1,37 @@
+/**
+ * Filter selector visitor.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5
+ *
+ * A filter selector [?expr] selects all children where the expression is true.
+ * For arrays: tests each element
+ * For objects: tests each member value
+ */
+import evaluateLogicalExpr from "../evaluators/logical-expr.mjs";
+/**
+ * Visit a filter selector.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {object} ctx.realm - Data realm
+ * @param {object} ctx.root - Root value ($)
+ * @param {unknown} value - Current value
+ * @param {object} node - AST node
+ * @param {object} node.expression - Logical expression to evaluate
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitFilterSelector = (ctx, value, node, emit) => {
+  const {
+    realm,
+    root
+  } = ctx;
+  const {
+    expression
+  } = node;
+  for (const [key, child] of realm.entries(value)) {
+    const result = evaluateLogicalExpr(ctx, root, child, expression);
+    if (result) {
+      emit(child, key);
+    }
+  }
+};
+export default visitFilterSelector;

package/es/evaluate/visitors/index-selector.mjs

@@ -0,0 +1,51 @@
+/**
+ * Index selector visitor.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.3
+ *
+ * An index selector selects at most one element from an array.
+ * Supports negative indices (count from end).
+ */
+
+/**
+ * Normalize an array index.
+ * Negative indices count from the end.
+ *
+ * @param {number} index - The index (may be negative)
+ * @param {number} length - Array length
+ * @returns {number} - Normalized index (non-negative or out of bounds)
+ */
+const normalizeIndex = (index, length) => {
+  if (index >= 0) return index;
+  return length + index;
+};
+
+/**
+ * Visit an index selector.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {object} ctx.realm - Data realm
+ * @param {unknown} value - Current value
+ * @param {object} node - AST node
+ * @param {number} node.value - Index to select
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitIndexSelector = (ctx, value, node, emit) => {
+  const {
+    realm
+  } = ctx;
+  const {
+    value: index
+  } = node;
+  if (!realm.isArray(value)) return;
+  const length = realm.getLength(value);
+  const normalizedIndex = normalizeIndex(index, length);
+
+  // Check bounds
+  if (normalizedIndex >= 0 && normalizedIndex < length) {
+    const selected = realm.getElement(value, normalizedIndex);
+    emit(selected, normalizedIndex);
+  }
+  // If out of bounds, yield nothing
+};
+export default visitIndexSelector;

package/es/evaluate/visitors/name-selector.mjs

@@ -0,0 +1,34 @@
+/**
+ * Name selector visitor.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.1
+ *
+ * A name selector selects at most one member value from an object.
+ * If the object has the specified member, yield its value.
+ * If not, yield nothing.
+ */
+
+/**
+ * Visit a name selector.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {object} ctx.realm - Data realm
+ * @param {unknown} value - Current value
+ * @param {object} node - AST node
+ * @param {string} node.value - Property name to select
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitNameSelector = (ctx, value, node, emit) => {
+  const {
+    realm
+  } = ctx;
+  const {
+    value: name
+  } = node;
+  if (realm.isObject(value) && realm.hasProperty(value, name)) {
+    const selected = realm.getProperty(value, name);
+    emit(selected, name);
+  }
+  // If not an object or property doesn't exist, yield nothing
+};
+export default visitNameSelector;

package/es/evaluate/visitors/segment.mjs

@@ -0,0 +1,91 @@
+/**
+ * Segment visitor dispatcher.
+ *
+ * Handles ChildSegment and DescendantSegment types.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.5
+ */
+import visitSelector from "./selector.mjs";
+import visitBracketedSelection from "./bracketed-selection.mjs";
+/**
+ * Visit a segment's selector.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} selector - Selector AST node
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitSegmentSelector = (ctx, value, selector, emit) => {
+  switch (selector.type) {
+    case 'BracketedSelection':
+      visitBracketedSelection(ctx, value, selector, emit);
+      break;
+    case 'NameSelector':
+    case 'WildcardSelector':
+    case 'IndexSelector':
+    case 'SliceSelector':
+    case 'FilterSelector':
+      visitSelector(ctx, value, selector, emit);
+      break;
+    default:
+      break;
+  }
+};
+
+/**
+ * Visit a child segment.
+ * Applies selector to current value.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} node - ChildSegment AST node
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+export const visitChildSegment = (ctx, value, node, emit) => {
+  const {
+    selector
+  } = node;
+  visitSegmentSelector(ctx, value, selector, emit);
+};
+
+/**
+ * Visit a descendant segment.
+ * Applies selector to current value and all descendants.
+ *
+ * Note: This is used by exec.js which handles the recursive descent
+ * by pushing descendants onto the stack. This function only applies
+ * the selector at the current level.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} node - DescendantSegment AST node
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+export const visitDescendantSegment = (ctx, value, node, emit) => {
+  const {
+    selector
+  } = node;
+  visitSegmentSelector(ctx, value, selector, emit);
+};
+
+/**
+ * Visit a segment and emit selected values.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} node - Segment AST node
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitSegment = (ctx, value, node, emit) => {
+  switch (node.type) {
+    case 'ChildSegment':
+      visitChildSegment(ctx, value, node, emit);
+      break;
+    case 'DescendantSegment':
+      visitDescendantSegment(ctx, value, node, emit);
+      break;
+    default:
+      break;
+  }
+};
+export default visitSegment;

package/es/evaluate/visitors/selector.mjs

@@ -0,0 +1,41 @@
+/**
+ * Selector visitor dispatcher.
+ *
+ * Routes to the appropriate selector visitor based on AST node type.
+ */
+import visitNameSelector from "./name-selector.mjs";
+import visitIndexSelector from "./index-selector.mjs";
+import visitWildcardSelector from "./wildcard-selector.mjs";
+import visitSliceSelector from "./slice-selector.mjs";
+import visitFilterSelector from "./filter-selector.mjs";
+/**
+ * Visit a selector and emit selected values.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} node - Selector AST node
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitSelector = (ctx, value, node, emit) => {
+  switch (node.type) {
+    case 'NameSelector':
+      visitNameSelector(ctx, value, node, emit);
+      break;
+    case 'IndexSelector':
+      visitIndexSelector(ctx, value, node, emit);
+      break;
+    case 'WildcardSelector':
+      visitWildcardSelector(ctx, value, node, emit);
+      break;
+    case 'SliceSelector':
+      visitSliceSelector(ctx, value, node, emit);
+      break;
+    case 'FilterSelector':
+      visitFilterSelector(ctx, value, node, emit);
+      break;
+    default:
+      // Unknown selector type, yield nothing
+      break;
+  }
+};
+export default visitSelector;

package/es/evaluate/visitors/slice-selector.mjs

@@ -0,0 +1,111 @@
+/**
+ * Slice selector visitor.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.4
+ *
+ * A slice selector [start:end:step] selects elements from an array.
+ * - start: first index (default 0 for positive step, len-1 for negative)
+ * - end: upper bound (default len for positive step, -len-1 for negative)
+ * - step: step size (default 1, must not be 0)
+ */
+
+/**
+ * Normalize a slice bound according to RFC 9535.
+ * @param {number} index - The bound value
+ * @param {number} length - Array length
+ * @returns {number} - Normalized bound
+ */
+const normalizeBound = (index, length) => {
+  if (index >= 0) {
+    return Math.min(index, length);
+  }
+  return Math.max(length + index, 0);
+};
+
+/**
+ * Get slice bounds and step according to RFC 9535 Section 2.3.4.2.
+ *
+ * @param {number | null} start
+ * @param {number | null} end
+ * @param {number | null} step
+ * @param {number} length - Array length
+ * @returns {{ lower: number, upper: number, step: number } | null}
+ */
+const getSliceBounds = (start, end, step, length) => {
+  // Default step is 1
+  const actualStep = step ?? 1;
+
+  // Step of 0 is not allowed
+  if (actualStep === 0) return null;
+  let lower;
+  let upper;
+  if (actualStep > 0) {
+    // Forward iteration
+    const defaultStart = 0;
+    const defaultEnd = length;
+    const normalizedStart = start !== null ? normalizeBound(start, length) : defaultStart;
+    const normalizedEnd = end !== null ? normalizeBound(end, length) : defaultEnd;
+    lower = Math.max(normalizedStart, 0);
+    upper = Math.min(normalizedEnd, length);
+  } else {
+    // Backward iteration
+    const defaultStart = length - 1;
+    const defaultEnd = -length - 1;
+    const normalizedStart = start !== null ? start >= 0 ? Math.min(start, length - 1) : Math.max(length + start, -1) : defaultStart;
+    const normalizedEnd = end !== null ? end >= 0 ? Math.min(end, length - 1) : Math.max(length + end, -1) : defaultEnd;
+    upper = Math.min(normalizedStart, length - 1);
+    lower = Math.max(normalizedEnd, -1);
+  }
+  return {
+    lower,
+    upper,
+    step: actualStep
+  };
+};
+
+/**
+ * Visit a slice selector.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {object} ctx.realm - Data realm
+ * @param {unknown} value - Current value
+ * @param {object} node - AST node
+ * @param {number | null} node.start - Start index
+ * @param {number | null} node.end - End index
+ * @param {number | null} node.step - Step
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitSliceSelector = (ctx, value, node, emit) => {
+  const {
+    realm
+  } = ctx;
+  const {
+    start,
+    end,
+    step
+  } = node;
+  if (!realm.isArray(value)) return;
+  const length = realm.getLength(value);
+  const bounds = getSliceBounds(start, end, step, length);
+  if (bounds === null) return; // step was 0
+
+  const {
+    lower,
+    upper,
+    step: actualStep
+  } = bounds;
+  if (actualStep > 0) {
+    // Forward iteration
+    for (let i = lower; i < upper; i += actualStep) {
+      const selected = realm.getElement(value, i);
+      emit(selected, i);
+    }
+  } else {
+    // Backward iteration
+    for (let i = upper; i > lower; i += actualStep) {
+      const selected = realm.getElement(value, i);
+      emit(selected, i);
+    }
+  }
+};
+export default visitSliceSelector;

package/es/evaluate/visitors/wildcard-selector.mjs

@@ -0,0 +1,28 @@
+/**
+ * Wildcard selector visitor.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.2
+ *
+ * A wildcard selector selects all children of a value:
+ * - For arrays: all elements
+ * - For objects: all member values
+ */
+
+/**
+ * Visit a wildcard selector.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {object} ctx.realm - Data realm
+ * @param {unknown} value - Current value
+ * @param {object} node - AST node (unused for wildcard)
+ * @param {(value: unknown, segment: string | number) => void} emit - Callback to emit selected value
+ */
+const visitWildcardSelector = (ctx, value, node, emit) => {
+  const {
+    realm
+  } = ctx;
+  for (const [key, child] of realm.entries(value)) {
+    emit(child, key);
+  }
+};
+export default visitWildcardSelector;

package/es/index.mjs

@@ -6,8 +6,12 @@ export { default as ASTTranslator } from "./parse/translators/ASTTranslator/inde
 export { default as XMLTranslator } from "./parse/translators/XMLTranslator.mjs";
 export { default as Trace } from "./parse/trace/Trace.mjs";
 export { default as test } from "./test/index.mjs";
-export { default as compile } from "./compile.mjs";
-export { default as escape } from "./escape.mjs";
+export * as NormalizedPath from "./normalized-path.mjs";
+export { default as evaluate } from "./evaluate/index.mjs";
+export * as functions from "./evaluate/functions/index.mjs";
+export { default as EvaluationRealm } from "./evaluate/realms/EvaluationRealm.mjs";
+export { default as JSONEvaluationRealm } from "./evaluate/realms/json/index.mjs";
 export { default as JSONPathError } from "./errors/JSONPathError.mjs";
 export { default as JSONPathParseError } from "./errors/JSONPathParseError.mjs";
-export { default as JSONPathCompileError } from "./errors/JSONPathCompileError.mjs";
+export { default as JSONNormalizedPathError } from "./errors/JSONNormalizedPathError.mjs";
+export { default as JSONPathEvaluateError } from "./errors/JSONPathEvaluateError.mjs";

package/es/normalized-path.mjs

@@ -0,0 +1,136 @@
+import parse from "./parse/index.mjs";
+import testFn from "./test/index.mjs";
+import JSONNormalizedPathError from "./errors/JSONNormalizedPathError.mjs";
+/**
+ * Tests if a string is a valid normalized JSONPath.
+ *
+ * @param {string} normalizedPath - The string to test
+ * @returns {boolean} True if valid normalized path, false otherwise
+ */
+export const test = normalizedPath => testFn(normalizedPath, {
+  normalized: true
+});
+
+/**
+ * Escapes a string for use in a normalized JSONPath name selector.
+ * Follows RFC 9535 Section 2.7 escaping rules for single-quoted strings.
+ *
+ * @param {string} selector - The string to escape
+ * @returns {string} The escaped string (without surrounding quotes)
+ */
+export const escape = selector => {
+  if (typeof selector !== 'string') {
+    throw new TypeError('Selector must be a string');
+  }
+  let escaped = '';
+  for (const char of selector) {
+    const codePoint = char.codePointAt(0);
+    switch (codePoint) {
+      case 0x08:
+        // backspace
+        escaped += '\\b';
+        break;
+      case 0x09:
+        // horizontal tab
+        escaped += '\\t';
+        break;
+      case 0x0a:
+        // line feed
+        escaped += '\\n';
+        break;
+      case 0x0c:
+        // form feed
+        escaped += '\\f';
+        break;
+      case 0x0d:
+        // carriage return
+        escaped += '\\r';
+        break;
+      case 0x27:
+        // apostrophe '
+        escaped += "\\'";
+        break;
+      case 0x5c:
+        // backslash \
+        escaped += '\\\\';
+        break;
+      default:
+        // Other control characters (U+0000-U+001F except those handled above)
+        if (codePoint <= 0x1f) {
+          escaped += `\\u${codePoint.toString(16).padStart(4, '0')}`;
+        } else {
+          escaped += char;
+        }
+    }
+  }
+  return escaped;
+};
+
+/**
+ * Creates a normalized path string from a list of selectors.
+ * Name selectors are automatically escaped.
+ *
+ * @param {Array<string|number>} selectors - Array of name selectors (strings) or index selectors (numbers)
+ * @returns {string} A normalized JSONPath string
+ * @throws {JSONNormalizedPathError} If selectors is not an array or contains invalid selector types
+ */
+export const from = selectors => {
+  if (!Array.isArray(selectors)) {
+    throw new JSONNormalizedPathError(`Selectors must be an array, got: ${typeof selectors}`, {
+      selectors
+    });
+  }
+  try {
+    const segments = selectors.map(selector => {
+      if (typeof selector === 'string') {
+        // Name selector: escape and wrap in single quotes
+        return `['${escape(selector)}']`;
+      }
+      if (typeof selector === 'number') {
+        // Index selector: must be a non-negative safe integer (RFC 9535 Section 2.1)
+        if (!Number.isSafeInteger(selector) || selector < 0) {
+          throw new TypeError(`Index selector must be a non-negative safe integer, got: ${selector}`);
+        }
+        return `[${selector}]`;
+      }
+      throw new TypeError(`Selector must be a string or non-negative integer, got: ${typeof selector}`);
+    });
+    return `$${segments.join('')}`;
+  } catch (error) {
+    throw new JSONNormalizedPathError('Failed to compile normalized JSONPath', {
+      cause: error,
+      selectors
+    });
+  }
+};
+
+/**
+ * Parses a normalized path string and returns a list of selectors.
+ *
+ * @param {string} normalizedPath - A normalized JSONPath string
+ * @returns {Array<string|number>} Array of name selectors (strings) or index selectors (numbers)
+ * @throws {JSONNormalizedPathError} If the normalized path is invalid
+ */
+export const to = normalizedPath => {
+  if (typeof normalizedPath !== 'string') {
+    throw new JSONNormalizedPathError(`Normalized path must be a string, got: ${typeof normalizedPath}`, {
+      normalizedPath
+    });
+  }
+  const parseResult = parse(normalizedPath, {
+    normalized: true
+  });
+  if (!parseResult.result.success) {
+    throw new JSONNormalizedPathError('Invalid normalized path', {
+      normalizedPath
+    });
+  }
+  const {
+    tree
+  } = parseResult;
+
+  // Extract selectors from AST segments
+  // Normalized path grammar only allows NameSelector and IndexSelector
+  // For normalized paths, segment.selector is directly the selector (not BracketedSelection)
+  return tree.segments.map(segment => segment.selector.value);
+};