@swaggerexpert/jsonpath 4.0.0 → 4.0.2

package/SECURITY.md

@@ -8,7 +8,8 @@ If you believe you've found an exploitable security issue in @swaggerexpert/json
 |---------|--------------------|
 | ^1.0.0  | :x:                |
 | ^2.0.0  | :x:                |
-| ^3.0.0  | :white_check_mark: |
+| ^3.0.0  | :x:                |
+| ^4.0.0  | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

package/cjs/evaluate/index.cjs

@@ -6,6 +6,7 @@ var _index = _interopRequireDefault(require("../parse/index.cjs"));
 var NormalizedPath = _interopRequireWildcard(require("../normalized-path.cjs"));
 var _segment = _interopRequireDefault(require("./visitors/segment.cjs"));
 var _index2 = _interopRequireDefault(require("./realms/json/index.cjs"));
+var _JSONPathParseError = _interopRequireDefault(require("../errors/JSONPathParseError.cjs"));
 var _JSONPathEvaluateError = _interopRequireDefault(require("../errors/JSONPathEvaluateError.cjs"));
 var defaultFunctions = _interopRequireWildcard(require("./functions/index.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); }
@@ -29,6 +30,8 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  *   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).
+ * @property {boolean} [trace=true] - Enable parser tracing for detailed error messages.
+ *   When true, syntax errors include position and expected tokens.
  */
 
 /**
@@ -38,7 +41,8 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
  * @param {string} expression - JSONPath expression
  * @param {EvaluateOptions} [options] - Evaluation options
  * @returns {unknown[]} - Array of matched values
- * @throws {JSONPathEvaluateError} If the expression is invalid
+ * @throws {JSONPathParseError} If the expression is invalid (syntax or semantic error)
+ * @throws {JSONPathEvaluateError} If an unexpected error occurs during evaluation
  *
  * @example
  * // Simple query
@@ -60,21 +64,29 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 const evaluate = (value, expression, {
   callback,
   realm = new _index2.default(),
-  functions = defaultFunctions
+  functions = defaultFunctions,
+  trace = true
 } = {}) => {
-  // Parse the expression
-  const parseResult = (0, _index.default)(expression);
-  if (!parseResult.result.success) {
-    throw new _JSONPathEvaluateError.default(`Invalid JSONPath expression: ${expression}`, {
-      expression
+  // Parse the expression with trace enabled for better error messages
+  const {
+    result,
+    trace: parseTrace,
+    tree
+  } = (0, _index.default)(expression, {
+    trace: !!trace
+  });
+  if (!result.success) {
+    let message = `Invalid JSONPath expression: "${expression}". Syntax error at position ${result.maxMatched}`;
+    message += parseTrace ? `, expected ${parseTrace.inferExpectations()}` : '';
+    throw new _JSONPathParseError.default(message, {
+      jsonPath: expression
     });
   }
   try {
     // The tree is the AST root directly (JsonPathQuery node)
-    const ast = parseResult.tree;
     const {
       segments
-    } = ast;
+    } = tree;
     const results = [];
 
     // Handle empty query ($ with no segments)

package/es/evaluate/index.mjs

@@ -12,6 +12,7 @@ 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 JSONPathParseError from "../errors/JSONPathParseError.mjs";
 import JSONPathEvaluateError from "../errors/JSONPathEvaluateError.mjs";
 import * as defaultFunctions from "./functions/index.mjs";
 /**
@@ -22,6 +23,8 @@ import * as defaultFunctions from "./functions/index.mjs";
  *   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).
+ * @property {boolean} [trace=true] - Enable parser tracing for detailed error messages.
+ *   When true, syntax errors include position and expected tokens.
  */
 /**
  * Evaluate a JSONPath expression against a value.
@@ -30,7 +33,8 @@ import * as defaultFunctions from "./functions/index.mjs";
  * @param {string} expression - JSONPath expression
  * @param {EvaluateOptions} [options] - Evaluation options
  * @returns {unknown[]} - Array of matched values
- * @throws {JSONPathEvaluateError} If the expression is invalid
+ * @throws {JSONPathParseError} If the expression is invalid (syntax or semantic error)
+ * @throws {JSONPathEvaluateError} If an unexpected error occurs during evaluation
  *
  * @example
  * // Simple query
@@ -52,21 +56,29 @@ import * as defaultFunctions from "./functions/index.mjs";
 const evaluate = (value, expression, {
   callback,
   realm = new JSONEvaluationRealm(),
-  functions = defaultFunctions
+  functions = defaultFunctions,
+  trace = true
 } = {}) => {
-  // Parse the expression
-  const parseResult = parse(expression);
-  if (!parseResult.result.success) {
-    throw new JSONPathEvaluateError(`Invalid JSONPath expression: ${expression}`, {
-      expression
+  // Parse the expression with trace enabled for better error messages
+  const {
+    result,
+    trace: parseTrace,
+    tree
+  } = parse(expression, {
+    trace: !!trace
+  });
+  if (!result.success) {
+    let message = `Invalid JSONPath expression: "${expression}". Syntax error at position ${result.maxMatched}`;
+    message += parseTrace ? `, expected ${parseTrace.inferExpectations()}` : '';
+    throw new JSONPathParseError(message, {
+      jsonPath: expression
     });
   }
   try {
     // The tree is the AST root directly (JsonPathQuery node)
-    const ast = parseResult.tree;
     const {
       segments
-    } = ast;
+    } = tree;
     const results = [];
 
     // Handle empty query ($ with no segments)

package/package.json

@@ -5,7 +5,7 @@
     "registry": "https://registry.npmjs.org",
     "provenance": true
   },
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "RFC 9535 implementation of JSONPath",
   "main": "./cjs/index.cjs",
   "types": "./types/index.d.ts",

package/types/index.d.ts

@@ -216,6 +216,11 @@ export interface Stats {
 
 export interface Trace {
   displayTrace(): string;
+  inferExpectations(): Expectations;
+}
+
+export interface Expectations extends Array<string> {
+  toString(): string;
 }
 
 /**
@@ -274,6 +279,12 @@ export interface EvaluateOptions {
    * Can extend or override built-in functions.
    */
   readonly functions?: Record<string, Function>;
+  /**
+   * Enable parser tracing for detailed error messages.
+   * When true, syntax errors include position and expected tokens.
+   * @default true
+   */
+  readonly trace?: boolean;
 }
 
 /**