@swaggerexpert/jsonpath 3.2.5 → 4.0.0

package/es/evaluate/evaluators/filter-query.mjs

@@ -0,0 +1,175 @@
+/**
+ * Filter query evaluator.
+ *
+ * Evaluates FilterQuery expressions which contain either:
+ * - RelQuery (@.path) - relative to current node
+ * - JsonPathQuery ($.path) - absolute from root
+ *
+ * Returns a nodelist (array of matched values).
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.2.1
+ */
+import visitSelector from "../visitors/selector.mjs";
+import visitBracketedSelection from "../visitors/bracketed-selection.mjs";
+/**
+ * Apply a segment to a value and collect all results.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} segment - Segment AST node
+ * @returns {unknown[]} - Array of matched values
+ */
+const applySegment = (ctx, value, segment) => {
+  const results = [];
+  const emit = selectedValue => {
+    results.push(selectedValue);
+  };
+  const {
+    selector
+  } = segment;
+  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;
+  }
+  return results;
+};
+
+/**
+ * Apply segments to get nodelist, supporting descendant segments.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown[]} values - Current nodelist
+ * @param {object[]} segments - Remaining segments
+ * @returns {unknown[]} - Result nodelist
+ */
+const applySegments = (ctx, root, values, segments) => {
+  let current = values;
+  for (const segment of segments) {
+    const next = [];
+    if (segment.type === 'DescendantSegment') {
+      // Descendant segment: apply to current and all descendants
+      const collectDescendants = value => {
+        const {
+          realm
+        } = ctx;
+        // Apply selector at current level
+        const results = applySegment(ctx, value, segment);
+        next.push(...results);
+
+        // Recurse into children
+        for (const [, child] of realm.entries(value)) {
+          collectDescendants(child);
+        }
+      };
+      for (const value of current) {
+        collectDescendants(value);
+      }
+    } else {
+      // Child segment: apply to current values only
+      for (const value of current) {
+        const results = applySegment(ctx, value, segment);
+        next.push(...results);
+      }
+    }
+    current = next;
+  }
+  return current;
+};
+
+/**
+ * Evaluate a RelQuery (@.path).
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - RelQuery AST node
+ * @returns {unknown[]} - Nodelist of matched values
+ */
+const evaluateRelQuery = (ctx, root, current, node) => {
+  const {
+    segments
+  } = node;
+  if (segments.length === 0) {
+    // @ with no segments returns current as single-element nodelist
+    return [current];
+  }
+  return applySegments(ctx, root, [current], segments);
+};
+
+/**
+ * Evaluate a JsonPathQuery ($.path).
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (unused)
+ * @param {object} node - JsonPathQuery AST node
+ * @returns {unknown[]} - Nodelist of matched values
+ */
+const evaluateJsonPathQuery = (ctx, root, current, node) => {
+  const {
+    segments
+  } = node;
+  if (segments.length === 0) {
+    // $ with no segments returns root as single-element nodelist
+    return [root];
+  }
+  return applySegments(ctx, root, [root], segments);
+};
+
+/**
+ * Mark an array as a nodelist.
+ * This helps functions distinguish nodelists from array values.
+ *
+ * @param {unknown[]} arr - Array to mark
+ * @returns {unknown[]} - Marked array
+ */
+const markAsNodelist = arr => {
+  Object.defineProperty(arr, '_isNodelist', {
+    value: true,
+    enumerable: false,
+    writable: false
+  });
+  return arr;
+};
+
+/**
+ * Evaluate a FilterQuery.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - FilterQuery AST node
+ * @returns {unknown[]} - Nodelist of matched values
+ */
+const evaluateFilterQuery = (ctx, root, current, node) => {
+  const {
+    query
+  } = node;
+  let result;
+  switch (query.type) {
+    case 'RelQuery':
+      result = evaluateRelQuery(ctx, root, current, query);
+      break;
+    case 'JsonPathQuery':
+      result = evaluateJsonPathQuery(ctx, root, current, query);
+      break;
+    default:
+      result = [];
+  }
+
+  // Mark result as a nodelist so functions can handle type coercion
+  return markAsNodelist(result);
+};
+export default evaluateFilterQuery;
+export { evaluateRelQuery, evaluateJsonPathQuery };

package/es/evaluate/evaluators/function-expr.mjs

@@ -0,0 +1,99 @@
+/**
+ * Function expression evaluator.
+ *
+ * Evaluates function calls like length(@.items), match(@.name, "pattern"), etc.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+ */
+import evaluateComparable from "./comparable.mjs";
+import evaluateFilterQuery from "./filter-query.mjs";
+/**
+ * Evaluate a function argument.
+ * Arguments can be:
+ * - Literals
+ * - Singular queries (@.path, $.path)
+ * - Filter queries (for NodesType parameters)
+ * - Function expressions (nested calls)
+ * - Logical expressions (for LogicalType parameters)
+ *
+ * Special case: When a TestExpr contains only a FilterQuery,
+ * we evaluate it as a nodelist (for functions like count() that expect NodesType).
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} arg - Argument AST node
+ * @returns {unknown} - Evaluated argument value
+ */
+const evaluateArgument = (ctx, root, current, arg) => {
+  switch (arg.type) {
+    case 'Literal':
+    case 'RelSingularQuery':
+    case 'AbsSingularQuery':
+    case 'FunctionExpr':
+      return evaluateComparable(ctx, root, current, arg);
+    case 'FilterQuery':
+      // FilterQuery produces a nodelist (array of values)
+      return evaluateFilterQuery(ctx, root, current, arg);
+    case 'TestExpr':
+      // TestExpr can contain FilterQuery (for NodesType/ValueType) or FunctionExpr
+      if (arg.expression.type === 'FilterQuery') {
+        // Always return the nodelist - functions handle type coercion internally
+        // Per RFC 9535 Section 2.4.1: if a function expects ValueType and gets NodesType,
+        // it auto-converts (single node -> value, otherwise -> Nothing)
+        return evaluateFilterQuery(ctx, root, current, arg.expression);
+      }
+      if (arg.expression.type === 'FunctionExpr') {
+        // FunctionExpr as argument - evaluate the nested function
+        return evaluateComparable(ctx, root, current, arg.expression);
+      }
+      // Otherwise evaluate as logical expression
+      // eslint-disable-next-line no-use-before-define
+      return evaluateLogicalExpr(ctx, root, current, arg);
+    case 'LogicalOrExpr':
+    case 'LogicalAndExpr':
+    case 'LogicalNotExpr':
+    case 'ComparisonExpr':
+      // Import dynamically to avoid circular dependency
+      // eslint-disable-next-line no-use-before-define
+      return evaluateLogicalExpr(ctx, root, current, arg);
+    default:
+      return undefined;
+  }
+};
+
+// Lazy import to avoid circular dependency
+let evaluateLogicalExpr;
+export const setLogicalExprEvaluator = fn => {
+  evaluateLogicalExpr = fn;
+};
+
+/**
+ * Evaluate a function expression.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - AST node
+ * @param {string} node.name - Function name
+ * @param {object[]} node.arguments - Array of argument AST nodes
+ * @returns {unknown} - Function result
+ */
+const evaluateFunctionExpr = (ctx, root, current, node) => {
+  const {
+    name,
+    arguments: args
+  } = node;
+  const fn = ctx.functions[name];
+  if (typeof fn !== 'function') {
+    // Unknown function returns Nothing
+    return undefined;
+  }
+
+  // Evaluate all arguments
+  const evaluatedArgs = args.map(arg => evaluateArgument(ctx, root, current, arg));
+
+  // Call the function with realm and evaluated arguments
+  return fn(ctx.realm, ...evaluatedArgs);
+};
+export default evaluateFunctionExpr;

package/es/evaluate/evaluators/literal.mjs

@@ -0,0 +1,21 @@
+/**
+ * Literal evaluator.
+ *
+ * Evaluates a literal value (string, number, boolean, null).
+ * Literals appear in comparisons and function arguments.
+ */
+
+/**
+ * Evaluate a literal AST node.
+ *
+ * @param {object} ctx - Evaluation context (unused for literals)
+ * @param {unknown} root - Root value (unused for literals)
+ * @param {unknown} current - Current value (unused for literals)
+ * @param {object} node - AST node
+ * @param {unknown} node.value - The literal value
+ * @returns {unknown} - The literal value
+ */
+const evaluateLiteral = (ctx, root, current, node) => {
+  return node.value;
+};
+export default evaluateLiteral;

package/es/evaluate/evaluators/logical-expr.mjs

@@ -0,0 +1,89 @@
+/**
+ * Logical expression evaluator.
+ *
+ * Evaluates logical expressions:
+ * - LogicalOrExpr (||)
+ * - LogicalAndExpr (&&)
+ * - LogicalNotExpr (!)
+ * - TestExpr (existence test or function result)
+ * - ComparisonExpr (routed to comparison evaluator)
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.2
+ */
+import evaluateComparisonExpr from "./comparison-expr.mjs";
+import evaluateFunctionExpr, { setLogicalExprEvaluator } from "./function-expr.mjs";
+import evaluateFilterQuery from "./filter-query.mjs";
+import { isArray } from "../utils/guards.mjs";
+/**
+ * Evaluate a logical expression.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - Logical expression AST node
+ * @returns {boolean} - Logical result
+ */
+const evaluateLogicalExpr = (ctx, root, current, node) => {
+  switch (node.type) {
+    case 'LogicalOrExpr':
+      {
+        // Short-circuit OR
+        const left = evaluateLogicalExpr(ctx, root, current, node.left);
+        if (left) return true;
+        return evaluateLogicalExpr(ctx, root, current, node.right);
+      }
+    case 'LogicalAndExpr':
+      {
+        // Short-circuit AND
+        const left = evaluateLogicalExpr(ctx, root, current, node.left);
+        if (!left) return false;
+        return evaluateLogicalExpr(ctx, root, current, node.right);
+      }
+    case 'LogicalNotExpr':
+      {
+        return !evaluateLogicalExpr(ctx, root, current, node.expression);
+      }
+    case 'TestExpr':
+      {
+        // TestExpr wraps a FilterQuery or FunctionExpr
+        const {
+          expression
+        } = node;
+        if (expression.type === 'FilterQuery') {
+          // Existence test: true if nodelist is non-empty
+          const nodelist = evaluateFilterQuery(ctx, root, current, expression);
+          return nodelist.length > 0;
+        }
+        if (expression.type === 'FunctionExpr') {
+          // Function result converted to boolean
+          const result = evaluateFunctionExpr(ctx, root, current, expression);
+          // LogicalType functions return boolean directly
+          // ValueType functions: undefined (Nothing) is false, truthy values are true
+          if (typeof result === 'boolean') {
+            return result;
+          }
+          // Nothing is false
+          if (result === undefined) {
+            return false;
+          }
+          // NodesType (array): non-empty is true
+          if (isArray(result)) {
+            return result.length > 0;
+          }
+          // Other ValueType: truthy check
+          return Boolean(result);
+        }
+        return false;
+      }
+    case 'ComparisonExpr':
+      {
+        return evaluateComparisonExpr(ctx, root, current, node);
+      }
+    default:
+      return false;
+  }
+};
+
+// Register with function-expr to break circular dependency
+setLogicalExprEvaluator(evaluateLogicalExpr);
+export default evaluateLogicalExpr;

package/es/evaluate/evaluators/singular-query.mjs

@@ -0,0 +1,97 @@
+/**
+ * Singular query evaluator.
+ *
+ * Evaluates RelSingularQuery (@.path) and AbsSingularQuery ($.path) expressions.
+ * These appear in comparison expressions within filters.
+ *
+ * A singular query can only contain name selectors and index selectors,
+ * ensuring it produces at most one value.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.2.2
+ */
+
+/**
+ * Apply a singular query segment (name or index selector).
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} value - Current value
+ * @param {object} segment - Segment AST node
+ * @returns {unknown} - Selected value or undefined (Nothing)
+ */
+const applySingularSegment = (ctx, value, segment) => {
+  const {
+    realm
+  } = ctx;
+  const {
+    selector
+  } = segment;
+  switch (selector.type) {
+    case 'NameSelector':
+      {
+        const {
+          value: name
+        } = selector;
+        if (realm.isObject(value) && realm.hasProperty(value, name)) {
+          return realm.getProperty(value, name);
+        }
+        return undefined; // Nothing
+      }
+    case 'IndexSelector':
+      {
+        const {
+          value: index
+        } = selector;
+        if (!realm.isArray(value)) return undefined;
+        const length = realm.getLength(value);
+        const normalizedIndex = index >= 0 ? index : length + index;
+        if (normalizedIndex >= 0 && normalizedIndex < length) {
+          return realm.getElement(value, normalizedIndex);
+        }
+        return undefined; // Nothing
+      }
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Evaluate a RelSingularQuery (@.path).
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value (unused)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - AST node
+ * @param {object[]} node.segments - Array of singular query segments
+ * @returns {unknown} - Result value or undefined (Nothing)
+ */
+export const evaluateRelSingularQuery = (ctx, root, current, node) => {
+  let value = current;
+  for (const segment of node.segments) {
+    value = applySingularSegment(ctx, value, segment);
+    if (value === undefined) {
+      return undefined; // Nothing - short circuit
+    }
+  }
+  return value;
+};
+
+/**
+ * Evaluate an AbsSingularQuery ($.path).
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (unused)
+ * @param {object} node - AST node
+ * @param {object[]} node.segments - Array of singular query segments
+ * @returns {unknown} - Result value or undefined (Nothing)
+ */
+export const evaluateAbsSingularQuery = (ctx, root, current, node) => {
+  let value = root;
+  for (const segment of node.segments) {
+    value = applySingularSegment(ctx, value, segment);
+    if (value === undefined) {
+      return undefined; // Nothing - short circuit
+    }
+  }
+  return value;
+};

package/es/evaluate/functions/count.mjs

@@ -0,0 +1,30 @@
+/**
+ * RFC 9535 count() function.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.4
+ *
+ * Parameters:
+ *   NodesType (nodelist)
+ *
+ * Returns:
+ *   ValueType (number)
+ *
+ * Result:
+ *   The number of nodes in the nodelist.
+ */
+import { isNodelist } from "../utils/guards.mjs";
+/**
+ * Count the number of nodes in a nodelist.
+ *
+ * @param {object} realm - Evaluation realm (unused, for consistent signature)
+ * @param {unknown} nodelist - A nodelist (array of values)
+ * @returns {number} - Number of nodes
+ */
+const count = (realm, nodelist) => {
+  if (isNodelist(nodelist)) {
+    return nodelist.length;
+  }
+  // Not a nodelist (NodesType): return Nothing per RFC 9535
+  return undefined;
+};
+export default count;

package/es/evaluate/functions/index.mjs

@@ -0,0 +1,13 @@
+/**
+ * RFC 9535 built-in functions.
+ *
+ * All functions defined in RFC 9535 Section 2.4.
+ * Can be extended or overridden via the `functions` option in evaluate().
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+ */
+export { default as length } from "./length.mjs";
+export { default as count } from "./count.mjs";
+export { default as value } from "./value.mjs";
+export { default as match } from "./match.mjs";
+export { default as search } from "./search.mjs";

package/es/evaluate/functions/length.mjs

@@ -0,0 +1,37 @@
+/**
+ * RFC 9535 length() function.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.5
+ *
+ * Parameters:
+ *   ValueType (single value)
+ *
+ * Returns:
+ *   ValueType (number or Nothing)
+ *
+ * Result:
+ *   - String: number of Unicode scalar values (not UTF-16 code units)
+ *   - Array: number of elements
+ *   - Object: number of members (key-value pairs)
+ *   - Other: Nothing (undefined)
+ */
+import { coerceToValueType, isNothing } from "../utils/guards.mjs";
+/**
+ * Get the length of a value.
+ *
+ * @param {object} realm - Evaluation realm
+ * @param {unknown} value - The value to measure (may be a nodelist)
+ * @returns {number | undefined} - Length or Nothing (undefined)
+ */
+const length = (realm, value) => {
+  // Coerce nodelist to single value if needed
+  const coerced = coerceToValueType(value);
+
+  // Nothing returns Nothing
+  if (isNothing(coerced)) return undefined;
+
+  // Use realm to get length (handles strings, arrays, objects)
+  const len = realm.getLength(coerced);
+  return len > 0 || realm.isString(coerced) || realm.isArray(coerced) || realm.isObject(coerced) ? len : undefined;
+};
+export default length;

package/es/evaluate/functions/match.mjs

@@ -0,0 +1,44 @@
+/**
+ * RFC 9535 match() function.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.1
+ *
+ * Parameters:
+ *   ValueType (string), ValueType (I-Regexp pattern string)
+ *
+ * Returns:
+ *   LogicalType (boolean)
+ *
+ * Result:
+ *   true if the entire string matches the I-Regexp pattern, false otherwise.
+ *   The pattern is implicitly anchored (^(?:pattern)$).
+ */
+import { coerceToValueType } from "../utils/guards.mjs";
+import { constructRegex } from "../utils/i-regexp.mjs";
+/**
+ * Test if entire string matches I-Regexp pattern.
+ *
+ * @param {object} realm - Evaluation realm
+ * @param {unknown} value - The string to test (may be a nodelist)
+ * @param {unknown} pattern - The I-Regexp pattern (may be a nodelist)
+ * @returns {boolean} - true if entire string matches
+ */
+const match = (realm, value, pattern) => {
+  // Coerce nodelists to single values
+  const coercedValue = coerceToValueType(value);
+  const coercedPattern = coerceToValueType(pattern);
+
+  // Get raw string values from realm
+  const strValue = realm.getString(coercedValue);
+  const strPattern = realm.getString(coercedPattern);
+  if (strValue === undefined || strPattern === undefined) {
+    return false;
+  }
+  const regex = constructRegex(strPattern, true); // anchored
+  if (regex === null) {
+    // Invalid I-Regexp pattern
+    return false;
+  }
+  return regex.test(strValue);
+};
+export default match;

package/es/evaluate/functions/search.mjs

@@ -0,0 +1,44 @@
+/**
+ * RFC 9535 search() function.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.2
+ *
+ * Parameters:
+ *   ValueType (string), ValueType (I-Regexp pattern string)
+ *
+ * Returns:
+ *   LogicalType (boolean)
+ *
+ * Result:
+ *   true if any substring matches the I-Regexp pattern, false otherwise.
+ *   The pattern is not anchored (can match anywhere in string).
+ */
+import { coerceToValueType } from "../utils/guards.mjs";
+import { constructRegex } from "../utils/i-regexp.mjs";
+/**
+ * Test if any substring matches I-Regexp pattern.
+ *
+ * @param {object} realm - Evaluation realm
+ * @param {unknown} value - The string to search (may be a nodelist)
+ * @param {unknown} pattern - The I-Regexp pattern (may be a nodelist)
+ * @returns {boolean} - true if any substring matches
+ */
+const search = (realm, value, pattern) => {
+  // Coerce nodelists to single values
+  const coercedValue = coerceToValueType(value);
+  const coercedPattern = coerceToValueType(pattern);
+
+  // Get raw string values from realm
+  const strValue = realm.getString(coercedValue);
+  const strPattern = realm.getString(coercedPattern);
+  if (strValue === undefined || strPattern === undefined) {
+    return false;
+  }
+  const regex = constructRegex(strPattern, false); // not anchored
+  if (regex === null) {
+    // Invalid I-Regexp pattern
+    return false;
+  }
+  return regex.test(strValue);
+};
+export default search;

package/es/evaluate/functions/value.mjs

@@ -0,0 +1,31 @@
+/**
+ * RFC 9535 value() function.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4.7
+ *
+ * Parameters:
+ *   NodesType (nodelist)
+ *
+ * Returns:
+ *   ValueType (the single value or Nothing)
+ *
+ * Result:
+ *   - If nodelist has exactly one node: that node's value
+ *   - Otherwise: Nothing (undefined)
+ */
+import { isNodelist } from "../utils/guards.mjs";
+/**
+ * Extract the single value from a nodelist.
+ *
+ * @param {object} realm - Evaluation realm (unused, for consistent signature)
+ * @param {unknown} nodelist - A nodelist (array of values)
+ * @returns {unknown} - The single value or Nothing (undefined)
+ */
+const value = (realm, nodelist) => {
+  if (isNodelist(nodelist) && nodelist.length === 1) {
+    return nodelist[0];
+  }
+  // Nothing for empty nodelist, multiple values, or non-nodelist
+  return undefined;
+};
+export default value;