@swaggerexpert/jsonpath 3.2.4 → 4.0.0

package/es/evaluate/index.mjs

@@ -0,0 +1,174 @@
+/**
+ * JSONPath evaluation module.
+ *
+ * Provides the evaluate() function to execute JSONPath expressions against a value.
+ * Uses an explicit stack for tree traversal to avoid call stack overflow
+ * on deeply nested documents.
+ *
+ * @module evaluate
+ * @see https://www.rfc-editor.org/rfc/rfc9535
+ */
+import parse from "../parse/index.mjs";
+import * as NormalizedPath from "../normalized-path.mjs";
+import visitSegment from "./visitors/segment.mjs";
+import JSONEvaluationRealm from "./realms/json/index.mjs";
+import JSONPathEvaluateError from "../errors/JSONPathEvaluateError.mjs";
+import * as defaultFunctions from "./functions/index.mjs";
+/**
+ * @typedef {Object} EvaluateOptions
+ * @property {Function} [callback] - Optional callback (value, normalizedPath) => void
+ *   Called for each match. Allows streaming results and collecting paths.
+ * @property {Object} [realm] - Optional custom evaluation realm.
+ *   Default is JSONEvaluationRealm for plain objects/arrays.
+ * @property {Object} [functions] - Optional custom function registry.
+ *   Can extend or override built-in functions (length, count, match, search, value).
+ */
+/**
+ * Evaluate a JSONPath expression against a value.
+ *
+ * @param {unknown} value - JSON value to query
+ * @param {string} expression - JSONPath expression
+ * @param {EvaluateOptions} [options] - Evaluation options
+ * @returns {unknown[]} - Array of matched values
+ * @throws {JSONPathEvaluateError} If the expression is invalid
+ *
+ * @example
+ * // Simple query
+ * evaluate({ a: 1, b: 2 }, '$.a');
+ * // => [1]
+ *
+ * @example
+ * // Wildcard
+ * evaluate({ store: { book: [{ title: 'A' }, { title: 'B' }] } }, '$.store.book[*].title');
+ * // => ['A', 'B']
+ *
+ * @example
+ * // With callback to collect paths
+ * const paths = [];
+ * evaluate(value, '$.store.book[*]', {
+ *   callback: (v, path) => paths.push(path)
+ * });
+ */
+const evaluate = (value, expression, {
+  callback,
+  realm = new JSONEvaluationRealm(),
+  functions = defaultFunctions
+} = {}) => {
+  // Parse the expression
+  const parseResult = parse(expression);
+  if (!parseResult.result.success) {
+    throw new JSONPathEvaluateError(`Invalid JSONPath expression: ${expression}`, {
+      expression
+    });
+  }
+  try {
+    // The tree is the AST root directly (JsonPathQuery node)
+    const ast = parseResult.tree;
+    const {
+      segments
+    } = ast;
+    const results = [];
+
+    // Handle empty query ($ with no segments)
+    if (segments.length === 0) {
+      results.push(value);
+      if (typeof callback === 'function') {
+        callback(value, '$');
+      }
+      return results;
+    }
+
+    // Evaluation context with root for filter expressions
+    const ctx = {
+      realm,
+      root: value,
+      functions
+    };
+    const stack = [];
+
+    // Start with root value
+    stack.push({
+      value,
+      path: [],
+      segmentIndex: 0
+    });
+    while (stack.length > 0) {
+      const item = stack.pop();
+      const {
+        value,
+        path,
+        segmentIndex
+      } = item;
+
+      // If all segments processed, emit result
+      if (segmentIndex >= segments.length) {
+        const normalizedPath = NormalizedPath.from(path);
+        results.push(value);
+        if (typeof callback === 'function') {
+          callback(value, normalizedPath);
+        }
+        continue;
+      }
+      const segment = segments[segmentIndex];
+
+      // Collect results from this segment
+      const segmentResults = [];
+      const emit = (selectedValue, pathSegment) => {
+        segmentResults.push({
+          value: selectedValue,
+          pathSegment
+        });
+      };
+
+      // Apply segment
+      visitSegment(ctx, value, segment, emit);
+
+      // For descendant segments, also push children for recursive descent
+      // Push descendants FIRST so they're processed AFTER current level results (LIFO)
+      if (segment.type === 'DescendantSegment') {
+        const descendants = [];
+        for (const [key, child] of realm.entries(value)) {
+          descendants.push({
+            value: child,
+            pathSegment: key
+          });
+        }
+
+        // Push descendants (in reverse for correct order)
+        // They stay at same segment index to continue recursive descent
+        for (let i = descendants.length - 1; i >= 0; i -= 1) {
+          const {
+            value: descendantValue,
+            pathSegment
+          } = descendants[i];
+          stack.push({
+            value: descendantValue,
+            path: [...path, pathSegment],
+            segmentIndex // Same segment for recursive descent
+          });
+        }
+      }
+
+      // Push results for next segment (in reverse order for correct output order)
+      // Push these AFTER descendants so they're processed FIRST (LIFO = document order)
+      for (let i = segmentResults.length - 1; i >= 0; i -= 1) {
+        const {
+          value: selectedValue,
+          pathSegment
+        } = segmentResults[i];
+        stack.push({
+          value: selectedValue,
+          path: [...path, pathSegment],
+          segmentIndex: segmentIndex + 1
+        });
+      }
+    }
+    return results;
+  } catch (error) {
+    throw new JSONPathEvaluateError('Unexpected error during JSONPath evaluation', {
+      cause: error,
+      expression
+    });
+  }
+};
+export default evaluate;

package/es/evaluate/realms/EvaluationRealm.mjs

@@ -0,0 +1,148 @@
+/**
+ * Abstract base class for Evaluation Realms.
+ *
+ * Evaluation Realms provide an abstraction for accessing different data structures,
+ * allowing JSONPath evaluation to work with various data types.
+ *
+ * Subclasses must implement all abstract methods.
+ */
+import JSONPathError from "../../errors/JSONPathError.mjs";
+class EvaluationRealm {
+  name = '';
+
+  /**
+   * Check if value is object (has named properties).
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isObject(value) {
+    throw new JSONPathError('Realm.isObject(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Check if value is array (has indexed elements).
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isArray(value) {
+    throw new JSONPathError('Realm.isArray(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Check if value is string.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isString(value) {
+    throw new JSONPathError('Realm.isString(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Check if value is number.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isNumber(value) {
+    throw new JSONPathError('Realm.isNumber(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Check if value is boolean.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isBoolean(value) {
+    throw new JSONPathError('Realm.isBoolean(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Check if value is null.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isNull(value) {
+    throw new JSONPathError('Realm.isNull(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Get raw string value for regex operations.
+   * @param {unknown} value
+   * @returns {string | undefined}
+   */
+  getString(value) {
+    throw new JSONPathError('Realm.getString(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Get property by name from object value.
+   * @param {unknown} value
+   * @param {string} key
+   * @returns {unknown}
+   */
+  getProperty(value, key) {
+    throw new JSONPathError('Realm.getProperty(value, key) must be implemented in a subclass');
+  }
+
+  /**
+   * Check if object value has property.
+   * @param {unknown} value
+   * @param {string} key
+   * @returns {boolean}
+   */
+  hasProperty(value, key) {
+    throw new JSONPathError('Realm.hasProperty(value, key) must be implemented in a subclass');
+  }
+
+  /**
+   * Get element by index from array value.
+   * @param {unknown} value
+   * @param {number} index
+   * @returns {unknown}
+   */
+  getElement(value, index) {
+    throw new JSONPathError('Realm.getElement(value, index) must be implemented in a subclass');
+  }
+
+  /**
+   * Get all keys of object value.
+   * @param {unknown} value
+   * @returns {string[]}
+   */
+  getKeys(value) {
+    throw new JSONPathError('Realm.getKeys(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Get length of array or object value.
+   * @param {unknown} value
+   * @returns {number}
+   */
+  getLength(value) {
+    throw new JSONPathError('Realm.getLength(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Iterate over entries as [key/index, value] pairs.
+   * For objects: yields [key, value] for each member.
+   * For arrays: yields [index, value] for each element.
+   * For other types: yields nothing.
+   * @param {unknown} value
+   * @returns {Iterable<[string | number, unknown]>}
+   */
+  *entries(value) {
+    throw new JSONPathError('Realm.entries(value) must be implemented in a subclass');
+  }
+
+  /**
+   * Compare two values using the specified operator.
+   * Per RFC 9535 Section 2.3.5.2.3.
+   * @param {unknown} left
+   * @param {string} operator - One of: ==, !=, <, <=, >, >=
+   * @param {unknown} right
+   * @returns {boolean}
+   */
+  compare(left, operator, right) {
+    throw new JSONPathError('Realm.compare(left, operator, right) must be implemented in a subclass');
+  }
+}
+export default EvaluationRealm;

package/es/evaluate/realms/json/index.mjs

@@ -0,0 +1,240 @@
+/**
+ * JSON Evaluation Realm for plain JavaScript objects and arrays.
+ */
+import EvaluationRealm from "../EvaluationRealm.mjs";
+import { isPlainObject, isArray, isNothing, isString, isNumber, isBoolean, isNull } from "../../utils/guards.mjs";
+/**
+ * JSON Evaluation Realm implementation.
+ */
+class JSONEvaluationRealm extends EvaluationRealm {
+  name = 'json';
+
+  /**
+   * Check if value is object (plain object with named properties).
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isObject(value) {
+    return isPlainObject(value);
+  }
+
+  /**
+   * Check if value is array.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isArray(value) {
+    return isArray(value);
+  }
+
+  /**
+   * Check if value is string.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isString(value) {
+    return isString(value);
+  }
+
+  /**
+   * Check if value is number.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isNumber(value) {
+    return isNumber(value);
+  }
+
+  /**
+   * Check if value is boolean.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isBoolean(value) {
+    return isBoolean(value);
+  }
+
+  /**
+   * Check if value is null.
+   * @param {unknown} value
+   * @returns {boolean}
+   */
+  isNull(value) {
+    return isNull(value);
+  }
+
+  /**
+   * Get raw string value for regex operations.
+   * @param {unknown} value
+   * @returns {string | undefined}
+   */
+  getString(value) {
+    return isString(value) ? value : undefined;
+  }
+
+  /**
+   * Get property by name from object value.
+   * Returns undefined if property doesn't exist (Nothing).
+   * @param {unknown} value
+   * @param {string} key
+   * @returns {unknown}
+   */
+  getProperty(value, key) {
+    if (!isPlainObject(value)) return undefined;
+    return Object.hasOwn(value, key) ? value[key] : undefined;
+  }
+
+  /**
+   * Check if object value has property.
+   * @param {unknown} value
+   * @param {string} key
+   * @returns {boolean}
+   */
+  hasProperty(value, key) {
+    if (!isPlainObject(value)) return false;
+    return Object.hasOwn(value, key);
+  }
+
+  /**
+   * Get element by index from array value.
+   * Returns undefined if index out of bounds (Nothing).
+   * @param {unknown} value
+   * @param {number} index
+   * @returns {unknown}
+   */
+  getElement(value, index) {
+    if (!isArray(value)) return undefined;
+    if (index < 0 || index >= value.length) return undefined;
+    return value[index];
+  }
+
+  /**
+   * Get all keys of object value.
+   * @param {unknown} value
+   * @returns {string[]}
+   */
+  getKeys(value) {
+    if (!isPlainObject(value)) return [];
+    return Object.keys(value);
+  }
+
+  /**
+   * Get length of value.
+   * Per RFC 9535 Section 2.4.5:
+   * - String: number of Unicode scalar values (not UTF-16 code units)
+   * - Array: number of elements
+   * - Object: number of members
+   * @param {unknown} value
+   * @returns {number}
+   */
+  getLength(value) {
+    if (isString(value)) return [...value].length;
+    if (isArray(value)) return value.length;
+    if (isPlainObject(value)) return Object.keys(value).length;
+    return 0;
+  }
+
+  /**
+   * Iterate over entries as [key/index, value] pairs.
+   * For objects: yields [key, value] for each member.
+   * For arrays: yields [index, value] for each element.
+   * For other types: yields nothing.
+   * @param {unknown} value
+   * @returns {Iterable<[string | number, unknown]>}
+   */
+  *entries(value) {
+    if (this.isArray(value)) {
+      for (let i = 0; i < value.length; i += 1) {
+        yield [i, value[i]];
+      }
+    } else if (this.isObject(value)) {
+      for (const key of Object.keys(value)) {
+        yield [key, value[key]];
+      }
+    }
+  }
+
+  /**
+   * Deep equality check for JSON values.
+   * @param {unknown} a
+   * @param {unknown} b
+   * @returns {boolean}
+   */
+  #deepEqual(a, b) {
+    // Primitive comparison
+    if (a === b) return true;
+
+    // Nothing comparison
+    if (isNothing(a) && isNothing(b)) return true;
+    if (isNothing(a) || isNothing(b)) return false;
+
+    // Null comparison
+    if (isNull(a) && isNull(b)) return true;
+    if (isNull(a) || isNull(b)) return false;
+
+    // Type must match for complex types
+    if (typeof a !== typeof b) return false;
+
+    // Array comparison
+    if (isArray(a) && isArray(b)) {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i += 1) {
+        if (!this.#deepEqual(a[i], b[i])) return false;
+      }
+      return true;
+    }
+
+    // Object comparison
+    if (isPlainObject(a) && isPlainObject(b)) {
+      const keysA = Object.keys(a);
+      const keysB = Object.keys(b);
+      if (keysA.length !== keysB.length) return false;
+      for (const key of keysA) {
+        if (!Object.hasOwn(b, key)) return false;
+        if (!this.#deepEqual(a[key], b[key])) return false;
+      }
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Compare two values using the specified operator.
+   * Per RFC 9535 Section 2.3.5.2.3.
+   * @param {unknown} left
+   * @param {string} operator - One of: ==, !=, <, <=, >, >=
+   * @param {unknown} right
+   * @returns {boolean}
+   */
+  compare(left, operator, right) {
+    switch (operator) {
+      case '==':
+        return this.#deepEqual(left, right);
+      case '!=':
+        return !this.#deepEqual(left, right);
+      case '<':
+        if (isNothing(left) || isNothing(right)) return false;
+        if (isNumber(left) && isNumber(right)) return left < right;
+        if (isString(left) && isString(right)) return left < right;
+        return false;
+      case '<=':
+        if (isNothing(left) || isNothing(right)) return false;
+        if (isNumber(left) && isNumber(right)) return left <= right;
+        if (isString(left) && isString(right)) return left <= right;
+        return this.#deepEqual(left, right);
+      case '>':
+        if (isNothing(left) || isNothing(right)) return false;
+        if (isNumber(left) && isNumber(right)) return left > right;
+        if (isString(left) && isString(right)) return left > right;
+        return false;
+      case '>=':
+        if (isNothing(left) || isNothing(right)) return false;
+        if (isNumber(left) && isNumber(right)) return left >= right;
+        if (isString(left) && isString(right)) return left >= right;
+        return this.#deepEqual(left, right);
+      default:
+        return false;
+    }
+  }
+}
+export default JSONEvaluationRealm;

package/es/evaluate/utils/guards.mjs

@@ -0,0 +1,114 @@
+/**
+ * Type guards for JSON value types.
+ */
+
+const objectTag = '[object Object]';
+
+/**
+ * Check if value is an array.
+ * @param {unknown} value
+ * @returns {value is unknown[]}
+ */
+export const isArray = value => Array.isArray(value);
+
+/**
+ * Check if value is an object (not null, not array).
+ * @param {unknown} value
+ * @returns {value is object}
+ */
+export const isObject = value => typeof value === 'object' && value !== null && !isArray(value);
+
+/**
+ * Check if value is a plain object (created by Object constructor or object literal).
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export const isPlainObject = value => {
+  if (!isObject(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) return true;
+  return proto.constructor === Object && Object.prototype.toString.call(value) === objectTag;
+};
+
+/**
+ * Check if value is a string.
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export const isString = value => typeof value === 'string';
+
+/**
+ * Check if value is a number.
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export const isNumber = value => typeof value === 'number' && Number.isFinite(value);
+
+/**
+ * Check if value is a boolean.
+ * @param {unknown} value
+ * @returns {value is boolean}
+ */
+export const isBoolean = value => typeof value === 'boolean';
+
+/**
+ * Check if value is null.
+ * @param {unknown} value
+ * @returns {value is null}
+ */
+export const isNull = value => value === null;
+
+/**
+ * Check if value represents Nothing (undefined).
+ * Per RFC 9535, Nothing is used when a query returns no value.
+ * We use undefined since JSON has no undefined value.
+ * @param {unknown} value
+ * @returns {value is undefined}
+ */
+export const isNothing = value => value === undefined;
+
+/**
+ * Check if value is a valid JSON value.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export const isJsonValue = value => {
+  if (isNull(value) || isBoolean(value) || isString(value) || isNumber(value)) {
+    return true;
+  }
+  if (isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  if (isPlainObject(value)) {
+    return Object.values(value).every(isJsonValue);
+  }
+  return false;
+};
+
+/**
+ * Check if value is a nodelist (marked array from filter query).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export const isNodelist = value => isArray(value) && value._isNodelist === true;
+
+/**
+ * Coerce a nodelist to a single value (ValueType).
+ * Per RFC 9535 Section 2.4.1: if function expects ValueType and receives NodesType,
+ * auto-convert: single node -> that node's value, otherwise -> Nothing.
+ *
+ * @param {unknown} value - Input value (may be a nodelist)
+ * @returns {unknown} - Coerced value or Nothing (undefined)
+ */
+export const coerceToValueType = value => {
+  if (isNodelist(value)) {
+    // Single node: unwrap and return value
+    if (value.length === 1) {
+      return value[0];
+    }
+    // Empty or multiple nodes: return Nothing
+    return undefined;
+  }
+  // Not a nodelist, return as-is
+  return value;
+};