@swaggerexpert/jsonpath 3.2.5 → 4.0.0

package/README.md

@@ -7,7 +7,7 @@
 [![try on RunKit](https://img.shields.io/badge/try%20on-RunKit-brightgreen.svg?style=flat)](https://npm.runkit.com/@swaggerexpert/jsonpath)
 [![Tidelift](https://tidelift.com/badges/package/npm/@swaggerexpert%2Fjsonpath)](https://tidelift.com/subscription/pkg/npm-.swaggerexpert-jsonpath?utm_source=npm-swaggerexpert-jsonpath&utm_medium=referral&utm_campaign=readme)
 
-`@swaggerexpert/jsonpath` is a **parser** and **validator** for [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) Query Expressions for JSON - **JSONPath**.
+`@swaggerexpert/jsonpath` is a **parser**, **validator**, **compiler**, and **evaluator** for [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) Query Expressions for JSON - **JSONPath**.
 
 The development of this library contributed to the identification and formal submission of following **erratas** against the RFC 9535:
 - [Errata ID: 8343](https://www.rfc-editor.org/errata/eid8343)
@@ -15,6 +15,8 @@ The development of this library contributed to the identification and formal sub
 - [Errata ID: 8353](https://www.rfc-editor.org/errata/eid8353)
 - [Errata ID: 8354](https://www.rfc-editor.org/errata/eid8354)
 
+This library is **100% compliant** with the [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite).
+
 <table>
   <tr>
     <td align="right" valign="middle">
@@ -43,11 +45,16 @@ The development of this library contributed to the identification and formal sub
       - [Statistics](#statistics)
       - [Tracing](#tracing)
     - [Validation](#validation)
-    - [Compilation](#compilation)
-    - [Escaping](#escaping)
+    - [Normalized paths](#normalized-paths-1)
+    - [Evaluation](#evaluation)
+      - [Collecting normalized paths](#collecting-normalized-paths)
+      - [Built-in functions](#built-in-functions)
+      - [Custom functions](#custom-functions)
+      - [Evaluation realms](#evaluation-realms)
     - [Errors](#errors)
     - [Grammar](#grammar)
 - [More about JSONPath](#more-about-jsonpath)
+- [Setting up for development](#setting-up-for-development)
 - [License](#license)
 
 ## Getting started
@@ -62,8 +69,8 @@ You can install `@swaggerexpert/jsonpath` using `npm`:
 
 ### Usage
 
-`@swaggerexpert/jsonpath` currently supports **parsing** and **validation**.
-Both parser and validator are based on a superset of [ABNF](https://www.rfc-editor.org/rfc/rfc5234) ([SABNF](https://cs.github.com/ldthomas/apg-js2/blob/master/SABNF.md))
+`@swaggerexpert/jsonpath` supports **parsing**, **validation**, **compilation**, and **evaluation** of JSONPath expressions.
+The parser and validator are based on a superset of [ABNF](https://www.rfc-editor.org/rfc/rfc5234) ([SABNF](https://cs.github.com/ldthomas/apg-js2/blob/master/SABNF.md))
 and use [apg-lite](https://github.com/ldthomas/apg-lite) parser generator.
 
 #### Parsing
@@ -229,39 +236,224 @@ test("$['a']", { normalized: true }); // => true
 test('$.store.book[0].title', { normalized: true }); // => false
 ```
 
-#### Compilation
+**Well-typedness validation** is enabled by default and validates the JSONPath expression against [RFC 9535 type system rules](https://www.rfc-editor.org/rfc/rfc9535#section-2.4.9)
+(e.g., function argument types, return type usage). Set `wellTyped` option to `false` to perform syntax-only validation.
+
+```js
+import { test } from '@swaggerexpert/jsonpath';
+
+test('$[?length(@.*) < 3]'); // => false (non-singular query for ValueType parameter)
+test('$[?length(@.*) < 3]', { wellTyped: false }); // => true (syntax is valid)
+```
+
+#### Normalized paths
+
+The `NormalizedPath` namespace provides utilities for working with [Normalized Paths](https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths).
 
-Compilation is the process of transforming a list of selectors into a [Normalized Path](https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths).
-During compilation, name selectors are automatically escaped before being compiled.
+##### NormalizedPath.test
+
+Tests if a string is a valid normalized JSONPath. This is a convenience wrapper around `test(path, { normalized: true })`.
 
 ```js
-import { compile } from '@swaggerexpert/jsonpath';
+import { NormalizedPath } from '@swaggerexpert/jsonpath';
+
+NormalizedPath.test("$['a']"); // => true
+NormalizedPath.test('$[0]'); // => true
+NormalizedPath.test("$['store']['book'][0]['title']"); // => true
+NormalizedPath.test('$.a'); // => false (dot notation not allowed)
+NormalizedPath.test('$["a"]'); // => false (double quotes not allowed)
+NormalizedPath.test('$[*]'); // => false (wildcard not allowed)
+```
 
-compile(['store', 'book', 0, 'title']); // => "$['store']['book'][0]['title']"
+##### NormalizedPath.from
+
+Creates a normalized path string from a list of selectors. Name selectors are automatically escaped.
+
+```js
+import { NormalizedPath } from '@swaggerexpert/jsonpath';
+
+NormalizedPath.from(['store', 'book', 0, 'title']); // => "$['store']['book'][0]['title']"
+NormalizedPath.from(["it's"]); // => "$['it\\'s']"
 ```
 
-#### Escaping
+##### NormalizedPath.to
+
+Parses a normalized path string and returns a list of selectors.
+
+```js
+import { NormalizedPath } from '@swaggerexpert/jsonpath';
+
+NormalizedPath.to("$['store']['book'][0]['title']"); // => ['store', 'book', 0, 'title']
+NormalizedPath.to("$['it\\'s']"); // => ["it's"]
+```
 
-Certain characters within name selectors in Normalized Paths require escaping.
+##### NormalizedPath.escape
+
+Escapes special characters in name selectors for use in normalized paths.
 The apostrophe (`'`) and backslash (`\`) characters must be escaped.
 Control characters (U+0000 through U+001F) are escaped using specific escape sequences
 (`\b`, `\t`, `\n`, `\f`, `\r`) or Unicode escape sequences (`\uXXXX`).
 
 ```js
-import { escape } from '@swaggerexpert/jsonpath';
+import { NormalizedPath } from '@swaggerexpert/jsonpath';
+
+NormalizedPath.escape("it's"); // => "it\\'s"
+NormalizedPath.escape('back\\slash'); // => "back\\\\slash"
+NormalizedPath.escape('line\nfeed'); // => "line\\nfeed"
+```
+
+#### Evaluation
+
+Evaluation is the process of applying a JSONPath expression against a JSON value to produce a nodelist (array of matched values).
+Per [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535#section-2.1), evaluation begins with the root value (`$`) and processes each
+segment sequentially, producing a nodelist of all matching values.
+
+```js
+import { evaluate } from '@swaggerexpert/jsonpath';
+
+const value = {
+  store: {
+    book: [
+      { title: 'A', price: 10 },
+      { title: 'B', price: 20 }
+    ]
+  }
+};
+
+evaluate(value, '$.store.book[*].title'); // => ['A', 'B']
+evaluate(value, '$.store.book[0]'); // => [{ title: 'A', price: 10 }]
+evaluate(value, '$.store.book[?@.price > 15]'); // => [{ title: 'B', price: 20 }]
+```
+
+##### Collecting normalized paths
+
+Use the `callback` option to collect [normalized paths](https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths) alongside matched values:
+
+```js
+import { evaluate } from '@swaggerexpert/jsonpath';
+
+const value = { store: { book: [{ title: 'A' }, { title: 'B' }] } };
+const paths = [];
+
+evaluate(value, '$.store.book[*].title', {
+  callback: (v, path) => paths.push(path)
+});
+// paths => ["$['store']['book'][0]['title']", "$['store']['book'][1]['title']"]
+```
+
+##### Built-in functions
+
+The evaluation engine includes all [RFC 9535 Section 2.4](https://www.rfc-editor.org/rfc/rfc9535#section-2.4) functions:
+
+| Function | Description |
+|----------|-------------|
+| `length(value)` | Returns the length of a string, array, or object |
+| `count(nodelist)` | Returns the number of nodes in a nodelist |
+| `match(string, regex)` | Tests if a string matches an I-Regexp pattern (full match) |
+| `search(string, regex)` | Tests if a string contains an I-Regexp pattern |
+| `value(nodelist)` | Extracts a single value from a nodelist |
+
+```js
+import { evaluate } from '@swaggerexpert/jsonpath';
+
+const value = { items: ['short', 'very long string', 'medium'] };
+
+evaluate(value, '$.items[?length(@) > 5]'); // => ['very long string', 'medium']
+evaluate(value, '$.items[?match(@, "^v.*")]'); // => ['very long string']
+```
 
-escape("it's"); // => "it\\'s"
-escape('back\\slash'); // => "back\\\\slash"
-escape('line\nfeed'); // => "line\\nfeed"
+##### Custom functions
+
+Extend or override built-in functions via the `functions` option:
+
+```js
+import { evaluate, functions } from '@swaggerexpert/jsonpath';
+
+const customFunctions = {
+  ...functions,
+  min: (ctx, args) => {
+    const values = args[0];
+    if (!Array.isArray(values)) return undefined;
+    return Math.min(...values);
+  }
+};
+
+const value = { numbers: [3, 1, 4, 1, 5] };
+evaluate(value, '$[?min($.numbers) == 1]', { functions: customFunctions });
+```
+
+##### Evaluation realms
+
+Evaluation realms provide an abstraction layer for accessing different data structures during JSONPath evaluation.
+By default, the evaluation engine uses the **JSON Evaluation Realm** which works with plain JavaScript objects and arrays.
+
+###### JSON Evaluation Realm
+
+By default, the evaluation operates under the **JSON realm**, which assumes that:
+
+- **Arrays** are indexed numerically
+- **Objects** (plain JavaScript objects) are accessed by string keys
+
+```js
+import { evaluate } from '@swaggerexpert/jsonpath';
+
+const value = { store: { book: [{ title: 'A' }] } };
+evaluate(value, '$.store.book[*].title'); // => ['A']
+```
+
+The default realm can also be specified explicitly:
+
+```js
+import { evaluate, JSONEvaluationRealm } from '@swaggerexpert/jsonpath';
+
+const value = { store: { book: [{ title: 'A' }] } };
+evaluate(value, '$.store.book[*].title', { realm: new JSONEvaluationRealm() }); // => ['A']
+```
+
+###### Custom Evaluation Realms
+
+You can create custom evaluation realms to work with different data structures (e.g., Immutable.js, ApiDOM elements).
+Extend the `EvaluationRealm` base class and implement the required methods:
+
+| Method | Description |
+|--------|-------------|
+| `isObject(value)` | Check if value is an object (has named properties) |
+| `isArray(value)` | Check if value is an array (has indexed elements) |
+| `isString(value)` | Check if value is a string |
+| `isNumber(value)` | Check if value is a number |
+| `isBoolean(value)` | Check if value is a boolean |
+| `isNull(value)` | Check if value is null |
+| `getString(value)` | Get raw string value for regex operations |
+| `getProperty(value, key)` | Get property by name from object |
+| `hasProperty(value, key)` | Check if object has property |
+| `getElement(value, index)` | Get element by index from array |
+| `getKeys(value)` | Get all keys of object |
+| `getLength(value)` | Get length of string, array, or object |
+| `entries(value)` | Iterate over [key/index, value] pairs |
+| `compare(left, op, right)` | Compare two values using operator (==, !=, <, <=, >, >=) |
+
+```js
+import { evaluate, EvaluationRealm } from '@swaggerexpert/jsonpath';
+
+class CustomRealm extends EvaluationRealm {
+  name = 'custom';
+
+  isObject(value) { /* ... */ }
+  isArray(value) { /* ... */ }
+  // ... implement all required methods
+}
+
+const value = { /* ... */ };
+evaluate(value, '$.path', { realm: new CustomRealm() });
 ```
 
 #### Errors
 
 `@swaggerexpert/jsonpath` provides a structured error class hierarchy,
-enabling precise error handling across JSONPath operations, including parsing and compilation.
+enabling precise error handling across JSONPath operations, including parsing, compilation, and evaluation.
 
 ```js
-import { JSONPathError, JSONPathParseError, JSONPathCompileError } from '@swaggerexpert/jsonpath';
+import { JSONPathError, JSONPathParseError, JSONNormalizedPathError, JSONPathEvaluateError } from '@swaggerexpert/jsonpath';
 ```
 
 **JSONPathError** is the base class for all JSONPath errors.
@@ -530,6 +722,21 @@ disjunction         = "||"
 conjunction         = "&&"
 ```
 
+## Setting up for development
+
+```sh
+ # Clone with submodules (recommended)
+ $ git clone --recurse-submodules https://github.com/swaggerexpert/jsonpath.git
+
+ # Or initialize submodules after cloning
+ $ git submodule update --init
+
+ # Install dependencies
+ $ npm install
+```
+
+The project uses the [JSONPath Compliance Test Suite](https://github.com/jsonpath-standard/jsonpath-compliance-test-suite) as a git submodule for testing.
+
 ## License
 
 `@swaggerexpert/jsonpath` is licensed under [Apache 2.0 license](https://github.com/swaggerexpert/jsonpath/blob/main/LICENSE).

package/cjs/errors/JSONNormalizedPathError.cjs

@@ -0,0 +1,8 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _JSONPathError = _interopRequireDefault(require("./JSONPathError.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class JSONNormalizedPathError extends _JSONPathError.default {}
+var _default = exports.default = JSONNormalizedPathError;

package/cjs/errors/JSONPathError.cjs

@@ -19,7 +19,7 @@ class JSONPathError extends Error {
      * This needs to stay here until our minimum supported version of Node.js is >= 16.9.0.
      * Node.js is >= 16.9.0 supports error causes natively.
      */
-    if (options != null && typeof options === 'object' && Object.prototype.hasOwnProperty.call(options, 'cause') && !('cause' in this)) {
+    if (options != null && typeof options === 'object' && Object.hasOwn(options, 'cause') && !('cause' in this)) {
       const {
         cause
       } = options;

package/cjs/errors/{JSONPathCompileError.cjs → JSONPathEvaluateError.cjs}

@@ -4,5 +4,5 @@ exports.__esModule = true;
 exports.default = void 0;
 var _JSONPathError = _interopRequireDefault(require("./JSONPathError.cjs"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-class JSONPathCompileError extends _JSONPathError.default {}
-var _default = exports.default = JSONPathCompileError;
+class JSONPathEvaluateError extends _JSONPathError.default {}
+var _default = exports.default = JSONPathEvaluateError;

package/cjs/evaluate/evaluators/comparable.cjs

@@ -0,0 +1,44 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _literal = _interopRequireDefault(require("./literal.cjs"));
+var _singularQuery = require("./singular-query.cjs");
+var _functionExpr = _interopRequireDefault(require("./function-expr.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Comparable evaluator.
+ *
+ * Evaluates comparables which can be:
+ * - Literal (string, number, boolean, null)
+ * - RelSingularQuery (@.path)
+ * - AbsSingularQuery ($.path)
+ * - FunctionExpr (function call)
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.2.2
+ */
+
+/**
+ * Evaluate a comparable expression.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - Comparable AST node
+ * @returns {unknown} - Evaluated value
+ */
+const evaluateComparable = (ctx, root, current, node) => {
+  switch (node.type) {
+    case 'Literal':
+      return (0, _literal.default)(ctx, root, current, node);
+    case 'RelSingularQuery':
+      return (0, _singularQuery.evaluateRelSingularQuery)(ctx, root, current, node);
+    case 'AbsSingularQuery':
+      return (0, _singularQuery.evaluateAbsSingularQuery)(ctx, root, current, node);
+    case 'FunctionExpr':
+      return (0, _functionExpr.default)(ctx, root, current, node);
+    default:
+      return undefined;
+  }
+};
+var _default = exports.default = evaluateComparable;

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

@@ -0,0 +1,37 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _comparable = _interopRequireDefault(require("./comparable.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Comparison expression evaluator.
+ *
+ * Evaluates comparison expressions like @.price < 10, @.name == "foo", etc.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.2.3
+ */
+
+/**
+ * Evaluate a comparison expression.
+ *
+ * @param {object} ctx - Evaluation context
+ * @param {unknown} root - Root value ($)
+ * @param {unknown} current - Current value (@)
+ * @param {object} node - ComparisonExpr AST node
+ * @param {object} node.left - Left comparable
+ * @param {string} node.op - Comparison operator (==, !=, <, <=, >, >=)
+ * @param {object} node.right - Right comparable
+ * @returns {boolean} - Comparison result
+ */
+const evaluateComparisonExpr = (ctx, root, current, node) => {
+  const {
+    left,
+    op,
+    right
+  } = node;
+  const leftValue = (0, _comparable.default)(ctx, root, current, left);
+  const rightValue = (0, _comparable.default)(ctx, root, current, right);
+  return ctx.realm.compare(leftValue, op, rightValue);
+};
+var _default = exports.default = evaluateComparisonExpr;

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

@@ -0,0 +1,182 @@
+"use strict";
+
+exports.__esModule = true;
+exports.evaluateRelQuery = exports.evaluateJsonPathQuery = exports.default = void 0;
+var _selector = _interopRequireDefault(require("../visitors/selector.cjs"));
+var _bracketedSelection = _interopRequireDefault(require("../visitors/bracketed-selection.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * 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
+ */
+
+/**
+ * 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':
+      (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;
+  }
+  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
+ */
+exports.evaluateRelQuery = evaluateRelQuery;
+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
+ */
+exports.evaluateJsonPathQuery = evaluateJsonPathQuery;
+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);
+};
+var _default = exports.default = evaluateFilterQuery;