@swaggerexpert/jsonpath 1.0.2 → 1.2.0

package/README.md

@@ -30,6 +30,10 @@ 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)
+      - [Statistics](#statistics)
+      - [Tracing](#tracing)
     - [Errors](#errors)
     - [Grammar](#grammar)
 - [More about JSONPath](#more-about-jsonpath)
@@ -256,7 +260,27 @@ const parseResult = parse('$.store.book[0].title', { ast: new JSONPathQueryCST()
 }
 ```
 
-###### Interpreting AST as XML
+###### Concrete Syntax Tree (CST)
+
+[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).
+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');
+```
+
+or
+
+```js
+import { parse, JSONPathQueryCST } from '@swaggerexpert/jsonpath';
+
+const { computed: CST } = parse('$.store.book[0].title', { ast: new JSONPathQueryCST() });
+```
+
+###### Interpreting Parse result as XML
 
 ```js
 import { parse } from '@swaggerexpert/jsonpath';
@@ -265,6 +289,39 @@ const parseResult = parse('$.store.book[0].title');
 const xml = parseResult.ast.toXml();
 ```
 
+###### Statistics
+
+`parse` function returns additional statistical information about the parsing process.
+Collection of the statistics can be enabled by setting `stats` option to `true`.
+
+```js
+import { parse } from '@swaggerexpert/jsonpath';
+
+const { stats } = parse('$.store.book[0].title', { stats: true });
+
+stats.displayStats(); // returns operator stats
+stats.displayHits(); // returns rules grouped by hit count
+```
+
+###### Tracing
+
+`parse` function returns additional tracing information about the parsing process.
+Tracing can be enabled by setting `trace` option to `true`. Tracing is essential
+for debugging failed matches or analyzing rule execution flow.
+
+```js
+import { parse } from '@swaggerexpert/jsonpath';
+
+const { result, trace } = parse('$fdfadfd', { trace: true });
+
+result.success; // returns false
+trace.displayTrace(); // returns trace information
+```
+
+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
+[test file](https://github.com/swaggerexpert/jsonpath/blob/main/test/parse/trace.js) for more information how to achieve that.
+
 #### Errors
 
 `@swaggerexpert/jsonpath` provides a structured error class hierarchy,
@@ -453,8 +510,8 @@ LCALPHA             = %x61-7A  ; "a".."z"
 function-expr       = function-name left-paren S [function-argument ; MODIFICATION: surrogate text rule used
                          *(S comma S function-argument)] S right-paren ; MODIFICATION: surrogate text rule used
 function-argument   = logical-expr / ; MODIFICATION: https://www.rfc-editor.org/errata/eid8343
-                      function-expr /
                       filter-query / ; (includes singular-query)
+                      function-expr /
                       literal
 
 

package/cjs/parse/index.cjs

@@ -11,6 +11,8 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 const grammar = new _grammar.default();
 const parse = (jsonPath, {
   ast = new _JSONPathQueryCST.default(),
+  stats = false,
+  trace = false,
   evaluator = _translate.default
 } = {}) => {
   if (typeof jsonPath !== 'string') {
@@ -19,6 +21,8 @@ const parse = (jsonPath, {
   try {
     const parser = new _apgLite.Parser();
     parser.ast = ast;
+    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
@@ -26,6 +30,8 @@ const parse = (jsonPath, {
     return {
       result,
       ast,
+      stats: parser.stats,
+      trace: parser.trace,
       computed
     };
   } catch (error) {

package/es/parse/index.mjs

@@ -1,4 +1,4 @@
-import { Parser } from 'apg-lite';
+import { Parser, Stats, Trace } from 'apg-lite';
 import Grammar from "../grammar.mjs";
 import translateEvaluator from "./evaluators/translate.mjs";
 import JSONPathQueryCST from "./ast/JSONPathQueryCST.mjs";
@@ -6,6 +6,8 @@ import JSONPathParseError from "../errors/JSONPathParseError.mjs";
 const grammar = new Grammar();
 const parse = (jsonPath, {
   ast = new JSONPathQueryCST(),
+  stats = false,
+  trace = false,
   evaluator = translateEvaluator
 } = {}) => {
   if (typeof jsonPath !== 'string') {
@@ -14,6 +16,8 @@ const parse = (jsonPath, {
   try {
     const parser = new Parser();
     parser.ast = ast;
+    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
@@ -21,6 +25,8 @@ const parse = (jsonPath, {
     return {
       result,
       ast,
+      stats: parser.stats,
+      trace: parser.trace,
       computed
     };
   } catch (error) {

package/package.json

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

package/types/index.d.ts

@@ -5,6 +5,8 @@ export function parse(jsonpath: string, options?: ParseOptions): ParseResult;
 
 export interface ParseOptions {
   readonly ast?: AST;
+  readonly stats?: boolean;
+  readonly trace?: boolean;
 }
 
 export interface AST {
@@ -18,14 +20,25 @@ export interface ParseResult {
   };
   readonly ast: AST;
   readonly computed: Record<string, CSTNode>;
+  readonly stats?: Stats;
+  readonly trace?: Trace;
 }
 
 export interface CSTNode {
-  type: string,
-  text: string,
-  start: number,
-  length: number,
-  children: CSTNode[],
+  readonly type: string,
+  readonly text: string,
+  readonly start: number,
+  readonly length: number,
+  readonly children: CSTNode[],
+}
+
+export interface Stats {
+  displayStats(): string;
+  displayHits(): string;
+}
+
+export interface Trace {
+  displayTrace(): string;
 }
 
 /**