@swaggerexpert/jsonpath 3.0.0 → 3.1.0

package/README.md

@@ -43,6 +43,8 @@ The development of this library contributed to the identification and formal sub
       - [Statistics](#statistics)
       - [Tracing](#tracing)
     - [Validation](#validation)
+    - [Compilation](#compilation)
+    - [Escaping](#escaping)
     - [Errors](#errors)
     - [Grammar](#grammar)
 - [More about JSONPath](#more-about-jsonpath)
@@ -200,10 +202,11 @@ const { result, trace } = parse('$fdfadfd', { trace: true });
 
 result.success; // returns false
 trace.displayTrace(); // returns trace information
+trace.inferExpectations(); // returns parser expectations
 ```
 
-By combining information from `result` and `trace`, it is possible to analyze the parsing process in detail
-and generate a messages like this: `'Syntax error at position 1, expected "[", ".", ".."'`. Please see this
+By combining information from `result` and `trace`, you can analyze the parsing process in detail
+and generate messages like: `'Syntax error at position 1, expected "[", ".", ".."'`. Please see this
 [test file](https://github.com/swaggerexpert/jsonpath/blob/main/test/parse/trace.js) for more information how to achieve that.
 
 #### Validation
@@ -226,13 +229,39 @@ test("$['a']", { normalized: true }); // => true
 test('$.store.book[0].title', { normalized: true }); // => false
 ```
 
+#### Compilation
+
+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.
+
+```js
+import { compile } from '@swaggerexpert/jsonpath';
+
+compile(['store', 'book', 0, 'title']); // => "$['store']['book'][0]['title']"
+```
+
+#### Escaping
+
+Certain characters within name selectors in Normalized Paths require escaping.
+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';
+
+escape("it's"); // => "it\\'s"
+escape('back\\slash'); // => "back\\\\slash"
+escape('line\nfeed'); // => "line\\nfeed"
+```
+
 #### Errors
 
 `@swaggerexpert/jsonpath` provides a structured error class hierarchy,
-enabling precise error handling across JSONPath operations, including parsing.
+enabling precise error handling across JSONPath operations, including parsing and compilation.
 
 ```js
-import { JSONPathError, JSONPathParseError } from '@swaggerexpert/jsonpath';
+import { JSONPathError, JSONPathParseError, JSONPathCompileError } from '@swaggerexpert/jsonpath';
 ```
 
 **JSONPathError** is the base class for all JSONPath errors.

package/SECURITY.md

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

package/cjs/apg-lite.cjs

@@ -2,31 +2,31 @@
 
 exports.__esModule = true;
 exports.utilities = exports.identifiers = exports.Trace = exports.Stats = exports.Parser = exports.Ast = void 0;
-/*  *************************************************************************************
- *   copyright: Copyright (c) 2023 Lowell D. Thomas, all rights reserved
- *     license: BSD-2-Clause (https://opensource.org/licenses/BSD-2-Clause)
- *
- *    Redistribution and use in source and binary forms, with or without
- *    modification, are permitted provided that the following conditions are met:
- *
- *    1. Redistributions of source code must retain the above copyright notice, this
- *       list of conditions and the following disclaimer.
- *
- *    2. Redistributions in binary form must reproduce the above copyright notice,
- *       this list of conditions and the following disclaimer in the documentation
- *       and/or other materials provided with the distribution.
- *
- *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- *    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
- *    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- *    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- *    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
- *    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- *    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- *    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
+/*  *************************************************************************************
+ *   copyright: Copyright (c) 2023 Lowell D. Thomas, all rights reserved
+ *     license: BSD-2-Clause (https://opensource.org/licenses/BSD-2-Clause)
+ *
+ *    Redistribution and use in source and binary forms, with or without
+ *    modification, are permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this
+ *       list of conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice,
+ *       this list of conditions and the following disclaimer in the documentation
+ *       and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ *    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ *    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ *    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ *    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ *    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ *    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ *    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
  *   ********************************************************************************* */
 
 const Parser = exports.Parser = function fnparser() {
@@ -665,7 +665,7 @@ const Ast = exports.Ast = function fnast() {
   a.ruleDefined = index => !!nodeCallbacks[index];
   /* AST node UDT callbacks - called by the parser's `UDT` operator */
   a.udtDefined = index => !!nodeCallbacks[rules.length + index];
-  /* called by the parser's `RNM` & `UDT` operators
+  /* called by the parser's `RNM` & `UDT` operators
      builds a record for the downward traversal of the node */
   a.down = (callbackIndex, name) => {
     const thisIndex = records.length;
@@ -963,8 +963,8 @@ const Stats = exports.Stats = function fnstats() {
     out += displayRow('TOTAL', totals.match, totals.empty, totals.nomatch, totals.total);
     return out;
   };
-  /*
-  Display rule/udt
+  /*
+  Display rule/udt
   */
   this.displayHits = type => {
     let out = '';

package/cjs/compile.cjs

@@ -0,0 +1,50 @@
+"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/errors/JSONPathCompileError.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 JSONPathCompileError extends _JSONPathError.default {}
+var _default = exports.default = JSONPathCompileError;

package/cjs/escape.cjs

@@ -0,0 +1,59 @@
+"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;

package/cjs/index.cjs

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.test = exports.parse = exports.XMLTranslator = exports.Grammar = exports.CSTTranslator = exports.CSTOptimizedTranslator = exports.ASTTranslator = void 0;
+exports.test = exports.parse = exports.escape = exports.compile = exports.XMLTranslator = exports.Trace = exports.JSONPathParseError = exports.JSONPathError = exports.JSONPathCompileError = exports.Grammar = exports.CSTTranslator = exports.CSTOptimizedTranslator = exports.ASTTranslator = void 0;
 var _grammar = _interopRequireDefault(require("./grammar.cjs"));
 exports.Grammar = _grammar.default;
 var _index = _interopRequireDefault(require("./parse/index.cjs"));
@@ -14,6 +14,18 @@ var _index2 = _interopRequireDefault(require("./parse/translators/ASTTranslator/
 exports.ASTTranslator = _index2.default;
 var _XMLTranslator = _interopRequireDefault(require("./parse/translators/XMLTranslator.cjs"));
 exports.XMLTranslator = _XMLTranslator.default;
+var _Trace = _interopRequireDefault(require("./parse/trace/Trace.cjs"));
+exports.Trace = _Trace.default;
 var _index3 = _interopRequireDefault(require("./test/index.cjs"));
 exports.test = _index3.default;
+var _compile = _interopRequireDefault(require("./compile.cjs"));
+exports.compile = _compile.default;
+var _escape = _interopRequireDefault(require("./escape.cjs"));
+exports.escape = _escape.default;
+var _JSONPathError = _interopRequireDefault(require("./errors/JSONPathError.cjs"));
+exports.JSONPathError = _JSONPathError.default;
+var _JSONPathParseError = _interopRequireDefault(require("./errors/JSONPathParseError.cjs"));
+exports.JSONPathParseError = _JSONPathParseError.default;
+var _JSONPathCompileError = _interopRequireDefault(require("./errors/JSONPathCompileError.cjs"));
+exports.JSONPathCompileError = _JSONPathCompileError.default;
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/cjs/parse/index.cjs

@@ -3,6 +3,7 @@
 exports.__esModule = true;
 exports.default = void 0;
 var _apgLite = require("../apg-lite.cjs");
+var _Trace = _interopRequireDefault(require("./trace/Trace.cjs"));
 var _grammar = _interopRequireDefault(require("../grammar.cjs"));
 var _index = _interopRequireDefault(require("./translators/ASTTranslator/index.cjs"));
 var _JSONPathParseError = _interopRequireDefault(require("../errors/JSONPathParseError.cjs"));
@@ -21,7 +22,7 @@ const parse = (jsonPath, {
     const parser = new _apgLite.Parser();
     if (translator) parser.ast = translator;
     if (stats) parser.stats = new _apgLite.Stats();
-    if (trace) parser.trace = new _apgLite.Trace();
+    if (trace) parser.trace = new _Trace.default();
     const startRule = normalized ? 'normalized-path' : 'jsonpath-query';
     const result = parser.parse(grammar, startRule, jsonPath);
     return {

package/cjs/parse/trace/Expectations.cjs

@@ -0,0 +1,10 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class Expectations extends Array {
+  toString() {
+    return this.map(c => `"${String(c)}"`).join(', ');
+  }
+}
+var _default = exports.default = Expectations;

package/cjs/parse/trace/Trace.cjs

@@ -0,0 +1,35 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apgLite = require("../../apg-lite.cjs");
+var _Expectations = _interopRequireDefault(require("./Expectations.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class Trace extends _apgLite.Trace {
+  inferExpectations() {
+    const lines = this.displayTrace().split('\n');
+    const expectations = new Set();
+    let lastMatchedIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // capture the max match line (first one that ends in a single character match)
+      if (line.includes('M|')) {
+        const textMatch = line.match(/]'(.*)'$/);
+        if (textMatch && textMatch[1]) {
+          lastMatchedIndex = i;
+        }
+      }
+
+      // collect terminal failures after the deepest successful match
+      if (i > lastMatchedIndex) {
+        const terminalFailMatch = line.match(/N\|\[TLS\(([^)]+)\)]/);
+        if (terminalFailMatch) {
+          expectations.add(terminalFailMatch[1]);
+        }
+      }
+    }
+    return new _Expectations.default(...expectations);
+  }
+}
+var _default = exports.default = Trace;

package/cjs/parse/translators/ASTTranslator/decoders.cjs

@@ -1,13 +1,80 @@
 "use strict";
 
 exports.__esModule = true;
-exports.decodeString = exports.decodeJSONValue = exports.decodeInteger = void 0;
-const decodeString = str => {
-  return JSON.parse(`"${str.replace(/"/g, '\\"')}"`);
+exports.decodeSingleQuotedString = exports.decodeJSONValue = exports.decodeInteger = exports.decodeDoubleQuotedString = void 0;
+const decodeDoubleQuotedString = str => {
+  return decodeJSONValue(`"${str}"`);
 };
-exports.decodeString = decodeString;
+exports.decodeDoubleQuotedString = decodeDoubleQuotedString;
+const decodeSingleQuotedString = str => {
+  // Decode single-quoted string escape sequences into raw text, then let JSON.stringify
+  // produce a correctly escaped double-quoted JSON string.
+  let decoded = '';
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === '\\') {
+      i++;
+      if (i >= str.length) {
+        // Trailing backslash, treat it as a literal backslash
+        decoded += '\\';
+        break;
+      }
+      const esc = str[i];
+      switch (esc) {
+        case 'n':
+          decoded += '\n';
+          break;
+        case 'r':
+          decoded += '\r';
+          break;
+        case 't':
+          decoded += '\t';
+          break;
+        case 'b':
+          decoded += '\b';
+          break;
+        case 'f':
+          decoded += '\f';
+          break;
+        case '/':
+          decoded += '/';
+          break;
+        case '\\':
+          decoded += '\\';
+          break;
+        case "'":
+          decoded += "'";
+          break;
+        case '"':
+          decoded += '"';
+          break;
+        case 'u':
+          {
+            // Unicode escape \uXXXX - grammar guarantees exactly 4 hex digits
+            const hex = str.slice(i + 1, i + 5);
+            decoded += String.fromCharCode(parseInt(hex, 16));
+            i += 4;
+            break;
+          }
+        default:
+          // Unrecognized escape, keep the escaped character literally
+          decoded += esc;
+          break;
+      }
+    } else {
+      decoded += ch;
+    }
+  }
+  // Use JSON.stringify to produce a valid JSON string literal
+  return decodeJSONValue(JSON.stringify(decoded));
+};
+exports.decodeSingleQuotedString = decodeSingleQuotedString;
 const decodeInteger = str => {
-  return parseInt(str, 10);
+  const value = parseInt(str, 10);
+  if (!Number.isSafeInteger(value)) {
+    throw new RangeError(`Integer value out of safe range [-(2^53)+1, (2^53)-1], got: ${str}`);
+  }
+  return value;
 };
 exports.decodeInteger = decodeInteger;
 const decodeJSONValue = str => {

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

@@ -4,8 +4,7 @@ exports.__esModule = true;
 exports.default = void 0;
 var _CSTOptimizedTranslator = _interopRequireDefault(require("../CSTOptimizedTranslator.cjs"));
 var _transformers = _interopRequireWildcard(require("./transformers.cjs"));
-function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
-function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+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); }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 class ASTTranslator extends _CSTOptimizedTranslator.default {
   getTree() {

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

@@ -73,9 +73,10 @@ const transformers = {
     const quoted = node.children.find(({
       type
     }) => ['double-quoted', 'single-quoted'].includes(type));
+    const decodeString = isSingleQuoted ? _decoders.decodeSingleQuotedString : _decoders.decodeDoubleQuotedString;
     return {
       type: 'StringLiteral',
-      value: quoted ? (0, _decoders.decodeString)(quoted.text) : '',
+      value: quoted ? decodeString(quoted.text) : '',
       format: isSingleQuoted ? 'single-quoted' : 'double-quoted'
     };
   },
@@ -396,7 +397,7 @@ const transformers = {
     }) => type === 'normal-single-quoted');
     return {
       type: 'NameSelector',
-      value: child ? (0, _decoders.decodeString)(child.text) : '',
+      value: child ? (0, _decoders.decodeSingleQuotedString)(child.text) : '',
       format: 'single-quoted'
     };
   },

package/es/compile.mjs

@@ -0,0 +1,45 @@
+import escape from "./escape.mjs";
+import JSONPathCompileError from "./errors/JSONPathCompileError.mjs";
+/**
+ * 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(`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 JSONPathCompileError('Failed to compile normalized JSONPath', {
+      cause: error,
+      selectors
+    });
+  }
+};
+export default compile;

package/es/errors/JSONPathCompileError.mjs

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

package/es/escape.mjs

@@ -0,0 +1,55 @@
+/**
+ * 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;
+};
+export default escape;

package/es/index.mjs

@@ -4,4 +4,10 @@ export { default as CSTTranslator } from "./parse/translators/CSTTranslator.mjs"
 export { default as CSTOptimizedTranslator } from "./parse/translators/CSTOptimizedTranslator.mjs";
 export { default as ASTTranslator } from "./parse/translators/ASTTranslator/index.mjs";
 export { default as XMLTranslator } from "./parse/translators/XMLTranslator.mjs";
-export { default as test } from "./test/index.mjs";
+export { default as Trace } from "./parse/trace/Trace.mjs";
+export { default as test } from "./test/index.mjs";
+export { default as compile } from "./compile.mjs";
+export { default as escape } from "./escape.mjs";
+export { default as JSONPathError } from "./errors/JSONPathError.mjs";
+export { default as JSONPathParseError } from "./errors/JSONPathParseError.mjs";
+export { default as JSONPathCompileError } from "./errors/JSONPathCompileError.mjs";

package/es/parse/index.mjs

@@ -1,4 +1,5 @@
-import { Parser, Stats, Trace } from 'apg-lite';
+import { Parser, Stats } from 'apg-lite';
+import Trace from "./trace/Trace.mjs";
 import Grammar from "../grammar.mjs";
 import ASTTranslator from "./translators/ASTTranslator/index.mjs";
 import JSONPathParseError from "../errors/JSONPathParseError.mjs";

package/es/parse/trace/Expectations.mjs

@@ -0,0 +1,6 @@
+class Expectations extends Array {
+  toString() {
+    return this.map(c => `"${String(c)}"`).join(', ');
+  }
+}
+export default Expectations;

package/es/parse/trace/Trace.mjs

@@ -0,0 +1,30 @@
+import { Trace as BaseTrace } from 'apg-lite';
+import Expectations from "./Expectations.mjs";
+class Trace extends BaseTrace {
+  inferExpectations() {
+    const lines = this.displayTrace().split('\n');
+    const expectations = new Set();
+    let lastMatchedIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // capture the max match line (first one that ends in a single character match)
+      if (line.includes('M|')) {
+        const textMatch = line.match(/]'(.*)'$/);
+        if (textMatch && textMatch[1]) {
+          lastMatchedIndex = i;
+        }
+      }
+
+      // collect terminal failures after the deepest successful match
+      if (i > lastMatchedIndex) {
+        const terminalFailMatch = line.match(/N\|\[TLS\(([^)]+)\)]/);
+        if (terminalFailMatch) {
+          expectations.add(terminalFailMatch[1]);
+        }
+      }
+    }
+    return new Expectations(...expectations);
+  }
+}
+export default Trace;

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

@@ -1,8 +1,74 @@
-export const decodeString = str => {
-  return JSON.parse(`"${str.replace(/"/g, '\\"')}"`);
+export const decodeDoubleQuotedString = str => {
+  return decodeJSONValue(`"${str}"`);
+};
+export const decodeSingleQuotedString = str => {
+  // Decode single-quoted string escape sequences into raw text, then let JSON.stringify
+  // produce a correctly escaped double-quoted JSON string.
+  let decoded = '';
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === '\\') {
+      i++;
+      if (i >= str.length) {
+        // Trailing backslash, treat it as a literal backslash
+        decoded += '\\';
+        break;
+      }
+      const esc = str[i];
+      switch (esc) {
+        case 'n':
+          decoded += '\n';
+          break;
+        case 'r':
+          decoded += '\r';
+          break;
+        case 't':
+          decoded += '\t';
+          break;
+        case 'b':
+          decoded += '\b';
+          break;
+        case 'f':
+          decoded += '\f';
+          break;
+        case '/':
+          decoded += '/';
+          break;
+        case '\\':
+          decoded += '\\';
+          break;
+        case "'":
+          decoded += "'";
+          break;
+        case '"':
+          decoded += '"';
+          break;
+        case 'u':
+          {
+            // Unicode escape \uXXXX - grammar guarantees exactly 4 hex digits
+            const hex = str.slice(i + 1, i + 5);
+            decoded += String.fromCharCode(parseInt(hex, 16));
+            i += 4;
+            break;
+          }
+        default:
+          // Unrecognized escape, keep the escaped character literally
+          decoded += esc;
+          break;
+      }
+    } else {
+      decoded += ch;
+    }
+  }
+  // Use JSON.stringify to produce a valid JSON string literal
+  return decodeJSONValue(JSON.stringify(decoded));
 };
 export const decodeInteger = str => {
-  return parseInt(str, 10);
+  const value = parseInt(str, 10);
+  if (!Number.isSafeInteger(value)) {
+    throw new RangeError(`Integer value out of safe range [-(2^53)+1, (2^53)-1], got: ${str}`);
+  }
+  return value;
 };
 export const decodeJSONValue = str => {
   return JSON.parse(str);

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

@@ -1,5 +1,5 @@
 import JSONPathParseError from "../../../errors/JSONPathParseError.mjs";
-import { decodeString, decodeInteger, decodeJSONValue } from "./decoders.mjs";
+import { decodeSingleQuotedString, decodeDoubleQuotedString, decodeInteger, decodeJSONValue } from "./decoders.mjs";
 export const transformCSTtoAST = (node, transformerMap, ctx = {
   parent: null,
   path: []
@@ -67,6 +67,7 @@ const transformers = {
     const quoted = node.children.find(({
       type
     }) => ['double-quoted', 'single-quoted'].includes(type));
+    const decodeString = isSingleQuoted ? decodeSingleQuotedString : decodeDoubleQuotedString;
     return {
       type: 'StringLiteral',
       value: quoted ? decodeString(quoted.text) : '',
@@ -390,7 +391,7 @@ const transformers = {
     }) => type === 'normal-single-quoted');
     return {
       type: 'NameSelector',
-      value: child ? decodeString(child.text) : '',
+      value: child ? decodeSingleQuotedString(child.text) : '',
       format: 'single-quoted'
     };
   },

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@swaggerexpert/jsonpath",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": true
   },
-  "version": "3.0.0",
-  "description": "RCF 9535 implementation of JSONPath",
+  "version": "3.1.0",
+  "description": "RFC 9535 implementation of JSONPath",
   "main": "./cjs/index.cjs",
   "types": "./types/index.d.ts",
   "exports": {
@@ -60,22 +62,28 @@
     "SECURITY.md"
   ],
   "dependencies": {
-    "apg-lite": "^1.0.4"
+    "apg-lite": "^1.0.5"
   },
   "devDependencies": {
-    "@babel/cli": "=7.27.0",
-    "@babel/core": "=7.26.10",
-    "@babel/preset-env": "=7.26.9",
-    "@commitlint/cli": "=19.8.0",
-    "@commitlint/config-conventional": "=19.8.0",
+    "@babel/cli": "=7.28.6",
+    "@babel/core": "=7.28.6",
+    "@babel/preset-env": "=7.28.6",
+    "@commitlint/cli": "=20.3.1",
+    "@commitlint/config-conventional": "=20.3.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "apg-js": "^4.4.0",
     "babel-plugin-module-resolver": "^5.0.2",
-    "chai": "=5.2.0",
-    "cross-env": "^7.0.3",
+    "chai": "=6.2.2",
+    "cross-env": "^10.0.0",
     "husky": "=9.1.7",
-    "mocha": "=11.1.0",
-    "mocha-expect-snapshot": "^7.2.0",
+    "mocha": "=11.7.5",
+    "mocha-expect-snapshot": "^8.0.0",
     "npm-watch": "^0.13.0",
-    "prettier": "^3.5.2"
+    "prettier": "^3.5.2",
+    "semantic-release": "^25.0.2"
   }
 }

package/types/index.d.ts

@@ -20,6 +20,9 @@ export declare class CSTOptimizedTranslator implements CSTTranslator {
   constructor(options?: { collapsibleTypes?: string[] });
   getTree(): CSTTree;
 }
+export declare class ASTTranslator implements Translator<ASTTree> {
+  getTree(): ASTTree;
+}
 export declare class XMLTranslator implements Translator<XMLTree> {
   getTree(): XMLTree;
 }
@@ -35,7 +38,7 @@ export interface ParseResult<TTree = ASTTree> {
     readonly maxTreeDepth: number
     readonly nodeHits: number;
   };
-  readonly tree: TTree;
+  readonly tree?: TTree;
   readonly stats?: Stats;
   readonly trace?: Trace;
 }
@@ -92,6 +95,8 @@ export interface NameSelectorASTNode extends ASTNode {
   value: string;
   format: 'single-quoted' | 'double-quoted' | 'shorthand';
 }
+type NameSelectorShorthandASTNode = NameSelectorASTNode & { format: 'shorthand' };
+type NameSelectorQuotedASTNode   = NameSelectorASTNode & { format: 'single-quoted' | 'double-quoted' };
 // https://www.rfc-editor.org/rfc/rfc9535#section-2.3.2.1
 export interface WildcardSelectorASTNode extends ASTNode {
   type: 'WildcardSelector';
@@ -166,7 +171,7 @@ export interface FunctionExprASTNode extends ASTNode {
 // https://www.rfc-editor.org/rfc/rfc9535#section-2.5.1.1
 export interface ChildSegmentASTNode extends ASTNode {
   type: 'ChildSegment';
-  selector: BracketedSelectionASTNode | WildcardSelectorASTNode | NameSelectorASTNode;
+  selector: BracketedSelectionASTNode | WildcardSelectorASTNode | NameSelectorShorthandASTNode;
 }
 export interface BracketedSelectionASTNode extends ASTNode {
   type: 'BracketedSelection';
@@ -174,11 +179,11 @@ export interface BracketedSelectionASTNode extends ASTNode {
 }
 export interface DescendantSegmentASTNode extends ASTNode {
   type: 'DescendantSegment';
-  selector: BracketedSelectionASTNode | WildcardSelectorASTNode | NameSelectorASTNode;
+  selector: BracketedSelectionASTNode | WildcardSelectorASTNode | NameSelectorShorthandASTNode;
 }
 // union types
 export type SelectorASTNode =
-  | NameSelectorASTNode
+  | NameSelectorQuotedASTNode
   | WildcardSelectorASTNode
   | SliceSelectorASTNode
   | IndexSelectorASTNode