@swaggerexpert/jsonpath 1.1.0 → 1.2.0

package/README.md

@@ -32,7 +32,8 @@ The development of this library contributed to the identification and formal sub
     - [Parsing](#parsing)
       - [Concrete Syntax Tree (CST)](#concrete-syntax-tree-cst)
       - [Interpreting Parse result as XML](#interpreting-parse-result-as-xml)
-      - [Parse statistics](#parse-statistics)
+      - [Statistics](#statistics)
+      - [Tracing](#tracing)
     - [Errors](#errors)
     - [Grammar](#grammar)
 - [More about JSONPath](#more-about-jsonpath)
@@ -288,7 +289,7 @@ const parseResult = parse('$.store.book[0].title');
 const xml = parseResult.ast.toXml();
 ```
 
-###### Parse 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`.
@@ -302,6 +303,25 @@ 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,

package/cjs/parse/index.cjs

@@ -12,6 +12,7 @@ const grammar = new _grammar.default();
 const parse = (jsonPath, {
   ast = new _JSONPathQueryCST.default(),
   stats = false,
+  trace = false,
   evaluator = _translate.default
 } = {}) => {
   if (typeof jsonPath !== 'string') {
@@ -21,6 +22,7 @@ const parse = (jsonPath, {
     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
@@ -29,6 +31,7 @@ const parse = (jsonPath, {
       result,
       ast,
       stats: parser.stats,
+      trace: parser.trace,
       computed
     };
   } catch (error) {

package/es/parse/index.mjs

@@ -1,4 +1,4 @@
-import { Parser, Stats } 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";
@@ -7,6 +7,7 @@ const grammar = new Grammar();
 const parse = (jsonPath, {
   ast = new JSONPathQueryCST(),
   stats = false,
+  trace = false,
   evaluator = translateEvaluator
 } = {}) => {
   if (typeof jsonPath !== 'string') {
@@ -16,6 +17,7 @@ const parse = (jsonPath, {
     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
@@ -24,6 +26,7 @@ const parse = (jsonPath, {
       result,
       ast,
       stats: parser.stats,
+      trace: parser.trace,
       computed
     };
   } catch (error) {

package/package.json

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

package/types/index.d.ts

@@ -6,6 +6,7 @@ export function parse(jsonpath: string, options?: ParseOptions): ParseResult;
 export interface ParseOptions {
   readonly ast?: AST;
   readonly stats?: boolean;
+  readonly trace?: boolean;
 }
 
 export interface AST {
@@ -20,6 +21,7 @@ export interface ParseResult {
   readonly ast: AST;
   readonly computed: Record<string, CSTNode>;
   readonly stats?: Stats;
+  readonly trace?: Trace;
 }
 
 export interface CSTNode {
@@ -35,6 +37,10 @@ export interface Stats {
   displayHits(): string;
 }
 
+export interface Trace {
+  displayTrace(): string;
+}
+
 /**
  * Grammar
  */