@swaggerexpert/jsonpath 1.2.0 → 2.0.0

package/README.md

@@ -9,7 +9,11 @@
 
 `@swaggerexpert/jsonpath` is a **parser** and **validator** for [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) Query Expressions for JSON - **JSONPath**.
 
-The development of this library contributed to the identification and formal submission of [Errata 8343](https://www.rfc-editor.org/errata/eid8343) against RFC 9535.
+The development of this library contributed to the identification and formal submission of following **erratas** against the RFC 9535:
+- [Errata ID: 8343](https://www.rfc-editor.org/errata/eid8343)
+- [Errata ID: 8352](https://www.rfc-editor.org/errata/eid8352)
+- [Errata ID: 8353](https://www.rfc-editor.org/errata/eid8353)
+- [Errata ID: 8354](https://www.rfc-editor.org/errata/eid8354)
 
 <table>
   <tr>
@@ -30,8 +34,9 @@ The development of this library contributed to the identification and formal sub
   - [Installation](#installation)
   - [Usage](#usage)
     - [Parsing](#parsing)
-      - [Concrete Syntax Tree (CST)](#concrete-syntax-tree-cst)
-      - [Interpreting Parse result as XML](#interpreting-parse-result-as-xml)
+      - [Translators](#translators)
+        - [CST](#cst-translator)
+        - [XML](#xml-translator)
       - [Statistics](#statistics)
       - [Tracing](#tracing)
     - [Errors](#errors)
@@ -68,228 +73,72 @@ const parseResult = parse('$.store.book[0].title');
 or
 
 ```js
-import { parse, JSONPathQueryCST } from '@swaggerexpert/jsonpath';
+import { parse, CSTTranslator } from '@swaggerexpert/jsonpath';
 
-const parseResult = parse('$.store.book[0].title', { ast: new JSONPathQueryCST() });
+const parseResult = parse('$.store.book[0].title', { translator: new CSTTranslator() });
 ```
 
 **parseResult** variable has the following shape:
 
 ```
 {
-  result: {
-    success: true,
-    state: 101,
-    stateName: 'MATCH',
-    length: 21,
-    matched: 21,
-    maxMatched: 21,
-    maxTreeDepth: 21,
-    nodeHits: 298
-  },
-  ast: <JSONPathQueryCST>,
-  computed: {
-    stack: [],
-    root: {
-      type: 'jsonpath-query',
-      text: '$.store.book[0].title',
-      start: 0,
-      length: 21,
-      children: [
-        {
-          type: 'root-identifier',
-          text: '$',
-          start: 0,
-          length: 1,
-          children: []
-        },
-        {
-          type: 'segments',
-          text: '.store.book[0].title',
-          start: 1,
-          length: 20,
-          children: [
-            {
-              type: 'segment',
-              text: '.store',
-              start: 1,
-              length: 6,
-              children: [
-                {
-                  type: 'child-segment',
-                  text: '.store',
-                  start: 1,
-                  length: 6,
-                  children: [
-                    {
-                      type: 'text',
-                      text: '.',
-                      start: 1,
-                      length: 1,
-                      children: []
-                    },
-                    {
-                      type: 'member-name-shorthand',
-                      text: 'store',
-                      start: 2,
-                      length: 5,
-                      children: []
-                    }
-                  ]
-                }
-              ]
-            },
-            {
-              type: 'segment',
-              text: '.book',
-              start: 7,
-              length: 5,
-              children: [
-                {
-                  type: 'child-segment',
-                  text: '.book',
-                  start: 7,
-                  length: 5,
-                  children: [
-                    {
-                      type: 'text',
-                      text: '.',
-                      start: 7,
-                      length: 1,
-                      children: []
-                    },
-                    {
-                      type: 'member-name-shorthand',
-                      text: 'book',
-                      start: 8,
-                      length: 4,
-                      children: []
-                    }
-                  ]
-                }
-              ]
-            },
-            {
-              type: 'segment',
-              text: '[0]',
-              start: 12,
-              length: 3,
-              children: [
-                {
-                  type: 'child-segment',
-                  text: '[0]',
-                  start: 12,
-                  length: 3,
-                  children: [
-                    {
-                      type: 'bracketed-selection',
-                      text: '[0]',
-                      start: 12,
-                      length: 3,
-                      children: [
-                        {
-                          type: 'text',
-                          text: '[',
-                          start: 12,
-                          length: 1,
-                          children: []
-                        },
-                        {
-                          type: 'selector',
-                          text: '0',
-                          start: 13,
-                          length: 1,
-                          children: [
-                            {
-                              type: 'index-selector',
-                              text: '0',
-                              start: 13,
-                              length: 1,
-                              children: []
-                            }
-                          ]
-                        },
-                        {
-                          type: 'text',
-                          text: ']',
-                          start: 14,
-                          length: 1,
-                          children: []
-                        }
-                      ]
-                    }
-                  ]
-                }
-              ]
-            },
-            {
-              type: 'segment',
-              text: '.title',
-              start: 15,
-              length: 6,
-              children: [
-                {
-                  type: 'child-segment',
-                  text: '.title',
-                  start: 15,
-                  length: 6,
-                  children: [
-                    {
-                      type: 'text',
-                      text: '.',
-                      start: 15,
-                      length: 1,
-                      children: []
-                    },
-                    {
-                      type: 'member-name-shorthand',
-                      text: 'title',
-                      start: 16,
-                      length: 5,
-                      children: []
-                    }
-                  ]
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    }
-  }
+  result: <ParseResult['result]>,
+  tree: <ParseResult['tree']>,
+  stats: <ParseResult['stats']>,
+  trace: <ParseResult['trace']>,
 }
 ```
 
-###### Concrete Syntax Tree (CST)
+[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.
 
-[Concrete Syntax Tree](https://en.wikipedia.org/wiki/Parse_tree) (Parse tree) is available on parse result via `computed` field.
-Instance of `JSONPathQueryCST` needs to be assigned to `ast` option in `parse` function (default behavior).
+##### Translators
+
+`@swaggerexpert/jsonpath` provides several translators to convert the parse result into different tree representations.
+
+###### CST translator
+
+[Concrete Syntax Tree](https://en.wikipedia.org/wiki/Parse_tree) (Parse tree) representation is available on parse result
+by default or when instance of `CSTTranslator` is provided via a `translator` option to the `parse` function.
 CST is suitable to be consumed by other tools like IDEs, editors, etc...
 
 ```js
 import { parse } from '@swaggerexpert/jsonpath';
 
-const { computed: CST } = parse('$.store.book[0].title');
+const { tree: CST } = parse('$.store.book[0].title');
 ```
 
 or
 
 ```js
-import { parse, JSONPathQueryCST } from '@swaggerexpert/jsonpath';
+import { parse, CSTTranslator } from '@swaggerexpert/jsonpath';
+
+const { tree: CST } = parse('$.store.book[0].title', { translator: new CSTTranslator() });
+```
 
-const { computed: CST } = parse('$.store.book[0].title', { ast: new JSONPathQueryCST() });
+CST tree has the following shape:
+
+```ts
+interface CSTTree {
+  readonly root: CSTNode;
+}
+interface CSTNode {
+  readonly type: string,
+  readonly text: string,
+  readonly start: number,
+  readonly length: number,
+  readonly children: CSTNode[],
+}
 ```
 
-###### Interpreting Parse result as XML
+###### XML translator
 
 ```js
-import { parse } from '@swaggerexpert/jsonpath';
+import { parse, XMLTranslator } from '@swaggerexpert/jsonpath';
 
-const parseResult = parse('$.store.book[0].title');
-const xml = parseResult.ast.toXml();
+const { tree: XML } = parse('$.store.book[0].title', { translator: new XMLTranslator() });
 ```
 
-###### Statistics
+##### Statistics
 
 `parse` function returns additional statistical information about the parsing process.
 Collection of the statistics can be enabled by setting `stats` option to `true`.
@@ -303,7 +152,7 @@ stats.displayStats(); // returns operator stats
 stats.displayHits(); // returns rules grouped by hit count
 ```
 
-###### Tracing
+##### Tracing
 
 `parse` function returns additional tracing information about the parsing process.
 Tracing can be enabled by setting `trace` option to `true`. Tracing is essential

package/cjs/grammar.cjs

@@ -2720,7 +2720,7 @@ function grammar() {
     str += "comparable          = singular-query / ; singular query value\n";
     str += "                      function-expr /  ; ValueType\n";
     str += "                      literal\n";
-    str += "                      ; MODIFICATION: https://www.rfc-editor.org/errata/eid8343\n";
+    str += "                      ; MODIFICATION: https://www.rfc-editor.org/errata/eid8352\n";
     str += "comparison-op       = \"==\" / \"!=\" /\n";
     str += "                      \"<=\" / \">=\" /\n";
     str += "                      \"<\"  / \">\"\n";

package/cjs/index.cjs

@@ -1,13 +1,13 @@
 "use strict";
 
 exports.__esModule = true;
-exports.translateEvaluator = exports.parse = exports.JSONPathQueryCST = exports.Grammar = void 0;
+exports.parse = exports.XMLTranslator = exports.Grammar = exports.CSTTranslator = void 0;
 var _grammar = _interopRequireDefault(require("./grammar.cjs"));
 exports.Grammar = _grammar.default;
 var _index = _interopRequireDefault(require("./parse/index.cjs"));
 exports.parse = _index.default;
-var _JSONPathQueryCST = _interopRequireDefault(require("./parse/ast/JSONPathQueryCST.cjs"));
-exports.JSONPathQueryCST = _JSONPathQueryCST.default;
-var _translate = _interopRequireDefault(require("./parse/evaluators/translate.cjs"));
-exports.translateEvaluator = _translate.default;
+var _CSTTranslator = _interopRequireDefault(require("./parse/translators/CSTTranslator.cjs"));
+exports.CSTTranslator = _CSTTranslator.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

@@ -10,10 +10,6 @@ const cst = ruleName => {
     if (!(typeof data === 'object' && data !== null && !Array.isArray(data))) {
       throw new _JSONPathParseError.default("parser's user data must be an object");
     }
-    if (!data.stack) {
-      data.stack = [];
-      data.root = null;
-    }
 
     // drop the empty nodes
     if (phraseLength === 0) return;

package/cjs/parse/index.cjs

@@ -4,35 +4,30 @@ exports.__esModule = true;
 exports.default = void 0;
 var _apgLite = require("../apg-lite.cjs");
 var _grammar = _interopRequireDefault(require("../grammar.cjs"));
-var _translate = _interopRequireDefault(require("./evaluators/translate.cjs"));
-var _JSONPathQueryCST = _interopRequireDefault(require("./ast/JSONPathQueryCST.cjs"));
+var _CSTTranslator = _interopRequireDefault(require("./translators/CSTTranslator.cjs"));
 var _JSONPathParseError = _interopRequireDefault(require("../errors/JSONPathParseError.cjs"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const grammar = new _grammar.default();
 const parse = (jsonPath, {
-  ast = new _JSONPathQueryCST.default(),
+  translator = new _CSTTranslator.default(),
   stats = false,
-  trace = false,
-  evaluator = _translate.default
+  trace = false
 } = {}) => {
   if (typeof jsonPath !== 'string') {
     throw new TypeError('JSONPath must be a string');
   }
   try {
+    var _parser$ast;
     const parser = new _apgLite.Parser();
-    parser.ast = ast;
+    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 computed = evaluator(ast, {
-      result
-    });
     return {
       result,
-      ast,
+      tree: (_parser$ast = parser.ast) == null ? void 0 : _parser$ast.getTree(),
       stats: parser.stats,
-      trace: parser.trace,
-      computed
+      trace: parser.trace
     };
   } catch (error) {
     throw new _JSONPathParseError.default('Unexpected error during JSONPath parsing', {

package/cjs/parse/{ast/JSONPathQueryCST.cjs → translators/CSTTranslator.cjs}

@@ -5,7 +5,7 @@ exports.default = void 0;
 var _apgLite = require("../../apg-lite.cjs");
 var _cst = _interopRequireDefault(require("../callbacks/cst.cjs"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-class JSONPathQueryCST extends _apgLite.Ast {
+class CSTTranslator extends _apgLite.Ast {
   constructor() {
     super();
 
@@ -97,5 +97,14 @@ class JSONPathQueryCST extends _apgLite.Ast {
     this.callbacks['left-paren'] = (0, _cst.default)('text');
     this.callbacks['right-paren'] = (0, _cst.default)('text');
   }
+  getTree() {
+    const data = {
+      stack: [],
+      root: null
+    };
+    this.translate(data);
+    delete data.stack;
+    return data;
+  }
 }
-var _default = exports.default = JSONPathQueryCST;
+var _default = exports.default = CSTTranslator;

package/cjs/parse/translators/XMLTranslator.cjs

@@ -0,0 +1,12 @@
+"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 XMLTranslator extends _CSTTranslator.default {
+  getTree() {
+    return this.toXml();
+  }
+}
+var _default = exports.default = XMLTranslator;

package/es/grammar.mjs

@@ -2716,7 +2716,7 @@ export default function grammar() {
     str += "comparable          = singular-query / ; singular query value\n";
     str += "                      function-expr /  ; ValueType\n";
     str += "                      literal\n";
-    str += "                      ; MODIFICATION: https://www.rfc-editor.org/errata/eid8343\n";
+    str += "                      ; MODIFICATION: https://www.rfc-editor.org/errata/eid8352\n";
     str += "comparison-op       = \"==\" / \"!=\" /\n";
     str += "                      \"<=\" / \">=\" /\n";
     str += "                      \"<\"  / \">\"\n";

package/es/index.mjs

@@ -1,4 +1,4 @@
 export { default as Grammar } from "./grammar.mjs";
 export { default as parse } from "./parse/index.mjs";
-export { default as JSONPathQueryCST } from "./parse/ast/JSONPathQueryCST.mjs";
-export { default as translateEvaluator } from "./parse/evaluators/translate.mjs";
+export { default as CSTTranslator } from "./parse/translators/CSTTranslator.mjs";
+export { default as XMLTranslator } from "./parse/translators/XMLTranslator.mjs";

package/es/parse/callbacks/cst.mjs

@@ -5,10 +5,6 @@ const cst = ruleName => {
     if (!(typeof data === 'object' && data !== null && !Array.isArray(data))) {
       throw new JSONPathParseError("parser's user data must be an object");
     }
-    if (!data.stack) {
-      data.stack = [];
-      data.root = null;
-    }
 
     // drop the empty nodes
     if (phraseLength === 0) return;

package/es/parse/index.mjs

@@ -1,33 +1,28 @@
 import { Parser, Stats, Trace } from 'apg-lite';
 import Grammar from "../grammar.mjs";
-import translateEvaluator from "./evaluators/translate.mjs";
-import JSONPathQueryCST from "./ast/JSONPathQueryCST.mjs";
+import CSTTranslator from "./translators/CSTTranslator.mjs";
 import JSONPathParseError from "../errors/JSONPathParseError.mjs";
 const grammar = new Grammar();
 const parse = (jsonPath, {
-  ast = new JSONPathQueryCST(),
+  translator = new CSTTranslator(),
   stats = false,
-  trace = false,
-  evaluator = translateEvaluator
+  trace = false
 } = {}) => {
   if (typeof jsonPath !== 'string') {
     throw new TypeError('JSONPath must be a string');
   }
   try {
+    var _parser$ast;
     const parser = new Parser();
-    parser.ast = ast;
+    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 computed = evaluator(ast, {
-      result
-    });
     return {
       result,
-      ast,
+      tree: (_parser$ast = parser.ast) === null || _parser$ast === void 0 ? void 0 : _parser$ast.getTree(),
       stats: parser.stats,
-      trace: parser.trace,
-      computed
+      trace: parser.trace
     };
   } catch (error) {
     throw new JSONPathParseError('Unexpected error during JSONPath parsing', {

package/es/parse/{ast/JSONPathQueryCST.mjs → translators/CSTTranslator.mjs}

@@ -1,6 +1,6 @@
 import { Ast as AST } from 'apg-lite';
 import cstCallback from "../callbacks/cst.mjs";
-class JSONPathQueryCST extends AST {
+class CSTTranslator extends AST {
   constructor() {
     super();
 
@@ -92,5 +92,14 @@ class JSONPathQueryCST extends AST {
     this.callbacks['left-paren'] = cstCallback('text');
     this.callbacks['right-paren'] = cstCallback('text');
   }
+  getTree() {
+    const data = {
+      stack: [],
+      root: null
+    };
+    this.translate(data);
+    delete data.stack;
+    return data;
+  }
 }
-export default JSONPathQueryCST;
+export default CSTTranslator;

package/es/parse/translators/XMLTranslator.mjs

@@ -0,0 +1,7 @@
+import CSTTranslator from "./CSTTranslator.mjs";
+class XMLTranslator extends CSTTranslator {
+  getTree() {
+    return this.toXml();
+  }
+}
+export default XMLTranslator;

package/package.json

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

package/types/index.d.ts

@@ -4,22 +4,33 @@
 export function parse(jsonpath: string, options?: ParseOptions): ParseResult;
 
 export interface ParseOptions {
-  readonly ast?: AST;
+  readonly translator?: Translator | null;
   readonly stats?: boolean;
   readonly trace?: boolean;
 }
 
-export interface AST {
-  readonly translate: (parts: Record<string, CSTNode>) => Record<string, CSTNode>;
-  readonly toXml: () => string;
+export interface Translator<TTree = unknown> {
+  getTree(): TTree;
+}
+export declare class CSTTranslator implements Translator<CSTTree> {
+  getTree(): CSTTree;
+}
+export declare class XMLTranslator implements Translator<XMLTree> {
+  getTree(): XMLTree;
 }
 
-export interface ParseResult {
+export interface ParseResult<TTree = unknown> {
   readonly result: {
     readonly success: boolean;
+    readonly state: number;
+    readonly stateName: string;
+    readonly length: number;
+    readonly matched: number;
+    readonly maxMatched: number;
+    readonly maxTreeDepth: number
+    readonly nodeHits: number;
   };
-  readonly ast: AST;
-  readonly computed: Record<string, CSTNode>;
+  readonly tree: TTree;
   readonly stats?: Stats;
   readonly trace?: Trace;
 }
@@ -32,6 +43,12 @@ export interface CSTNode {
   readonly children: CSTNode[],
 }
 
+export interface CSTTree {
+  readonly root: CSTNode;
+}
+
+export type XMLTree = string;
+
 export interface Stats {
   displayStats(): string;
   displayHits(): string;

package/cjs/parse/evaluators/translate.cjs

@@ -1,13 +0,0 @@
-"use strict";
-
-exports.__esModule = true;
-exports.default = void 0;
-const translateEvaluator = (ast, {
-  result
-}) => {
-  if (!result.success) return null;
-  const parts = {};
-  ast.translate(parts);
-  return parts;
-};
-var _default = exports.default = translateEvaluator;

package/es/parse/evaluators/translate.mjs

@@ -1,9 +0,0 @@
-const translateEvaluator = (ast, {
-  result
-}) => {
-  if (!result.success) return null;
-  const parts = {};
-  ast.translate(parts);
-  return parts;
-};
-export default translateEvaluator;