@swaggerexpert/jsonpath 3.2.4 → 4.0.0

package/cjs/normalized-path.cjs

@@ -0,0 +1,145 @@
+"use strict";
+
+exports.__esModule = true;
+exports.to = exports.test = exports.from = exports.escape = void 0;
+var _index = _interopRequireDefault(require("./parse/index.cjs"));
+var _index2 = _interopRequireDefault(require("./test/index.cjs"));
+var _JSONNormalizedPathError = _interopRequireDefault(require("./errors/JSONNormalizedPathError.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Tests if a string is a valid normalized JSONPath.
+ *
+ * @param {string} normalizedPath - The string to test
+ * @returns {boolean} True if valid normalized path, false otherwise
+ */
+const test = normalizedPath => (0, _index2.default)(normalizedPath, {
+  normalized: true
+});
+
+/**
+ * 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)
+ */
+exports.test = test;
+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;
+};
+
+/**
+ * Creates a normalized path string from a list of selectors.
+ * Name selectors are automatically escaped.
+ *
+ * @param {Array<string|number>} selectors - Array of name selectors (strings) or index selectors (numbers)
+ * @returns {string} A normalized JSONPath string
+ * @throws {JSONNormalizedPathError} If selectors is not an array or contains invalid selector types
+ */
+exports.escape = escape;
+const from = selectors => {
+  if (!Array.isArray(selectors)) {
+    throw new _JSONNormalizedPathError.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 `['${escape(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 _JSONNormalizedPathError.default('Failed to compile normalized JSONPath', {
+      cause: error,
+      selectors
+    });
+  }
+};
+
+/**
+ * Parses a normalized path string and returns a list of selectors.
+ *
+ * @param {string} normalizedPath - A normalized JSONPath string
+ * @returns {Array<string|number>} Array of name selectors (strings) or index selectors (numbers)
+ * @throws {JSONNormalizedPathError} If the normalized path is invalid
+ */
+exports.from = from;
+const to = normalizedPath => {
+  if (typeof normalizedPath !== 'string') {
+    throw new _JSONNormalizedPathError.default(`Normalized path must be a string, got: ${typeof normalizedPath}`, {
+      normalizedPath
+    });
+  }
+  const parseResult = (0, _index.default)(normalizedPath, {
+    normalized: true
+  });
+  if (!parseResult.result.success) {
+    throw new _JSONNormalizedPathError.default('Invalid normalized path', {
+      normalizedPath
+    });
+  }
+  const {
+    tree
+  } = parseResult;
+
+  // Extract selectors from AST segments
+  // Normalized path grammar only allows NameSelector and IndexSelector
+  // For normalized paths, segment.selector is directly the selector (not BracketedSelection)
+  return tree.segments.map(segment => segment.selector.value);
+};
+exports.to = to;

package/cjs/parse/callbacks/cst.cjs

@@ -7,13 +7,12 @@ var _JSONPathParseError = _interopRequireDefault(require("../../errors/JSONPathP
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 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.default("parser's user data must be an object");
     }
 
     // drop the empty nodes
-    if ((_data$options = data.options) != null && _data$options.optimize && phraseLength === 0 && (_data$options2 = data.options) != null && (_data$options2 = _data$options2.droppableTypes) != null && _data$options2.includes(nodeType)) {
+    if (data.options?.optimize && phraseLength === 0 && data.options?.droppableTypes?.includes(nodeType)) {
       return;
     }
     if (state === _apgLite.identifiers.SEM_PRE) {
@@ -25,11 +24,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 ? void 0 : _data$options3.optimize) && ((_data$options4 = data.options) == null || (_data$options4 = _data$options4.collapsibleTypes) == null ? void 0 : _data$options4.includes(node.type)) && (prevSibling == null ? 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/cjs/parse/index.cjs

@@ -32,7 +32,9 @@ const parse = (jsonPath, {
       trace: parser.trace
     };
   } catch (error) {
-    throw new _JSONPathParseError.default('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.default(message, {
       cause: error,
       jsonPath
     });

package/cjs/parse/translators/ASTTranslator/index.cjs

@@ -9,7 +9,7 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 class ASTTranslator extends _CSTOptimizedTranslator.default {
   getTree() {
     const cst = super.getTree();
-    return (0, _transformers.transformCSTtoAST)(cst.root, _transformers.default);
+    return (0, _transformers.transformCSTtoAST)(cst, _transformers.default);
   }
 }
 var _default = exports.default = ASTTranslator;

package/cjs/parse/translators/ASTTranslator/transformers.cjs

@@ -5,6 +5,204 @@ exports.transformCSTtoAST = exports.default = void 0;
 var _JSONPathParseError = _interopRequireDefault(require("../../../errors/JSONPathParseError.cjs"));
 var _decoders = require("./decoders.cjs");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * 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);
+  }
+};
 const transformCSTtoAST = (node, transformerMap, ctx = {
   parent: null,
   path: []
@@ -124,9 +322,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) {
@@ -153,6 +373,7 @@ const transformers = {
         right
       };
     }
+    return left;
   },
   ['logical-and-expr'](node, ctx) {
     const basicExprs = node.children.filter(({
@@ -197,9 +418,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',
@@ -227,11 +449,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) {
@@ -314,10 +551,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/cjs/parse/translators/CSTOptimizedTranslator.cjs

@@ -31,9 +31,7 @@ class CSTOptimizedTranslator extends _CSTTranslator.default {
       options
     };
     this.translate(data);
-    delete data.stack;
-    delete data.options;
-    return data;
+    return data.root;
   }
 }
 var _default = exports.default = CSTOptimizedTranslator;

package/cjs/parse/translators/CSTTranslator.cjs

@@ -111,8 +111,7 @@ class CSTTranslator extends _apgLite.Ast {
       root: null
     };
     this.translate(data);
-    delete data.stack;
-    return data;
+    return data.root;
   }
 }
 var _default = exports.default = CSTTranslator;

package/cjs/test/index.cjs

@@ -3,9 +3,11 @@
 exports.__esModule = true;
 exports.default = void 0;
 var _index = _interopRequireDefault(require("../parse/index.cjs"));
+var _index2 = _interopRequireDefault(require("../parse/translators/ASTTranslator/index.cjs"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const test = (jsonPath, {
-  normalized = false
+  normalized = false,
+  wellTyped = true
 } = {}) => {
   if (typeof jsonPath !== 'string') return false;
   try {
@@ -15,7 +17,7 @@ const test = (jsonPath, {
       normalized,
       stats: false,
       trace: false,
-      translator: null
+      translator: wellTyped ? new _index2.default() : null
     });
     return result.success;
   } catch {

package/es/errors/JSONNormalizedPathError.mjs

@@ -0,0 +1,3 @@
+import JSONPathError from "./JSONPathError.mjs";
+class JSONNormalizedPathError extends JSONPathError {}
+export default JSONNormalizedPathError;

package/es/errors/JSONPathError.mjs

@@ -15,7 +15,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/es/errors/JSONPathEvaluateError.mjs

@@ -0,0 +1,3 @@
+import JSONPathError from "./JSONPathError.mjs";
+class JSONPathEvaluateError extends JSONPathError {}
+export default JSONPathEvaluateError;

package/es/evaluate/evaluators/comparable.mjs

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+import evaluateLiteral from "./literal.mjs";
+import { evaluateRelSingularQuery, evaluateAbsSingularQuery } from "./singular-query.mjs";
+import evaluateFunctionExpr from "./function-expr.mjs";
+/**
+ * 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 evaluateLiteral(ctx, root, current, node);
+    case 'RelSingularQuery':
+      return evaluateRelSingularQuery(ctx, root, current, node);
+    case 'AbsSingularQuery':
+      return evaluateAbsSingularQuery(ctx, root, current, node);
+    case 'FunctionExpr':
+      return evaluateFunctionExpr(ctx, root, current, node);
+    default:
+      return undefined;
+  }
+};
+export default evaluateComparable;

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

@@ -0,0 +1,31 @@
+/**
+ * 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
+ */
+import evaluateComparable from "./comparable.mjs";
+/**
+ * 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 = evaluateComparable(ctx, root, current, left);
+  const rightValue = evaluateComparable(ctx, root, current, right);
+  return ctx.realm.compare(leftValue, op, rightValue);
+};
+export default evaluateComparisonExpr;