@swaggerexpert/jsonpath 2.0.0 → 2.2.0

package/README.md

@@ -34,8 +34,10 @@ The development of this library contributed to the identification and formal sub
   - [Installation](#installation)
   - [Usage](#usage)
     - [Parsing](#parsing)
+      - [Normalized paths](#normalized-paths)
       - [Translators](#translators)
         - [CST](#cst-translator)
+        - [CST Optimized](#cst-optimized-translator)
         - [XML](#xml-translator)
       - [Statistics](#statistics)
       - [Tracing](#tracing)
@@ -70,14 +72,6 @@ import { parse } from '@swaggerexpert/jsonpath';
 const parseResult = parse('$.store.book[0].title');
 ```
 
-or
-
-```js
-import { parse, CSTTranslator } from '@swaggerexpert/jsonpath';
-
-const parseResult = parse('$.store.book[0].title', { translator: new CSTTranslator() });
-```
-
 **parseResult** variable has the following shape:
 
 ```
@@ -91,6 +85,31 @@ const parseResult = parse('$.store.book[0].title', { translator: new CSTTranslat
 
 [TypeScript typings](https://github.com/swaggerexpert/jsonpath/blob/main/types/index.d.ts) are available for all fields attached to parse result object returned by the `parse` function.
 
+
+##### Normalized paths
+
+[comment]: <> (SPDX-FileCopyrightText: Copyright &#40;c&#41; 2024 IETF Trust and the persons identified as the document authors. All rights reserved.)
+[comment]: <> (SPDX-License-Identifier: BSD-3-Clause)
+
+[Normalized Path](https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths) is a JSONPath query with restricted syntax.
+A Normalized Path represents the identity of a node in a specific value.
+There is precisely one Normalized Path identifying any particular node in a value.
+Normalized Paths provide a predictable format that simplifies testing and post-processing of nodelists, e.g., to remove duplicate nodes.
+Normalized Paths use the canonical bracket notation, rather than dot notation.
+Single quotes are used in Normalized Paths to delimit string member names. This reduces the number of characters that need escaping when Normalized Paths appear in strings delimited by double quotes.
+
+Parsing in normalized path mode can be enabled by setting `normalized` option to `true`.
+
+```js
+import { parse } from '@swaggerexpert/jsonpath';
+
+parse("$['a']", { normalized: true });
+parse("$[1]", { normalized: true });
+parse("$[2]", { normalized: true });
+parse("$['a']['b'][1]", { normalized: true });
+parse("$['\\u000b']", { normalized: true });
+```
+
 ##### Translators
 
 `@swaggerexpert/jsonpath` provides several translators to convert the parse result into different tree representations.
@@ -130,6 +149,17 @@ interface CSTNode {
 }
 ```
 
+###### CST Optimized translator
+
+Same as CST, but optimizes the tree for more optimized representation. By default, it collapses
+fragmented `single-quoted` or `double-quoted` nodes into a single node.
+
+```js
+import { parse, CSTOptimizedTranslator } from '@swaggerexpert/jsonpath';
+
+const { tree: CST } = parse('$.store.book[0].title', { translator: new CSTOptimizedTranslator() });
+```
+
 ###### XML translator
 
 ```js

package/cjs/grammar.cjs

@@ -16,9 +16,9 @@ function grammar() {
   //        ALT = 41
   //        CAT = 60
   //        REP = 32
-  //        RNM = 174
-  //        TLS = 66
-  //        TBS = 30
+  //        RNM = 178
+  //        TLS = 64
+  //        TBS = 28
   //        TRG = 20
   //        ---   SABNF superset opcodes
   //        UDT = 0
@@ -2247,17 +2247,17 @@ function grammar() {
     children: [1, 2, 3]
   }; // CAT
   this.rules[69].opcodes[1] = {
-    type: 7,
-    string: [91]
-  }; // TLS
+    type: 4,
+    index: 80
+  }; // RNM(left-bracket)
   this.rules[69].opcodes[2] = {
     type: 4,
     index: 70
   }; // RNM(normal-selector)
   this.rules[69].opcodes[3] = {
-    type: 7,
-    string: [93]
-  }; // TLS
+    type: 4,
+    index: 81
+  }; // RNM(right-bracket)
 
   /* normal-selector */
   this.rules[70].opcodes = [];
@@ -2281,9 +2281,9 @@ function grammar() {
     children: [1, 2, 4]
   }; // CAT
   this.rules[71].opcodes[1] = {
-    type: 6,
-    string: [39]
-  }; // TBS
+    type: 4,
+    index: 87
+  }; // RNM(squote)
   this.rules[71].opcodes[2] = {
     type: 3,
     min: 0,
@@ -2294,9 +2294,9 @@ function grammar() {
     index: 72
   }; // RNM(normal-single-quoted)
   this.rules[71].opcodes[4] = {
-    type: 6,
-    string: [39]
-  }; // TBS
+    type: 4,
+    index: 87
+  }; // RNM(squote)
 
   /* normal-single-quoted */
   this.rules[72].opcodes = [];
@@ -2784,9 +2784,9 @@ function grammar() {
     str += "\n";
     str += "; https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths\n";
     str += "normalized-path      = root-identifier *(normal-index-segment)\n";
-    str += "normal-index-segment = \"[\" normal-selector \"]\"\n";
+    str += "normal-index-segment = left-bracket normal-selector right-bracket ; MODIFICATION: surrogate text rule used\n";
     str += "normal-selector      = normal-name-selector / normal-index-selector\n";
-    str += "normal-name-selector = %x27 *normal-single-quoted %x27 ; 'string'\n";
+    str += "normal-name-selector = squote *normal-single-quoted squote ; 'string', MODIFICATION: surrogate text rule used\n";
     str += "normal-single-quoted = normal-unescaped /\n";
     str += "                       ESC normal-escapable\n";
     str += "normal-unescaped     =    ; omit %x0-1F control codes\n";

package/cjs/index.cjs

@@ -1,13 +1,15 @@
 "use strict";
 
 exports.__esModule = true;
-exports.parse = exports.XMLTranslator = exports.Grammar = exports.CSTTranslator = void 0;
+exports.parse = exports.XMLTranslator = exports.Grammar = exports.CSTTranslator = exports.CSTOptimizedTranslator = void 0;
 var _grammar = _interopRequireDefault(require("./grammar.cjs"));
 exports.Grammar = _grammar.default;
 var _index = _interopRequireDefault(require("./parse/index.cjs"));
 exports.parse = _index.default;
 var _CSTTranslator = _interopRequireDefault(require("./parse/translators/CSTTranslator.cjs"));
 exports.CSTTranslator = _CSTTranslator.default;
+var _CSTOptimizedTranslator = _interopRequireDefault(require("./parse/translators/CSTOptimizedTranslator.cjs"));
+exports.CSTOptimizedTranslator = _CSTOptimizedTranslator.default;
 var _XMLTranslator = _interopRequireDefault(require("./parse/translators/XMLTranslator.cjs"));
 exports.XMLTranslator = _XMLTranslator.default;
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/cjs/parse/callbacks/cst.cjs

@@ -22,9 +22,15 @@ const cst = ruleName => {
         children: []
       };
       if (data.stack.length > 0) {
+        var _data$options, _data$options2;
         const parent = data.stack[data.stack.length - 1];
-        const isTextWithinTextNode = parent.type === 'text' && node.type === 'text';
-        if (!isTextWithinTextNode) {
+        const prevSibling = parent.children[parent.children.length - 1];
+        const isTextNodeWithinTextNode = parent.type === 'text' && node.type === 'text';
+        const shouldCollapse = ((_data$options = data.options) == null ? void 0 : _data$options.optimize) && ((_data$options2 = data.options) == null || (_data$options2 = _data$options2.collapsibleTypes) == null ? void 0 : _data$options2.includes(node.type)) && (prevSibling == null ? void 0 : prevSibling.type) === node.type;
+        if (shouldCollapse) {
+          prevSibling.text += node.text;
+          prevSibling.length += node.length;
+        } else if (!isTextNodeWithinTextNode) {
           parent.children.push(node);
         }
       } else {

package/cjs/parse/index.cjs

@@ -9,9 +9,11 @@ var _JSONPathParseError = _interopRequireDefault(require("../errors/JSONPathPars
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const grammar = new _grammar.default();
 const parse = (jsonPath, {
-  translator = new _CSTTranslator.default(),
+  normalized = false,
   stats = false,
-  trace = false
+  trace = false,
+  translator = new _CSTTranslator.default(),
+  test = 3
 } = {}) => {
   if (typeof jsonPath !== 'string') {
     throw new TypeError('JSONPath must be a string');
@@ -22,7 +24,8 @@ const parse = (jsonPath, {
     if (translator) parser.ast = translator;
     if (stats) parser.stats = new _apgLite.Stats();
     if (trace) parser.trace = new _apgLite.Trace();
-    const result = parser.parse(grammar, 'jsonpath-query', jsonPath);
+    const startRule = normalized ? 'normalized-path' : 'jsonpath-query';
+    const result = parser.parse(grammar, startRule, jsonPath);
     return {
       result,
       tree: (_parser$ast = parser.ast) == null ? void 0 : _parser$ast.getTree(),

package/cjs/parse/translators/CSTOptimizedTranslator.cjs

@@ -0,0 +1,33 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _CSTTranslator = _interopRequireDefault(require("./CSTTranslator.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class CSTOptimizedTranslator extends _CSTTranslator.default {
+  collapsibleTypes = ['single-quoted', 'double-quoted'];
+  constructor({
+    collapsibleTypes
+  } = {}) {
+    super();
+    if (Array.isArray(collapsibleTypes)) {
+      this.collapsibleTypes = collapsibleTypes;
+    }
+  }
+  getTree() {
+    const options = {
+      optimize: true,
+      collapsibleTypes: this.collapsibleTypes
+    };
+    const data = {
+      stack: [],
+      root: null,
+      options
+    };
+    this.translate(data);
+    delete data.stack;
+    delete data.options;
+    return data;
+  }
+}
+var _default = exports.default = CSTOptimizedTranslator;

package/cjs/parse/translators/CSTTranslator.cjs

@@ -82,6 +82,14 @@ class CSTTranslator extends _apgLite.Ast {
     // https://www.rfc-editor.org/rfc/rfc9535#section-2.5.2.1
     this.callbacks['descendant-segment'] = (0, _cst.default)('descendant-segment');
 
+    // https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
+    this.callbacks['normalized-path'] = (0, _cst.default)('normalized-path');
+    this.callbacks['normal-index-segment'] = (0, _cst.default)('normal-index-segment');
+    this.callbacks['normal-selector'] = (0, _cst.default)('normal-selector');
+    this.callbacks['normal-name-selector'] = (0, _cst.default)('normal-name-selector');
+    this.callbacks['normal-index-selector'] = (0, _cst.default)('normal-index-selector');
+    this.callbacks['normal-single-quoted'] = (0, _cst.default)('normal-single-quoted');
+
     // Surrogate named rules
     this.callbacks['dot-prefix'] = (0, _cst.default)('text');
     this.callbacks['double-dot-prefix'] = (0, _cst.default)('text');

package/es/grammar.mjs

@@ -12,9 +12,9 @@ export default function grammar() {
   //        ALT = 41
   //        CAT = 60
   //        REP = 32
-  //        RNM = 174
-  //        TLS = 66
-  //        TBS = 30
+  //        RNM = 178
+  //        TLS = 64
+  //        TBS = 28
   //        TRG = 20
   //        ---   SABNF superset opcodes
   //        UDT = 0
@@ -2243,17 +2243,17 @@ export default function grammar() {
     children: [1, 2, 3]
   }; // CAT
   this.rules[69].opcodes[1] = {
-    type: 7,
-    string: [91]
-  }; // TLS
+    type: 4,
+    index: 80
+  }; // RNM(left-bracket)
   this.rules[69].opcodes[2] = {
     type: 4,
     index: 70
   }; // RNM(normal-selector)
   this.rules[69].opcodes[3] = {
-    type: 7,
-    string: [93]
-  }; // TLS
+    type: 4,
+    index: 81
+  }; // RNM(right-bracket)
 
   /* normal-selector */
   this.rules[70].opcodes = [];
@@ -2277,9 +2277,9 @@ export default function grammar() {
     children: [1, 2, 4]
   }; // CAT
   this.rules[71].opcodes[1] = {
-    type: 6,
-    string: [39]
-  }; // TBS
+    type: 4,
+    index: 87
+  }; // RNM(squote)
   this.rules[71].opcodes[2] = {
     type: 3,
     min: 0,
@@ -2290,9 +2290,9 @@ export default function grammar() {
     index: 72
   }; // RNM(normal-single-quoted)
   this.rules[71].opcodes[4] = {
-    type: 6,
-    string: [39]
-  }; // TBS
+    type: 4,
+    index: 87
+  }; // RNM(squote)
 
   /* normal-single-quoted */
   this.rules[72].opcodes = [];
@@ -2780,9 +2780,9 @@ export default function grammar() {
     str += "\n";
     str += "; https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths\n";
     str += "normalized-path      = root-identifier *(normal-index-segment)\n";
-    str += "normal-index-segment = \"[\" normal-selector \"]\"\n";
+    str += "normal-index-segment = left-bracket normal-selector right-bracket ; MODIFICATION: surrogate text rule used\n";
     str += "normal-selector      = normal-name-selector / normal-index-selector\n";
-    str += "normal-name-selector = %x27 *normal-single-quoted %x27 ; 'string'\n";
+    str += "normal-name-selector = squote *normal-single-quoted squote ; 'string', MODIFICATION: surrogate text rule used\n";
     str += "normal-single-quoted = normal-unescaped /\n";
     str += "                       ESC normal-escapable\n";
     str += "normal-unescaped     =    ; omit %x0-1F control codes\n";

package/es/index.mjs

@@ -1,4 +1,5 @@
 export { default as Grammar } from "./grammar.mjs";
 export { default as parse } from "./parse/index.mjs";
 export { default as CSTTranslator } from "./parse/translators/CSTTranslator.mjs";
+export { default as CSTOptimizedTranslator } from "./parse/translators/CSTOptimizedTranslator.mjs";
 export { default as XMLTranslator } from "./parse/translators/XMLTranslator.mjs";

package/es/parse/callbacks/cst.mjs

@@ -17,9 +17,15 @@ const cst = ruleName => {
         children: []
       };
       if (data.stack.length > 0) {
+        var _data$options, _data$options2;
         const parent = data.stack[data.stack.length - 1];
-        const isTextWithinTextNode = parent.type === 'text' && node.type === 'text';
-        if (!isTextWithinTextNode) {
+        const prevSibling = parent.children[parent.children.length - 1];
+        const isTextNodeWithinTextNode = parent.type === 'text' && node.type === 'text';
+        const shouldCollapse = ((_data$options = data.options) === null || _data$options === void 0 ? void 0 : _data$options.optimize) && ((_data$options2 = data.options) === null || _data$options2 === void 0 || (_data$options2 = _data$options2.collapsibleTypes) === null || _data$options2 === void 0 ? void 0 : _data$options2.includes(node.type)) && (prevSibling === null || prevSibling === void 0 ? void 0 : prevSibling.type) === node.type;
+        if (shouldCollapse) {
+          prevSibling.text += node.text;
+          prevSibling.length += node.length;
+        } else if (!isTextNodeWithinTextNode) {
           parent.children.push(node);
         }
       } else {

package/es/parse/index.mjs

@@ -4,9 +4,11 @@ import CSTTranslator from "./translators/CSTTranslator.mjs";
 import JSONPathParseError from "../errors/JSONPathParseError.mjs";
 const grammar = new Grammar();
 const parse = (jsonPath, {
-  translator = new CSTTranslator(),
+  normalized = false,
   stats = false,
-  trace = false
+  trace = false,
+  translator = new CSTTranslator(),
+  test = 3
 } = {}) => {
   if (typeof jsonPath !== 'string') {
     throw new TypeError('JSONPath must be a string');
@@ -17,7 +19,8 @@ const parse = (jsonPath, {
     if (translator) parser.ast = translator;
     if (stats) parser.stats = new Stats();
     if (trace) parser.trace = new Trace();
-    const result = parser.parse(grammar, 'jsonpath-query', jsonPath);
+    const startRule = normalized ? 'normalized-path' : 'jsonpath-query';
+    const result = parser.parse(grammar, startRule, jsonPath);
     return {
       result,
       tree: (_parser$ast = parser.ast) === null || _parser$ast === void 0 ? void 0 : _parser$ast.getTree(),

package/es/parse/translators/CSTOptimizedTranslator.mjs

@@ -0,0 +1,28 @@
+import CSTTranslator from "./CSTTranslator.mjs";
+class CSTOptimizedTranslator extends CSTTranslator {
+  collapsibleTypes = ['single-quoted', 'double-quoted'];
+  constructor({
+    collapsibleTypes
+  } = {}) {
+    super();
+    if (Array.isArray(collapsibleTypes)) {
+      this.collapsibleTypes = collapsibleTypes;
+    }
+  }
+  getTree() {
+    const options = {
+      optimize: true,
+      collapsibleTypes: this.collapsibleTypes
+    };
+    const data = {
+      stack: [],
+      root: null,
+      options
+    };
+    this.translate(data);
+    delete data.stack;
+    delete data.options;
+    return data;
+  }
+}
+export default CSTOptimizedTranslator;

package/es/parse/translators/CSTTranslator.mjs

@@ -77,6 +77,14 @@ class CSTTranslator extends AST {
     // https://www.rfc-editor.org/rfc/rfc9535#section-2.5.2.1
     this.callbacks['descendant-segment'] = cstCallback('descendant-segment');
 
+    // https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
+    this.callbacks['normalized-path'] = cstCallback('normalized-path');
+    this.callbacks['normal-index-segment'] = cstCallback('normal-index-segment');
+    this.callbacks['normal-selector'] = cstCallback('normal-selector');
+    this.callbacks['normal-name-selector'] = cstCallback('normal-name-selector');
+    this.callbacks['normal-index-selector'] = cstCallback('normal-index-selector');
+    this.callbacks['normal-single-quoted'] = cstCallback('normal-single-quoted');
+
     // Surrogate named rules
     this.callbacks['dot-prefix'] = cstCallback('text');
     this.callbacks['double-dot-prefix'] = cstCallback('text');

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "RCF 9535 implementation of JSONPath",
   "main": "./cjs/index.cjs",
   "types": "./types/index.d.ts",

package/types/index.d.ts

@@ -4,9 +4,10 @@
 export function parse(jsonpath: string, options?: ParseOptions): ParseResult;
 
 export interface ParseOptions {
-  readonly translator?: Translator | null;
+  readonly normalized?: boolean;
   readonly stats?: boolean;
   readonly trace?: boolean;
+  readonly translator?: Translator | null;
 }
 
 export interface Translator<TTree = unknown> {
@@ -15,6 +16,10 @@ export interface Translator<TTree = unknown> {
 export declare class CSTTranslator implements Translator<CSTTree> {
   getTree(): CSTTree;
 }
+export declare class CSTOptimizedTranslator implements CSTTranslator {
+  constructor(options?: { collapsibleTypes?: string[] });
+  getTree(): CSTTree;
+}
 export declare class XMLTranslator implements Translator<XMLTree> {
   getTree(): XMLTree;
 }