@swaggerexpert/jsonpath 3.2.4 → 4.0.0

package/cjs/evaluate/evaluators/function-expr.cjs

@@ -0,0 +1,106 @@
+"use strict";
+
+exports.__esModule = true;
+exports.setLogicalExprEvaluator = exports.default = void 0;
+var _comparable = _interopRequireDefault(require("./comparable.cjs"));
+var _filterQuery = _interopRequireDefault(require("./filter-query.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Function expression evaluator.
+ *
+ * Evaluates function calls like length(@.items), match(@.name, "pattern"), etc.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+ */
+
+/**
+ * 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 (0, _comparable.default)(ctx, root, current, arg);
+    case 'FilterQuery':
+      // FilterQuery produces a nodelist (array of values)
+      return (0, _filterQuery.default)(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 (0, _filterQuery.default)(ctx, root, current, arg.expression);
+      }
+      if (arg.expression.type === 'FunctionExpr') {
+        // FunctionExpr as argument - evaluate the nested function
+        return (0, _comparable.default)(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;
+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
+ */
+exports.setLogicalExprEvaluator = setLogicalExprEvaluator;
+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);
+};
+var _default = exports.default = evaluateFunctionExpr;

package/cjs/evaluate/evaluators/literal.cjs

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

package/cjs/evaluate/evaluators/logical-expr.cjs

@@ -0,0 +1,96 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _comparisonExpr = _interopRequireDefault(require("./comparison-expr.cjs"));
+var _functionExpr = _interopRequireWildcard(require("./function-expr.cjs"));
+var _filterQuery = _interopRequireDefault(require("./filter-query.cjs"));
+var _guards = require("../utils/guards.cjs");
+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 }; }
+/**
+ * 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
+ */
+
+/**
+ * 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 = (0, _filterQuery.default)(ctx, root, current, expression);
+          return nodelist.length > 0;
+        }
+        if (expression.type === 'FunctionExpr') {
+          // Function result converted to boolean
+          const result = (0, _functionExpr.default)(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 ((0, _guards.isArray)(result)) {
+            return result.length > 0;
+          }
+          // Other ValueType: truthy check
+          return Boolean(result);
+        }
+        return false;
+      }
+    case 'ComparisonExpr':
+      {
+        return (0, _comparisonExpr.default)(ctx, root, current, node);
+      }
+    default:
+      return false;
+  }
+};
+
+// Register with function-expr to break circular dependency
+(0, _functionExpr.setLogicalExprEvaluator)(evaluateLogicalExpr);
+var _default = exports.default = evaluateLogicalExpr;

package/cjs/evaluate/evaluators/singular-query.cjs

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

package/cjs/evaluate/functions/count.cjs

@@ -0,0 +1,35 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _guards = require("../utils/guards.cjs");
+/**
+ * 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.
+ */
+
+/**
+ * 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 ((0, _guards.isNodelist)(nodelist)) {
+    return nodelist.length;
+  }
+  // Not a nodelist (NodesType): return Nothing per RFC 9535
+  return undefined;
+};
+var _default = exports.default = count;

package/cjs/evaluate/functions/index.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+exports.__esModule = true;
+exports.value = exports.search = exports.match = exports.length = exports.count = void 0;
+var _length = _interopRequireDefault(require("./length.cjs"));
+exports.length = _length.default;
+var _count = _interopRequireDefault(require("./count.cjs"));
+exports.count = _count.default;
+var _value = _interopRequireDefault(require("./value.cjs"));
+exports.value = _value.default;
+var _match = _interopRequireDefault(require("./match.cjs"));
+exports.match = _match.default;
+var _search = _interopRequireDefault(require("./search.cjs"));
+exports.search = _search.default;
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/cjs/evaluate/functions/length.cjs

@@ -0,0 +1,42 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _guards = require("../utils/guards.cjs");
+/**
+ * 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)
+ */
+
+/**
+ * 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 = (0, _guards.coerceToValueType)(value);
+
+  // Nothing returns Nothing
+  if ((0, _guards.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;
+};
+var _default = exports.default = length;

package/cjs/evaluate/functions/match.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _guards = require("../utils/guards.cjs");
+var _iRegexp = require("../utils/i-regexp.cjs");
+/**
+ * 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)$).
+ */
+
+/**
+ * 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 = (0, _guards.coerceToValueType)(value);
+  const coercedPattern = (0, _guards.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 = (0, _iRegexp.constructRegex)(strPattern, true); // anchored
+  if (regex === null) {
+    // Invalid I-Regexp pattern
+    return false;
+  }
+  return regex.test(strValue);
+};
+var _default = exports.default = match;

package/cjs/evaluate/functions/search.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _guards = require("../utils/guards.cjs");
+var _iRegexp = require("../utils/i-regexp.cjs");
+/**
+ * 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).
+ */
+
+/**
+ * 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 = (0, _guards.coerceToValueType)(value);
+  const coercedPattern = (0, _guards.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 = (0, _iRegexp.constructRegex)(strPattern, false); // not anchored
+  if (regex === null) {
+    // Invalid I-Regexp pattern
+    return false;
+  }
+  return regex.test(strValue);
+};
+var _default = exports.default = search;

package/cjs/evaluate/functions/value.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _guards = require("../utils/guards.cjs");
+/**
+ * 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)
+ */
+
+/**
+ * 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 ((0, _guards.isNodelist)(nodelist) && nodelist.length === 1) {
+    return nodelist[0];
+  }
+  // Nothing for empty nodelist, multiple values, or non-nodelist
+  return undefined;
+};
+var _default = exports.default = value;