@swaggerexpert/jsonpath 3.2.5 → 4.0.0

package/es/parse/callbacks/cst.mjs

@@ -2,13 +2,12 @@ import { utilities, identifiers } from 'apg-lite';
 import JSONPathParseError from "../../errors/JSONPathParseError.mjs";
 const cst = nodeType => {
   return (state, chars, phraseIndex, phraseLength, data) => {
-    var _data$options, _data$options2;
     if (!(typeof data === 'object' && data !== null && !Array.isArray(data))) {
       throw new JSONPathParseError("parser's user data must be an object");
     }
 
     // drop the empty nodes
-    if ((_data$options = data.options) !== null && _data$options !== void 0 && _data$options.optimize && phraseLength === 0 && (_data$options2 = data.options) !== null && _data$options2 !== void 0 && (_data$options2 = _data$options2.droppableTypes) !== null && _data$options2 !== void 0 && _data$options2.includes(nodeType)) {
+    if (data.options?.optimize && phraseLength === 0 && data.options?.droppableTypes?.includes(nodeType)) {
       return;
     }
     if (state === identifiers.SEM_PRE) {
@@ -20,11 +19,10 @@ const cst = nodeType => {
         children: []
       };
       if (data.stack.length > 0) {
-        var _data$options3, _data$options4;
         const parent = data.stack[data.stack.length - 1];
         const prevSibling = parent.children[parent.children.length - 1];
         const isTextNodeWithinTextNode = parent.type === 'text' && node.type === 'text';
-        const shouldCollapse = ((_data$options3 = data.options) === null || _data$options3 === void 0 ? void 0 : _data$options3.optimize) && ((_data$options4 = data.options) === null || _data$options4 === void 0 || (_data$options4 = _data$options4.collapsibleTypes) === null || _data$options4 === void 0 ? void 0 : _data$options4.includes(node.type)) && (prevSibling === null || prevSibling === void 0 ? void 0 : prevSibling.type) === node.type;
+        const shouldCollapse = data.options?.optimize && data.options?.collapsibleTypes?.includes(node.type) && prevSibling?.type === node.type;
         if (shouldCollapse) {
           prevSibling.text += node.text;
           prevSibling.length += node.length;

package/es/parse/index.mjs

@@ -27,7 +27,9 @@ const parse = (jsonPath, {
       trace: parser.trace
     };
   } catch (error) {
-    throw new JSONPathParseError('Unexpected error during JSONPath parsing', {
+    // Provide specific error message for semantic validation errors
+    const message = error instanceof RangeError ? `Invalid JSONPath expression: ${error.message}` : 'Unexpected error during JSONPath parsing';
+    throw new JSONPathParseError(message, {
       cause: error,
       jsonPath
     });

package/es/parse/translators/ASTTranslator/index.mjs

@@ -3,7 +3,7 @@ import { transformCSTtoAST, default as transformers } from "./transformers.mjs";
 class ASTTranslator extends CSTOptimizedTranslator {
   getTree() {
     const cst = super.getTree();
-    return transformCSTtoAST(cst.root, transformers);
+    return transformCSTtoAST(cst, transformers);
   }
 }
 export default ASTTranslator;

package/es/parse/translators/ASTTranslator/transformers.mjs

@@ -1,5 +1,203 @@
 import JSONPathParseError from "../../../errors/JSONPathParseError.mjs";
 import { decodeSingleQuotedString, decodeDoubleQuotedString, decodeInteger, decodeJSONValue } from "./decoders.mjs";
+/**
+ * RFC 9535 function type signatures.
+ * @see https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+ */
+const FUNCTION_SIGNATURES = {
+  // count(NodesType) -> ValueType
+  count: {
+    params: [{
+      type: 'NodesType'
+    }],
+    returns: 'ValueType'
+  },
+  // length(ValueType) -> ValueType
+  length: {
+    params: [{
+      type: 'ValueType'
+    }],
+    returns: 'ValueType'
+  },
+  // value(NodesType) -> ValueType
+  value: {
+    params: [{
+      type: 'NodesType'
+    }],
+    returns: 'ValueType'
+  },
+  // match(ValueType, ValueType) -> LogicalType
+  match: {
+    params: [{
+      type: 'ValueType'
+    }, {
+      type: 'ValueType'
+    }],
+    returns: 'LogicalType'
+  },
+  // search(ValueType, ValueType) -> LogicalType
+  search: {
+    params: [{
+      type: 'ValueType'
+    }, {
+      type: 'ValueType'
+    }],
+    returns: 'LogicalType'
+  }
+};
+
+/**
+ * Check if an AST node represents a singular query.
+ * Singular queries use only name selectors and index selectors.
+ */
+const isSingularQueryAST = node => {
+  if (node.type !== 'FilterQuery') return false;
+  const {
+    query
+  } = node;
+  if (!query || !query.segments) return false;
+  for (const segment of query.segments) {
+    if (segment.type !== 'ChildSegment') return false;
+    const {
+      selector
+    } = segment;
+    if (selector.type !== 'NameSelector' && selector.type !== 'IndexSelector') {
+      // Check for BracketedSelection with single NameSelector or IndexSelector
+      if (selector.type === 'BracketedSelection') {
+        if (selector.selectors.length !== 1) return false;
+        const inner = selector.selectors[0];
+        if (inner.type !== 'NameSelector' && inner.type !== 'IndexSelector') {
+          return false;
+        }
+      } else {
+        return false;
+      }
+    }
+  }
+  return true;
+};
+
+/**
+ * Check if argument type matches expected parameter type.
+ */
+const checkArgumentType = (argAST, expectedType, funcName) => {
+  if (expectedType === 'NodesType') {
+    // NodesType requires a filter-query (non-singular)
+    // Literals and singular queries are NOT NodesType
+    if (argAST.type === 'Literal') {
+      throw new RangeError(`Function ${funcName}() requires NodesType argument, got literal`);
+    }
+    if (argAST.type === 'TestExpr' && argAST.expression?.type === 'FilterQuery') {
+      // This is a filter query wrapped in TestExpr - valid NodesType
+      return;
+    }
+    if (argAST.type === 'FilterQuery') {
+      // Direct filter query - valid NodesType
+      return;
+    }
+    // Other types are not valid NodesType
+    throw new RangeError(`Function ${funcName}() requires NodesType argument`);
+  }
+  if (expectedType === 'ValueType') {
+    // ValueType accepts: literals, singular queries, function expressions
+    if (argAST.type === 'Literal') return;
+    if (argAST.type === 'FunctionExpr') return;
+
+    // TestExpr containing FunctionExpr - valid if function returns ValueType
+    if (argAST.type === 'TestExpr' && argAST.expression?.type === 'FunctionExpr') {
+      // Function expressions that return ValueType are valid
+      // Unknown functions are allowed (they return Nothing at runtime)
+      return;
+    }
+
+    // TestExpr containing FilterQuery - check if singular
+    if (argAST.type === 'TestExpr' && argAST.expression?.type === 'FilterQuery') {
+      if (!isSingularQueryAST(argAST.expression)) {
+        throw new RangeError(`Function ${funcName}() requires ValueType argument, got non-singular query`);
+      }
+      return;
+    }
+
+    // FilterQuery - check if singular
+    if (argAST.type === 'FilterQuery') {
+      if (!isSingularQueryAST(argAST)) {
+        throw new RangeError(`Function ${funcName}() requires ValueType argument, got non-singular query`);
+      }
+      return;
+    }
+
+    // LogicalExpr types are not ValueType
+    throw new RangeError(`Function ${funcName}() requires ValueType argument`);
+  }
+};
+
+/**
+ * Get the return type of an expression AST node.
+ *
+ * @param {object} node - AST node
+ * @returns {string | null} - 'LogicalType', 'ValueType', 'NodesType', or null for unknown
+ */
+const getExpressionReturnType = node => {
+  if (!node) return null;
+
+  // Function expressions return based on signature
+  if (node.type === 'FunctionExpr') {
+    const signature = FUNCTION_SIGNATURES[node.name];
+    return signature ? signature.returns : null;
+  }
+
+  // Literals are ValueType
+  if (node.type === 'Literal') {
+    return 'ValueType';
+  }
+
+  // Singular queries return ValueType
+  if (node.type === 'RelSingularQuery' || node.type === 'AbsSingularQuery') {
+    return 'ValueType';
+  }
+
+  // Filter queries return NodesType
+  if (node.type === 'FilterQuery') {
+    return 'NodesType';
+  }
+
+  // Logical expressions return LogicalType
+  if (node.type === 'LogicalOrExpr' || node.type === 'LogicalAndExpr' || node.type === 'LogicalNotExpr' || node.type === 'ComparisonExpr') {
+    return 'LogicalType';
+  }
+
+  // TestExpr: depends on what it wraps
+  if (node.type === 'TestExpr') {
+    return getExpressionReturnType(node.expression);
+  }
+  return null;
+};
+
+/**
+ * Validate function call against its type signature.
+ */
+const validateFunctionCall = (funcName, argASTs) => {
+  const signature = FUNCTION_SIGNATURES[funcName];
+  if (!signature) {
+    // Unknown function - no validation (will return Nothing at runtime)
+    return;
+  }
+
+  // Check argument count
+  const expectedCount = signature.params.length;
+  const actualCount = argASTs.length;
+  if (actualCount < expectedCount) {
+    throw new RangeError(`Function ${funcName}() requires ${expectedCount} argument(s), got ${actualCount}`);
+  }
+  if (actualCount > expectedCount) {
+    throw new RangeError(`Function ${funcName}() requires ${expectedCount} argument(s), got ${actualCount}`);
+  }
+
+  // Check argument types
+  for (let i = 0; i < expectedCount; i++) {
+    checkArgumentType(argASTs[i], signature.params[i].type, funcName);
+  }
+};
 export const transformCSTtoAST = (node, transformerMap, ctx = {
   parent: null,
   path: []
@@ -118,9 +316,31 @@ const transformers = {
     const child = node.children.find(({
       type
     }) => type === 'logical-expr');
+    const expressionAST = transformCSTtoAST(child, transformers, ctx);
+
+    // Validate: ValueType functions cannot be used as existence tests
+    // Per RFC 9535 Section 2.4.9: "Type error: ValueType not TestExpr"
+    // This only applies when the top-level expression is a TestExpr
+    // containing a function that returns ValueType
+    if (expressionAST.type === 'TestExpr') {
+      const innerType = getExpressionReturnType(expressionAST.expression);
+      if (innerType === 'ValueType') {
+        const funcName = expressionAST.expression.type === 'FunctionExpr' ? expressionAST.expression.name : 'expression';
+        throw new RangeError(`Function ${funcName}() returns ValueType which cannot be used as existence test; result must be compared`);
+      }
+    }
+    // Also check for LogicalNotExpr wrapping TestExpr (for negated existence tests)
+    if (expressionAST.type === 'LogicalNotExpr' && expressionAST.expression?.type === 'TestExpr') {
+      const innerExpr = expressionAST.expression.expression;
+      const innerType = getExpressionReturnType(innerExpr);
+      if (innerType === 'ValueType') {
+        const funcName = innerExpr.type === 'FunctionExpr' ? innerExpr.name : 'expression';
+        throw new RangeError(`Function ${funcName}() returns ValueType which cannot be used as existence test; result must be compared`);
+      }
+    }
     return {
       type: 'FilterSelector',
-      expression: transformCSTtoAST(child, transformers, ctx)
+      expression: expressionAST
     };
   },
   ['logical-expr'](node, ctx) {
@@ -147,6 +367,7 @@ const transformers = {
         right
       };
     }
+    return left;
   },
   ['logical-and-expr'](node, ctx) {
     const basicExprs = node.children.filter(({
@@ -191,9 +412,10 @@ const transformers = {
     const expression = node.children.find(({
       type
     }) => ['filter-query', 'function-expr'].includes(type));
+    const expressionAST = transformCSTtoAST(expression, transformers, ctx);
     const testExpr = {
       type: 'TestExpr',
-      expression: transformCSTtoAST(expression, transformers, ctx)
+      expression: expressionAST
     };
     return isNegated ? {
       type: 'LogicalNotExpr',
@@ -221,11 +443,26 @@ const transformers = {
       type
     }) => ['comparable', 'comparison-op'].includes(type));
     const [left, op, right] = children;
+    const leftAST = transformCSTtoAST(left, transformers, ctx);
+    const rightAST = transformCSTtoAST(right, transformers, ctx);
+
+    // Validate: LogicalType functions cannot be used in comparisons
+    // Per RFC 9535 Section 2.4.9: "Type error: no compare to LogicalType"
+    const leftType = getExpressionReturnType(leftAST);
+    const rightType = getExpressionReturnType(rightAST);
+    if (leftType === 'LogicalType') {
+      const funcName = leftAST.type === 'FunctionExpr' ? leftAST.name : 'expression';
+      throw new RangeError(`Function ${funcName}() returns LogicalType which cannot be compared`);
+    }
+    if (rightType === 'LogicalType') {
+      const funcName = rightAST.type === 'FunctionExpr' ? rightAST.name : 'expression';
+      throw new RangeError(`Function ${funcName}() returns LogicalType which cannot be compared`);
+    }
     return {
       type: 'ComparisonExpr',
-      left: transformCSTtoAST(left, transformers, ctx),
+      left: leftAST,
       op: op.text,
-      right: transformCSTtoAST(right, transformers, ctx)
+      right: rightAST
     };
   },
   ['literal'](node, ctx) {
@@ -308,10 +545,14 @@ const transformers = {
     const args = node.children.filter(({
       type
     }) => type === 'function-argument');
+    const argASTs = args.map(arg => transformCSTtoAST(arg, transformers, ctx));
+
+    // Validate function call against type signature
+    validateFunctionCall(name.text, argASTs);
     return {
       type: 'FunctionExpr',
       name: name.text,
-      arguments: args.map(arg => transformCSTtoAST(arg, transformers, ctx))
+      arguments: argASTs
     };
   },
   ['function-argument'](node, ctx) {

package/es/parse/translators/CSTOptimizedTranslator.mjs

@@ -26,9 +26,7 @@ class CSTOptimizedTranslator extends CSTTranslator {
       options
     };
     this.translate(data);
-    delete data.stack;
-    delete data.options;
-    return data;
+    return data.root;
   }
 }
 export default CSTOptimizedTranslator;

package/es/parse/translators/CSTTranslator.mjs

@@ -106,8 +106,7 @@ class CSTTranslator extends AST {
       root: null
     };
     this.translate(data);
-    delete data.stack;
-    return data;
+    return data.root;
   }
 }
 export default CSTTranslator;

package/es/test/index.mjs

@@ -1,6 +1,8 @@
 import parse from "../parse/index.mjs";
+import ASTTranslator from "../parse/translators/ASTTranslator/index.mjs";
 const test = (jsonPath, {
-  normalized = false
+  normalized = false,
+  wellTyped = true
 } = {}) => {
   if (typeof jsonPath !== 'string') return false;
   try {
@@ -10,7 +12,7 @@ const test = (jsonPath, {
       normalized,
       stats: false,
       trace: false,
-      translator: null
+      translator: wellTyped ? new ASTTranslator() : null
     });
     return result.success;
   } catch {

package/package.json

@@ -5,7 +5,7 @@
     "registry": "https://registry.npmjs.org",
     "provenance": true
   },
-  "version": "3.2.5",
+  "version": "4.0.0",
   "description": "RFC 9535 implementation of JSONPath",
   "main": "./cjs/index.cjs",
   "types": "./types/index.d.ts",
@@ -32,7 +32,7 @@
     "watch": "npm-watch"
   },
   "engines": {
-    "node": ">=12.20.0"
+    "node": ">=16.14.0"
   },
   "type": "module",
   "repository": {
@@ -43,6 +43,8 @@
     "jsonpath",
     "parser",
     "validator",
+    "compiler",
+    "evaluator",
     "rfc9535"
   ],
   "author": "Vladimír Gorej <vladimir.gorej@gmail.com>",

package/types/index.d.ts

@@ -16,8 +16,8 @@ export interface Translator<TTree = unknown> {
 export declare class CSTTranslator implements Translator<CSTTree> {
   getTree(): CSTTree;
 }
-export declare class CSTOptimizedTranslator implements CSTTranslator {
-  constructor(options?: { collapsibleTypes?: string[] });
+export declare class CSTOptimizedTranslator extends CSTTranslator {
+  constructor(options?: { collapsibleTypes?: string[]; droppableTypes?: string[] });
   getTree(): CSTTree;
 }
 export declare class ASTTranslator implements Translator<ASTTree> {
@@ -51,16 +51,13 @@ export interface CSTNode {
   readonly children: CSTNode[],
 }
 
-export interface CSTTree {
-  readonly root: CSTNode;
-}
+export type CSTTree = CSTNode;
 
 export type XMLTree = string;
 
 /* AST Tree start */
-export interface ASTTree {
-  readonly root: JSONPathQueryASTNode;
-}
+export type ASTTree = JSONPathQueryASTNode;
+
 export interface ASTNode {
   readonly type:
     | 'JSONPathQuery'
@@ -231,9 +228,110 @@ export interface TestOptions {
 }
 
 /**
- * Compiling
+ * Normalized Paths
+ */
+export namespace NormalizedPath {
+  /**
+   * Tests if a string is a valid normalized JSONPath.
+   */
+  function test(normalizedPath: string): boolean;
+
+  /**
+   * Creates a normalized path string from a list of selectors.
+   * Name selectors are automatically escaped.
+   */
+  function from(selectors: (string | number)[]): string;
+
+  /**
+   * Parses a normalized path string and returns a list of selectors.
+   */
+  function to(normalizedPath: string): (string | number)[];
+
+  /**
+   * Escapes special characters in name selectors for use in normalized paths.
+   */
+  function escape(value: string): string;
+}
+
+/**
+ * Evaluation
+ */
+export function evaluate<T = unknown>(data: unknown, expression: string, options?: EvaluateOptions): T[];
+
+export interface EvaluateOptions {
+  /**
+   * Callback function called for each match.
+   * Receives the matched value and its normalized path.
+   */
+  readonly callback?: (value: unknown, normalizedPath: string) => void;
+  /**
+   * Custom evaluation realm for different data structures.
+   * Default is JSON realm for plain objects/arrays.
+   */
+  readonly realm?: EvaluationRealmInterface;
+  /**
+   * Custom function registry.
+   * Can extend or override built-in functions.
+   */
+  readonly functions?: Record<string, Function>;
+}
+
+/**
+ * Evaluation realm interface for custom data structures.
+ * Implement this to evaluate JSONPath on Immutable.js, ApiDOM, etc.
  */
-export function compile(selectors: (string | number)[]): string;
+export interface EvaluationRealmInterface {
+  name?: string;
+  isObject(value: unknown): boolean;
+  isArray(value: unknown): boolean;
+  isString(value: unknown): boolean;
+  isNumber(value: unknown): boolean;
+  isBoolean(value: unknown): boolean;
+  isNull(value: unknown): boolean;
+  getString(value: unknown): string | undefined;
+  getProperty(value: unknown, key: string): unknown;
+  hasProperty(value: unknown, key: string): boolean;
+  getElement(value: unknown, index: number): unknown;
+  getKeys(value: unknown): string[];
+  getLength(value: unknown): number;
+  entries(value: unknown): Iterable<[string | number, unknown]>;
+  compare(left: unknown, operator: '==' | '!=' | '<' | '<=' | '>' | '>=', right: unknown): boolean;
+}
+
+/**
+ * Built-in evaluation functions.
+ */
+export const functions: Record<string, Function>;
+
+/**
+ * Base class for evaluation realms.
+ * Extend this class to create custom evaluation realms.
+ */
+export declare class EvaluationRealm implements EvaluationRealmInterface {
+  name: string;
+  isObject(value: unknown): boolean;
+  isArray(value: unknown): boolean;
+  isString(value: unknown): boolean;
+  isNumber(value: unknown): boolean;
+  isBoolean(value: unknown): boolean;
+  isNull(value: unknown): boolean;
+  getString(value: unknown): string | undefined;
+  getProperty(value: unknown, key: string): unknown;
+  hasProperty(value: unknown, key: string): boolean;
+  getElement(value: unknown, index: number): unknown;
+  getKeys(value: unknown): string[];
+  getLength(value: unknown): number;
+  entries(value: unknown): Iterable<[string | number, unknown]>;
+  compare(left: unknown, operator: '==' | '!=' | '<' | '<=' | '>' | '>=', right: unknown): boolean;
+}
+
+/**
+ * JSON Evaluation Realm for plain JavaScript objects and arrays.
+ * This is the default realm used by the evaluate function.
+ */
+export declare class JSONEvaluationRealm extends EvaluationRealm {
+  name: 'json';
+}
 
 /**
  * Errors
@@ -248,12 +346,17 @@ export interface JSONPathErrorOptions {
   [key: string]: unknown;
 }
 
-export declare class JSONPathCompileError extends JSONPathError {
+export declare class JSONNormalizedPathError extends JSONPathError {
   selectors?: (string | number)[];
+  normalizedPath?: string;
 }
 
 export declare class JSONPathParseError extends JSONPathError {}
 
+export declare class JSONPathEvaluateError extends JSONPathError {
+  expression?: string;
+}
+
 /**
  * Grammar
  */

package/cjs/compile.cjs

@@ -1,50 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-var _escape = _interopRequireDefault(require("./escape.cjs"));
-var _JSONPathCompileError = _interopRequireDefault(require("./errors/JSONPathCompileError.cjs"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/**
- * Compiles an array of selectors into a normalized JSONPath.
- * Follows RFC 9535 Section 2.7 normalized path format.
- *
- * @param {Array<string|number>} selectors - Array of name selectors (strings) or index selectors (numbers)
- * @returns {string} A normalized JSONPath string
- * @throws {JSONPathCompileError} If selectors is not an array or contains invalid selector types
- *
- * @example
- * compile(['a', 'b', 1]) // returns "$['a']['b'][1]"
- * compile([]) // returns "$"
- * compile(['foo', 0, 'bar']) // returns "$['foo'][0]['bar']"
- */
-const compile = selectors => {
-  if (!Array.isArray(selectors)) {
-    throw new _JSONPathCompileError.default(`Selectors must be an array, got: ${typeof selectors}`, {
-      selectors
-    });
-  }
-  try {
-    const segments = selectors.map(selector => {
-      if (typeof selector === 'string') {
-        // Name selector: escape and wrap in single quotes
-        return `['${(0, _escape.default)(selector)}']`;
-      }
-      if (typeof selector === 'number') {
-        // Index selector: must be a non-negative safe integer (RFC 9535 Section 2.1)
-        if (!Number.isSafeInteger(selector) || selector < 0) {
-          throw new TypeError(`Index selector must be a non-negative safe integer, got: ${selector}`);
-        }
-        return `[${selector}]`;
-      }
-      throw new TypeError(`Selector must be a string or non-negative integer, got: ${typeof selector}`);
-    });
-    return `$${segments.join('')}`;
-  } catch (error) {
-    throw new _JSONPathCompileError.default('Failed to compile normalized JSONPath', {
-      cause: error,
-      selectors
-    });
-  }
-};
-var _default = exports.default = compile;

package/cjs/escape.cjs

@@ -1,59 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-/**
- * Escapes a string for use in a normalized JSONPath name selector.
- * Follows RFC 9535 Section 2.7 escaping rules for single-quoted strings.
- *
- * @param {string} selector - The string to escape
- * @returns {string} The escaped string (without surrounding quotes)
- */
-const escape = selector => {
-  if (typeof selector !== 'string') {
-    throw new TypeError('Selector must be a string');
-  }
-  let escaped = '';
-  for (const char of selector) {
-    const codePoint = char.codePointAt(0);
-    switch (codePoint) {
-      case 0x08:
-        // backspace
-        escaped += '\\b';
-        break;
-      case 0x09:
-        // horizontal tab
-        escaped += '\\t';
-        break;
-      case 0x0a:
-        // line feed
-        escaped += '\\n';
-        break;
-      case 0x0c:
-        // form feed
-        escaped += '\\f';
-        break;
-      case 0x0d:
-        // carriage return
-        escaped += '\\r';
-        break;
-      case 0x27:
-        // apostrophe '
-        escaped += "\\'";
-        break;
-      case 0x5c:
-        // backslash \
-        escaped += '\\\\';
-        break;
-      default:
-        // Other control characters (U+0000-U+001F except those handled above)
-        if (codePoint <= 0x1f) {
-          escaped += `\\u${codePoint.toString(16).padStart(4, '0')}`;
-        } else {
-          escaped += char;
-        }
-    }
-  }
-  return escaped;
-};
-var _default = exports.default = escape;