@swaggerexpert/jsonpath 2.0.0 → 2.1.0

package/README.md

@@ -34,6 +34,7 @@ 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)
         - [XML](#xml-translator)
@@ -70,14 +71,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 +84,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.

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/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/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/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/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.1.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> {