@swaggerexpert/jsonpath 3.2.4 → 4.0.0

package/cjs/evaluate/utils/i-regexp.cjs

@@ -0,0 +1,118 @@
+"use strict";
+
+exports.__esModule = true;
+exports.constructRegex = void 0;
+/**
+ * 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
+ */
+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;
+  }
+};
+exports.constructRegex = constructRegex;

package/cjs/evaluate/visitors/bracketed-selection.cjs

@@ -0,0 +1,35 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _selector = _interopRequireDefault(require("./selector.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * 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.
+ */
+
+/**
+ * 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) {
+    (0, _selector.default)(ctx, value, selector, emit);
+  }
+};
+var _default = exports.default = visitBracketedSelection;

package/cjs/evaluate/visitors/filter-selector.cjs

@@ -0,0 +1,43 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _logicalExpr = _interopRequireDefault(require("../evaluators/logical-expr.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * 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
+ */
+
+/**
+ * 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 = (0, _logicalExpr.default)(ctx, root, child, expression);
+    if (result) {
+      emit(child, key);
+    }
+  }
+};
+var _default = exports.default = visitFilterSelector;

package/cjs/evaluate/visitors/index-selector.cjs

@@ -0,0 +1,55 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * 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
+};
+var _default = exports.default = visitIndexSelector;

package/cjs/evaluate/visitors/name-selector.cjs

@@ -0,0 +1,38 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * 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
+};
+var _default = exports.default = visitNameSelector;

package/cjs/evaluate/visitors/segment.cjs

@@ -0,0 +1,99 @@
+"use strict";
+
+exports.__esModule = true;
+exports.visitDescendantSegment = exports.visitChildSegment = exports.default = void 0;
+var _selector = _interopRequireDefault(require("./selector.cjs"));
+var _bracketedSelection = _interopRequireDefault(require("./bracketed-selection.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Segment visitor dispatcher.
+ *
+ * Handles ChildSegment and DescendantSegment types.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.5
+ */
+
+/**
+ * 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':
+      (0, _bracketedSelection.default)(ctx, value, selector, emit);
+      break;
+    case 'NameSelector':
+    case 'WildcardSelector':
+    case 'IndexSelector':
+    case 'SliceSelector':
+    case 'FilterSelector':
+      (0, _selector.default)(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
+ */
+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
+ */
+exports.visitChildSegment = visitChildSegment;
+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
+ */
+exports.visitDescendantSegment = visitDescendantSegment;
+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;
+  }
+};
+var _default = exports.default = visitSegment;

package/cjs/evaluate/visitors/selector.cjs

@@ -0,0 +1,47 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _nameSelector = _interopRequireDefault(require("./name-selector.cjs"));
+var _indexSelector = _interopRequireDefault(require("./index-selector.cjs"));
+var _wildcardSelector = _interopRequireDefault(require("./wildcard-selector.cjs"));
+var _sliceSelector = _interopRequireDefault(require("./slice-selector.cjs"));
+var _filterSelector = _interopRequireDefault(require("./filter-selector.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Selector visitor dispatcher.
+ *
+ * Routes to the appropriate selector visitor based on AST node type.
+ */
+
+/**
+ * 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':
+      (0, _nameSelector.default)(ctx, value, node, emit);
+      break;
+    case 'IndexSelector':
+      (0, _indexSelector.default)(ctx, value, node, emit);
+      break;
+    case 'WildcardSelector':
+      (0, _wildcardSelector.default)(ctx, value, node, emit);
+      break;
+    case 'SliceSelector':
+      (0, _sliceSelector.default)(ctx, value, node, emit);
+      break;
+    case 'FilterSelector':
+      (0, _filterSelector.default)(ctx, value, node, emit);
+      break;
+    default:
+      // Unknown selector type, yield nothing
+      break;
+  }
+};
+var _default = exports.default = visitSelector;

package/cjs/evaluate/visitors/slice-selector.cjs

@@ -0,0 +1,115 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * 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);
+    }
+  }
+};
+var _default = exports.default = visitSliceSelector;

package/cjs/evaluate/visitors/wildcard-selector.cjs

@@ -0,0 +1,32 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * 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);
+  }
+};
+var _default = exports.default = visitWildcardSelector;

package/cjs/index.cjs

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.test = exports.parse = exports.escape = exports.compile = exports.XMLTranslator = exports.Trace = exports.JSONPathParseError = exports.JSONPathError = exports.JSONPathCompileError = exports.Grammar = exports.CSTTranslator = exports.CSTOptimizedTranslator = exports.ASTTranslator = void 0;
+exports.test = exports.parse = exports.functions = exports.evaluate = exports.XMLTranslator = exports.Trace = exports.NormalizedPath = exports.JSONPathParseError = exports.JSONPathEvaluateError = exports.JSONPathError = exports.JSONNormalizedPathError = exports.JSONEvaluationRealm = exports.Grammar = exports.EvaluationRealm = exports.CSTTranslator = exports.CSTOptimizedTranslator = exports.ASTTranslator = void 0;
 var _grammar = _interopRequireDefault(require("./grammar.cjs"));
 exports.Grammar = _grammar.default;
 var _index = _interopRequireDefault(require("./parse/index.cjs"));
@@ -18,14 +18,23 @@ var _Trace = _interopRequireDefault(require("./parse/trace/Trace.cjs"));
 exports.Trace = _Trace.default;
 var _index3 = _interopRequireDefault(require("./test/index.cjs"));
 exports.test = _index3.default;
-var _compile = _interopRequireDefault(require("./compile.cjs"));
-exports.compile = _compile.default;
-var _escape = _interopRequireDefault(require("./escape.cjs"));
-exports.escape = _escape.default;
+var _NormalizedPath = _interopRequireWildcard(require("./normalized-path.cjs"));
+exports.NormalizedPath = _NormalizedPath;
+var _index4 = _interopRequireDefault(require("./evaluate/index.cjs"));
+exports.evaluate = _index4.default;
+var _functions = _interopRequireWildcard(require("./evaluate/functions/index.cjs"));
+exports.functions = _functions;
+var _EvaluationRealm = _interopRequireDefault(require("./evaluate/realms/EvaluationRealm.cjs"));
+exports.EvaluationRealm = _EvaluationRealm.default;
+var _index6 = _interopRequireDefault(require("./evaluate/realms/json/index.cjs"));
+exports.JSONEvaluationRealm = _index6.default;
 var _JSONPathError = _interopRequireDefault(require("./errors/JSONPathError.cjs"));
 exports.JSONPathError = _JSONPathError.default;
 var _JSONPathParseError = _interopRequireDefault(require("./errors/JSONPathParseError.cjs"));
 exports.JSONPathParseError = _JSONPathParseError.default;
-var _JSONPathCompileError = _interopRequireDefault(require("./errors/JSONPathCompileError.cjs"));
-exports.JSONPathCompileError = _JSONPathCompileError.default;
+var _JSONNormalizedPathError = _interopRequireDefault(require("./errors/JSONNormalizedPathError.cjs"));
+exports.JSONNormalizedPathError = _JSONNormalizedPathError.default;
+var _JSONPathEvaluateError = _interopRequireDefault(require("./errors/JSONPathEvaluateError.cjs"));
+exports.JSONPathEvaluateError = _JSONPathEvaluateError.default;
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }