@swaggerexpert/jsonpath 2.5.0 → 3.0.0

package/README.md

@@ -38,6 +38,7 @@ The development of this library contributed to the identification and formal sub
       - [Translators](#translators)
         - [CST](#cst-translator)
         - [CST Optimized](#cst-optimized-translator)
+        - [AST](#ast-translator)
         - [XML](#xml-translator)
       - [Statistics](#statistics)
       - [Tracing](#tracing)
@@ -118,37 +119,16 @@ parse("$['\\u000b']", { normalized: true });
 ###### 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.
+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 { tree: CST } = parse('$.store.book[0].title');
-```
-
-or
-
 ```js
 import { parse, CSTTranslator } from '@swaggerexpert/jsonpath';
 
 const { tree: CST } = parse('$.store.book[0].title', { translator: new CSTTranslator() });
 ```
 
-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[],
-}
-```
+CST tree has a shape documented by [TypeScript typings (CSTTree)](https://github.com/swaggerexpert/jsonpath/blob/main/types/index.d.ts).
 
 ###### CST Optimized translator
 
@@ -162,6 +142,29 @@ import { parse, CSTOptimizedTranslator } from '@swaggerexpert/jsonpath';
 const { tree: CST } = parse('$.store.book[0].title', { translator: new CSTOptimizedTranslator() });
 ```
 
+###### AST translator
+
+**Default translator**. [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) representation is available on parse result
+by default or when instance of `ASTTranslator` is provided via a `translator` option to the `parse` function.
+AST is suitable to be consumed by implementations that need to analyze the structure of the JSONPath expression
+or for building a custom JSONPath evaluation engine.
+
+```js
+import { parse } from '@swaggerexpert/jsonpath';
+
+const { tree: AST } = parse('$.store.book[0].title');
+```
+
+or
+
+```js
+import { parse, ASTTranslator } from '@swaggerexpert/jsonpath';
+
+const { tree: AST } = parse('$.store.book[0].title', { translator: new ASTTranslator() });
+```
+
+AST tree has a shape documented by [TypeScript typings (ASTTree)](https://github.com/swaggerexpert/jsonpath/blob/main/types/index.d.ts).
+
 ###### XML translator
 
 ```js
@@ -214,7 +217,7 @@ test('$.store.book[0].title'); // => true
 test('$$'); // => false
 ```
 
-Normalized paths can be validated by setting `normalized` option to `true`.
+**Normalized paths** can be validated by setting `normalized` option to `true`.
 
 ```js
 import { test } from '@swaggerexpert/jsonpath';

package/cjs/index.cjs

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

package/cjs/parse/index.cjs

@@ -4,7 +4,7 @@ exports.__esModule = true;
 exports.default = void 0;
 var _apgLite = require("../apg-lite.cjs");
 var _grammar = _interopRequireDefault(require("../grammar.cjs"));
-var _CSTTranslator = _interopRequireDefault(require("./translators/CSTTranslator.cjs"));
+var _index = _interopRequireDefault(require("./translators/ASTTranslator/index.cjs"));
 var _JSONPathParseError = _interopRequireDefault(require("../errors/JSONPathParseError.cjs"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const grammar = new _grammar.default();
@@ -12,7 +12,7 @@ const parse = (jsonPath, {
   normalized = false,
   stats = false,
   trace = false,
-  translator = new _CSTTranslator.default()
+  translator = new _index.default()
 } = {}) => {
   if (typeof jsonPath !== 'string') {
     throw new TypeError('JSONPath must be a string');

package/cjs/parse/translators/ASTTranslator/decoders.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+exports.__esModule = true;
+exports.decodeString = exports.decodeJSONValue = exports.decodeInteger = void 0;
+const decodeString = str => {
+  return JSON.parse(`"${str.replace(/"/g, '\\"')}"`);
+};
+exports.decodeString = decodeString;
+const decodeInteger = str => {
+  return parseInt(str, 10);
+};
+exports.decodeInteger = decodeInteger;
+const decodeJSONValue = str => {
+  return JSON.parse(str);
+};
+exports.decodeJSONValue = decodeJSONValue;

package/cjs/parse/translators/ASTTranslator/index.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _CSTOptimizedTranslator = _interopRequireDefault(require("../CSTOptimizedTranslator.cjs"));
+var _transformers = _interopRequireWildcard(require("./transformers.cjs"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class ASTTranslator extends _CSTOptimizedTranslator.default {
+  getTree() {
+    const cst = super.getTree();
+    return (0, _transformers.transformCSTtoAST)(cst.root, _transformers.default);
+  }
+}
+var _default = exports.default = ASTTranslator;

package/cjs/parse/translators/ASTTranslator/transformers.cjs

@@ -0,0 +1,410 @@
+"use strict";
+
+exports.__esModule = true;
+exports.transformCSTtoAST = exports.default = void 0;
+var _JSONPathParseError = _interopRequireDefault(require("../../../errors/JSONPathParseError.cjs"));
+var _decoders = require("./decoders.cjs");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const transformCSTtoAST = (node, transformerMap, ctx = {
+  parent: null,
+  path: []
+}) => {
+  const transformer = transformerMap[node.type];
+  if (!transformer) {
+    throw new _JSONPathParseError.default(`No transformer for CST node type: ${node.type}`);
+  }
+  const nextCtx = {
+    parent: node,
+    path: [...ctx.path, node]
+  };
+  return transformer(node, nextCtx);
+};
+exports.transformCSTtoAST = transformCSTtoAST;
+const transformers = {
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.1.1
+   */
+  ['jsonpath-query'](node, ctx) {
+    const segments = node.children.find(c => c.type === 'segments');
+    return {
+      type: 'JsonPathQuery',
+      segments: segments ? segments.children.filter(({
+        type
+      }) => type === 'segment').map(segNode => transformCSTtoAST(segNode, transformers, ctx)) : []
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.5
+   */
+  segment(node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['child-segment', 'descendant-segment'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3
+   */
+  selector(node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['name-selector', 'wildcard-selector', 'slice-selector', 'index-selector', 'filter-selector'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.1.1
+   */
+  ['name-selector'](node, ctx) {
+    const stringLiteralCSTNode = node.children.find(({
+      type
+    }) => type === 'string-literal');
+    const stringLiteralASTNode = transformCSTtoAST(stringLiteralCSTNode, transformers, ctx);
+    return {
+      type: 'NameSelector',
+      value: stringLiteralASTNode.value,
+      format: stringLiteralASTNode.format
+    };
+  },
+  ['string-literal'](node) {
+    const isSingleQuoted = node.children.find(({
+      type,
+      text
+    }) => type === 'text' && text === "'");
+    const quoted = node.children.find(({
+      type
+    }) => ['double-quoted', 'single-quoted'].includes(type));
+    return {
+      type: 'StringLiteral',
+      value: quoted ? (0, _decoders.decodeString)(quoted.text) : '',
+      format: isSingleQuoted ? 'single-quoted' : 'double-quoted'
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.2.1
+   */
+  ['wildcard-selector']() {
+    return {
+      type: 'WildcardSelector'
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.3.1
+   */
+  ['index-selector'](node) {
+    return {
+      type: 'IndexSelector',
+      value: (0, _decoders.decodeInteger)(node.text)
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.4.1
+   */
+  ['slice-selector'](node) {
+    const start = node.children.find(({
+      type
+    }) => type === 'start');
+    const end = node.children.find(({
+      type
+    }) => type === 'end');
+    const step = node.children.find(({
+      type
+    }) => type === 'step');
+    return {
+      type: 'SliceSelector',
+      start: start ? (0, _decoders.decodeInteger)(start.text) : null,
+      end: end ? (0, _decoders.decodeInteger)(end.text) : null,
+      step: step ? (0, _decoders.decodeInteger)(step.text) : null
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.1
+   */
+  ['filter-selector'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'logical-expr');
+    return {
+      type: 'FilterSelector',
+      expression: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['logical-expr'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'logical-or-expr');
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['logical-or-expr'](node, ctx) {
+    const logicalAndExprs = node.children.filter(({
+      type
+    }) => type === 'logical-and-expr');
+    if (logicalAndExprs.length === 1) {
+      return transformCSTtoAST(logicalAndExprs[0], transformers, ctx);
+    }
+
+    // fold left for left-associativity
+    let left = transformCSTtoAST(logicalAndExprs[0], transformers, ctx);
+    for (let i = 1; i < logicalAndExprs.length; i += 1) {
+      const right = transformCSTtoAST(logicalAndExprs[i], transformers, ctx);
+      left = {
+        type: 'LogicalOrExpr',
+        left,
+        right
+      };
+    }
+  },
+  ['logical-and-expr'](node, ctx) {
+    const basicExprs = node.children.filter(({
+      type
+    }) => type === 'basic-expr');
+    if (basicExprs.length === 1) {
+      return transformCSTtoAST(basicExprs[0], transformers, ctx);
+    }
+    let left = transformCSTtoAST(basicExprs[0], transformers, ctx);
+    for (let i = 1; i < basicExprs.length; i += 1) {
+      const right = transformCSTtoAST(basicExprs[i], transformers, ctx);
+      left = {
+        type: 'LogicalAndExpr',
+        left,
+        right
+      };
+    }
+    return left;
+  },
+  ['basic-expr'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['paren-expr', 'comparison-expr', 'test-expr'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['paren-expr'](node, ctx) {
+    const isNegated = node.children.some(child => child.type === 'logical-not-op');
+    const logicalExprCSTNode = node.children.find(child => child.type === 'logical-expr');
+    const logicalExpressionASTNode = transformCSTtoAST(logicalExprCSTNode, transformers, ctx);
+    if (isNegated) {
+      return {
+        type: 'LogicalNotExpr',
+        expression: logicalExpressionASTNode
+      };
+    }
+    return logicalExpressionASTNode;
+  },
+  ['test-expr'](node, ctx) {
+    const isNegated = node.children.some(({
+      type
+    }) => type === 'logical-not-op');
+    const expression = node.children.find(({
+      type
+    }) => ['filter-query', 'function-expr'].includes(type));
+    const testExpr = {
+      type: 'TestExpr',
+      expression: transformCSTtoAST(expression, transformers, ctx)
+    };
+    return isNegated ? {
+      type: 'LogicalNotExpr',
+      expression: testExpr
+    } : testExpr;
+  },
+  ['filter-query'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['rel-query', 'jsonpath-query'].includes(type));
+    return {
+      type: 'FilterQuery',
+      query: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['rel-query'](node, ctx) {
+    const segments = node.children.find(c => c.type === 'segments');
+    return {
+      type: 'RelQuery',
+      segments: segments ? segments.children.filter(n => n.type === 'segment').map(segNode => transformCSTtoAST(segNode, transformers, ctx)) : []
+    };
+  },
+  ['comparison-expr'](node, ctx) {
+    const children = node.children.filter(({
+      type
+    }) => ['comparable', 'comparison-op'].includes(type));
+    const [left, op, right] = children;
+    return {
+      type: 'ComparisonExpr',
+      left: transformCSTtoAST(left, transformers, ctx),
+      op: op.text,
+      right: transformCSTtoAST(right, transformers, ctx)
+    };
+  },
+  ['literal'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['number', 'string-literal', 'true', 'false', 'null'].includes(type));
+    if (child.type === 'string-literal') {
+      const stringLiteralASTNode = transformCSTtoAST(child, transformers, ctx);
+      return {
+        type: 'Literal',
+        value: stringLiteralASTNode.value
+      };
+    }
+    return {
+      type: 'Literal',
+      value: (0, _decoders.decodeJSONValue)(child.text)
+    };
+  },
+  ['comparable'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['singular-query', 'function-expr', 'literal'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['singular-query'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['rel-singular-query', 'abs-singular-query'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['rel-singular-query'](node, ctx) {
+    const segmentsNode = node.children.find(({
+      type
+    }) => type === 'singular-query-segments');
+    const segments = segmentsNode ? segmentsNode.children.filter(({
+      type
+    }) => ['name-segment', 'index-segment'].includes(type)).map(segNode => ({
+      type: 'SingularQuerySegment',
+      selector: transformCSTtoAST(segNode, transformers, ctx)
+    })) : [];
+    return {
+      type: 'RelSingularQuery',
+      segments
+    };
+  },
+  ['abs-singular-query'](node, ctx) {
+    const segmentsNode = node.children.find(({
+      type
+    }) => type === 'singular-query-segments');
+    const segments = segmentsNode ? segmentsNode.children.filter(({
+      type
+    }) => ['name-segment', 'index-segment'].includes(type)).map(segNode => ({
+      type: 'SingularQuerySegment',
+      selector: transformCSTtoAST(segNode, transformers, ctx)
+    })) : [];
+    return {
+      type: 'AbsSingularQuery',
+      segments
+    };
+  },
+  ['name-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['name-selector', 'member-name-shorthand'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['index-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'index-selector');
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+   */
+  ['function-expr'](node, ctx) {
+    const name = node.children.find(({
+      type
+    }) => type === 'function-name');
+    const args = node.children.filter(({
+      type
+    }) => type === 'function-argument');
+    return {
+      type: 'FunctionExpr',
+      name: name.text,
+      arguments: args.map(arg => transformCSTtoAST(arg, transformers, ctx))
+    };
+  },
+  ['function-argument'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['logical-expr', 'function-expr', 'filter-query', 'literal'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.5.1.1
+   */
+  ['child-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['bracketed-selection', 'wildcard-selector', 'member-name-shorthand'].includes(type));
+    return {
+      type: 'ChildSegment',
+      selector: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['bracketed-selection'](node, ctx) {
+    return {
+      type: 'BracketedSelection',
+      selectors: node.children.filter(({
+        type
+      }) => type === 'selector').map(selectorNode => transformCSTtoAST(selectorNode, transformers, ctx))
+    };
+  },
+  ['member-name-shorthand'](node) {
+    return {
+      type: 'NameSelector',
+      value: node.text,
+      format: 'shorthand'
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.5.2.1
+   */
+  ['descendant-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['bracketed-selection', 'wildcard-selector', 'member-name-shorthand'].includes(type));
+    return {
+      type: 'DescendantSegment',
+      selector: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
+   */
+  ['normalized-path'](node, ctx) {
+    return {
+      type: 'JsonPathQuery',
+      segments: node.children.filter(({
+        type
+      }) => type === 'normal-index-segment').map(segNode => transformCSTtoAST(segNode, transformers, ctx))
+    };
+  },
+  ['normal-index-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'normal-selector');
+    return {
+      type: 'ChildSegment',
+      selector: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['normal-selector'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['normal-name-selector', 'normal-index-selector'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['normal-name-selector'](node) {
+    const child = node.children.find(({
+      type
+    }) => type === 'normal-single-quoted');
+    return {
+      type: 'NameSelector',
+      value: child ? (0, _decoders.decodeString)(child.text) : '',
+      format: 'single-quoted'
+    };
+  },
+  ['normal-index-selector'](node) {
+    return {
+      type: 'IndexSelector',
+      value: (0, _decoders.decodeInteger)(node.text)
+    };
+  }
+};
+var _default = exports.default = transformers;

package/cjs/parse/translators/CSTOptimizedTranslator.cjs

@@ -8,12 +8,16 @@ class CSTOptimizedTranslator extends _CSTTranslator.default {
   collapsibleTypes = ['single-quoted', 'double-quoted', 'normal-single-quoted'];
   droppableTypes = ['text', 'segments', 'singular-query-segments'];
   constructor({
-    collapsibleTypes
+    collapsibleTypes,
+    droppableTypes
   } = {}) {
     super();
     if (Array.isArray(collapsibleTypes)) {
       this.collapsibleTypes = collapsibleTypes;
     }
+    if (Array.isArray(droppableTypes)) {
+      this.droppableTypes = droppableTypes;
+    }
   }
   getTree() {
     const options = {

package/es/index.mjs

@@ -2,5 +2,6 @@ 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 ASTTranslator } from "./parse/translators/ASTTranslator/index.mjs";
 export { default as XMLTranslator } from "./parse/translators/XMLTranslator.mjs";
 export { default as test } from "./test/index.mjs";

package/es/parse/index.mjs

@@ -1,13 +1,13 @@
 import { Parser, Stats, Trace } from 'apg-lite';
 import Grammar from "../grammar.mjs";
-import CSTTranslator from "./translators/CSTTranslator.mjs";
+import ASTTranslator from "./translators/ASTTranslator/index.mjs";
 import JSONPathParseError from "../errors/JSONPathParseError.mjs";
 const grammar = new Grammar();
 const parse = (jsonPath, {
   normalized = false,
   stats = false,
   trace = false,
-  translator = new CSTTranslator()
+  translator = new ASTTranslator()
 } = {}) => {
   if (typeof jsonPath !== 'string') {
     throw new TypeError('JSONPath must be a string');

package/es/parse/translators/ASTTranslator/decoders.mjs

@@ -0,0 +1,9 @@
+export const decodeString = str => {
+  return JSON.parse(`"${str.replace(/"/g, '\\"')}"`);
+};
+export const decodeInteger = str => {
+  return parseInt(str, 10);
+};
+export const decodeJSONValue = str => {
+  return JSON.parse(str);
+};

package/es/parse/translators/ASTTranslator/index.mjs

@@ -0,0 +1,9 @@
+import CSTOptimizedTranslator from "../CSTOptimizedTranslator.mjs";
+import { transformCSTtoAST, default as transformers } from "./transformers.mjs";
+class ASTTranslator extends CSTOptimizedTranslator {
+  getTree() {
+    const cst = super.getTree();
+    return transformCSTtoAST(cst.root, transformers);
+  }
+}
+export default ASTTranslator;

package/es/parse/translators/ASTTranslator/transformers.mjs

@@ -0,0 +1,404 @@
+import JSONPathParseError from "../../../errors/JSONPathParseError.mjs";
+import { decodeString, decodeInteger, decodeJSONValue } from "./decoders.mjs";
+export const transformCSTtoAST = (node, transformerMap, ctx = {
+  parent: null,
+  path: []
+}) => {
+  const transformer = transformerMap[node.type];
+  if (!transformer) {
+    throw new JSONPathParseError(`No transformer for CST node type: ${node.type}`);
+  }
+  const nextCtx = {
+    parent: node,
+    path: [...ctx.path, node]
+  };
+  return transformer(node, nextCtx);
+};
+const transformers = {
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.1.1
+   */
+  ['jsonpath-query'](node, ctx) {
+    const segments = node.children.find(c => c.type === 'segments');
+    return {
+      type: 'JsonPathQuery',
+      segments: segments ? segments.children.filter(({
+        type
+      }) => type === 'segment').map(segNode => transformCSTtoAST(segNode, transformers, ctx)) : []
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.5
+   */
+  segment(node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['child-segment', 'descendant-segment'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3
+   */
+  selector(node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['name-selector', 'wildcard-selector', 'slice-selector', 'index-selector', 'filter-selector'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.1.1
+   */
+  ['name-selector'](node, ctx) {
+    const stringLiteralCSTNode = node.children.find(({
+      type
+    }) => type === 'string-literal');
+    const stringLiteralASTNode = transformCSTtoAST(stringLiteralCSTNode, transformers, ctx);
+    return {
+      type: 'NameSelector',
+      value: stringLiteralASTNode.value,
+      format: stringLiteralASTNode.format
+    };
+  },
+  ['string-literal'](node) {
+    const isSingleQuoted = node.children.find(({
+      type,
+      text
+    }) => type === 'text' && text === "'");
+    const quoted = node.children.find(({
+      type
+    }) => ['double-quoted', 'single-quoted'].includes(type));
+    return {
+      type: 'StringLiteral',
+      value: quoted ? decodeString(quoted.text) : '',
+      format: isSingleQuoted ? 'single-quoted' : 'double-quoted'
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.2.1
+   */
+  ['wildcard-selector']() {
+    return {
+      type: 'WildcardSelector'
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.3.1
+   */
+  ['index-selector'](node) {
+    return {
+      type: 'IndexSelector',
+      value: decodeInteger(node.text)
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.4.1
+   */
+  ['slice-selector'](node) {
+    const start = node.children.find(({
+      type
+    }) => type === 'start');
+    const end = node.children.find(({
+      type
+    }) => type === 'end');
+    const step = node.children.find(({
+      type
+    }) => type === 'step');
+    return {
+      type: 'SliceSelector',
+      start: start ? decodeInteger(start.text) : null,
+      end: end ? decodeInteger(end.text) : null,
+      step: step ? decodeInteger(step.text) : null
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.1
+   */
+  ['filter-selector'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'logical-expr');
+    return {
+      type: 'FilterSelector',
+      expression: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['logical-expr'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'logical-or-expr');
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['logical-or-expr'](node, ctx) {
+    const logicalAndExprs = node.children.filter(({
+      type
+    }) => type === 'logical-and-expr');
+    if (logicalAndExprs.length === 1) {
+      return transformCSTtoAST(logicalAndExprs[0], transformers, ctx);
+    }
+
+    // fold left for left-associativity
+    let left = transformCSTtoAST(logicalAndExprs[0], transformers, ctx);
+    for (let i = 1; i < logicalAndExprs.length; i += 1) {
+      const right = transformCSTtoAST(logicalAndExprs[i], transformers, ctx);
+      left = {
+        type: 'LogicalOrExpr',
+        left,
+        right
+      };
+    }
+  },
+  ['logical-and-expr'](node, ctx) {
+    const basicExprs = node.children.filter(({
+      type
+    }) => type === 'basic-expr');
+    if (basicExprs.length === 1) {
+      return transformCSTtoAST(basicExprs[0], transformers, ctx);
+    }
+    let left = transformCSTtoAST(basicExprs[0], transformers, ctx);
+    for (let i = 1; i < basicExprs.length; i += 1) {
+      const right = transformCSTtoAST(basicExprs[i], transformers, ctx);
+      left = {
+        type: 'LogicalAndExpr',
+        left,
+        right
+      };
+    }
+    return left;
+  },
+  ['basic-expr'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['paren-expr', 'comparison-expr', 'test-expr'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['paren-expr'](node, ctx) {
+    const isNegated = node.children.some(child => child.type === 'logical-not-op');
+    const logicalExprCSTNode = node.children.find(child => child.type === 'logical-expr');
+    const logicalExpressionASTNode = transformCSTtoAST(logicalExprCSTNode, transformers, ctx);
+    if (isNegated) {
+      return {
+        type: 'LogicalNotExpr',
+        expression: logicalExpressionASTNode
+      };
+    }
+    return logicalExpressionASTNode;
+  },
+  ['test-expr'](node, ctx) {
+    const isNegated = node.children.some(({
+      type
+    }) => type === 'logical-not-op');
+    const expression = node.children.find(({
+      type
+    }) => ['filter-query', 'function-expr'].includes(type));
+    const testExpr = {
+      type: 'TestExpr',
+      expression: transformCSTtoAST(expression, transformers, ctx)
+    };
+    return isNegated ? {
+      type: 'LogicalNotExpr',
+      expression: testExpr
+    } : testExpr;
+  },
+  ['filter-query'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['rel-query', 'jsonpath-query'].includes(type));
+    return {
+      type: 'FilterQuery',
+      query: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['rel-query'](node, ctx) {
+    const segments = node.children.find(c => c.type === 'segments');
+    return {
+      type: 'RelQuery',
+      segments: segments ? segments.children.filter(n => n.type === 'segment').map(segNode => transformCSTtoAST(segNode, transformers, ctx)) : []
+    };
+  },
+  ['comparison-expr'](node, ctx) {
+    const children = node.children.filter(({
+      type
+    }) => ['comparable', 'comparison-op'].includes(type));
+    const [left, op, right] = children;
+    return {
+      type: 'ComparisonExpr',
+      left: transformCSTtoAST(left, transformers, ctx),
+      op: op.text,
+      right: transformCSTtoAST(right, transformers, ctx)
+    };
+  },
+  ['literal'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['number', 'string-literal', 'true', 'false', 'null'].includes(type));
+    if (child.type === 'string-literal') {
+      const stringLiteralASTNode = transformCSTtoAST(child, transformers, ctx);
+      return {
+        type: 'Literal',
+        value: stringLiteralASTNode.value
+      };
+    }
+    return {
+      type: 'Literal',
+      value: decodeJSONValue(child.text)
+    };
+  },
+  ['comparable'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['singular-query', 'function-expr', 'literal'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['singular-query'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['rel-singular-query', 'abs-singular-query'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['rel-singular-query'](node, ctx) {
+    const segmentsNode = node.children.find(({
+      type
+    }) => type === 'singular-query-segments');
+    const segments = segmentsNode ? segmentsNode.children.filter(({
+      type
+    }) => ['name-segment', 'index-segment'].includes(type)).map(segNode => ({
+      type: 'SingularQuerySegment',
+      selector: transformCSTtoAST(segNode, transformers, ctx)
+    })) : [];
+    return {
+      type: 'RelSingularQuery',
+      segments
+    };
+  },
+  ['abs-singular-query'](node, ctx) {
+    const segmentsNode = node.children.find(({
+      type
+    }) => type === 'singular-query-segments');
+    const segments = segmentsNode ? segmentsNode.children.filter(({
+      type
+    }) => ['name-segment', 'index-segment'].includes(type)).map(segNode => ({
+      type: 'SingularQuerySegment',
+      selector: transformCSTtoAST(segNode, transformers, ctx)
+    })) : [];
+    return {
+      type: 'AbsSingularQuery',
+      segments
+    };
+  },
+  ['name-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['name-selector', 'member-name-shorthand'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['index-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'index-selector');
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+   */
+  ['function-expr'](node, ctx) {
+    const name = node.children.find(({
+      type
+    }) => type === 'function-name');
+    const args = node.children.filter(({
+      type
+    }) => type === 'function-argument');
+    return {
+      type: 'FunctionExpr',
+      name: name.text,
+      arguments: args.map(arg => transformCSTtoAST(arg, transformers, ctx))
+    };
+  },
+  ['function-argument'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['logical-expr', 'function-expr', 'filter-query', 'literal'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.5.1.1
+   */
+  ['child-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['bracketed-selection', 'wildcard-selector', 'member-name-shorthand'].includes(type));
+    return {
+      type: 'ChildSegment',
+      selector: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['bracketed-selection'](node, ctx) {
+    return {
+      type: 'BracketedSelection',
+      selectors: node.children.filter(({
+        type
+      }) => type === 'selector').map(selectorNode => transformCSTtoAST(selectorNode, transformers, ctx))
+    };
+  },
+  ['member-name-shorthand'](node) {
+    return {
+      type: 'NameSelector',
+      value: node.text,
+      format: 'shorthand'
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#section-2.5.2.1
+   */
+  ['descendant-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['bracketed-selection', 'wildcard-selector', 'member-name-shorthand'].includes(type));
+    return {
+      type: 'DescendantSegment',
+      selector: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  /**
+   * https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
+   */
+  ['normalized-path'](node, ctx) {
+    return {
+      type: 'JsonPathQuery',
+      segments: node.children.filter(({
+        type
+      }) => type === 'normal-index-segment').map(segNode => transformCSTtoAST(segNode, transformers, ctx))
+    };
+  },
+  ['normal-index-segment'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => type === 'normal-selector');
+    return {
+      type: 'ChildSegment',
+      selector: transformCSTtoAST(child, transformers, ctx)
+    };
+  },
+  ['normal-selector'](node, ctx) {
+    const child = node.children.find(({
+      type
+    }) => ['normal-name-selector', 'normal-index-selector'].includes(type));
+    return transformCSTtoAST(child, transformers, ctx);
+  },
+  ['normal-name-selector'](node) {
+    const child = node.children.find(({
+      type
+    }) => type === 'normal-single-quoted');
+    return {
+      type: 'NameSelector',
+      value: child ? decodeString(child.text) : '',
+      format: 'single-quoted'
+    };
+  },
+  ['normal-index-selector'](node) {
+    return {
+      type: 'IndexSelector',
+      value: decodeInteger(node.text)
+    };
+  }
+};
+export default transformers;

package/es/parse/translators/CSTOptimizedTranslator.mjs

@@ -3,12 +3,16 @@ class CSTOptimizedTranslator extends CSTTranslator {
   collapsibleTypes = ['single-quoted', 'double-quoted', 'normal-single-quoted'];
   droppableTypes = ['text', 'segments', 'singular-query-segments'];
   constructor({
-    collapsibleTypes
+    collapsibleTypes,
+    droppableTypes
   } = {}) {
     super();
     if (Array.isArray(collapsibleTypes)) {
       this.collapsibleTypes = collapsibleTypes;
     }
+    if (Array.isArray(droppableTypes)) {
+      this.droppableTypes = droppableTypes;
+    }
   }
   getTree() {
     const options = {

package/package.json

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

package/types/index.d.ts

@@ -24,7 +24,7 @@ export declare class XMLTranslator implements Translator<XMLTree> {
   getTree(): XMLTree;
 }
 
-export interface ParseResult<TTree = unknown> {
+export interface ParseResult<TTree = ASTTree> {
   readonly result: {
     readonly success: boolean;
     readonly state: number;
@@ -54,6 +54,159 @@ export interface CSTTree {
 
 export type XMLTree = string;
 
+/* AST Tree start */
+export interface ASTTree {
+  readonly root: JSONPathQueryASTNode;
+}
+export interface ASTNode {
+  readonly type:
+    | 'JSONPathQuery'
+    | 'NameSelector'
+    | 'WildcardSelector'
+    | 'IndexSelector'
+    | 'SliceSelector'
+    | 'FilterSelector'
+    | 'LogicalOrExpr'
+    | 'LogicalAndExpr'
+    | 'LogicalNotExpr'
+    | 'TestExpr'
+    | 'FilterQuery'
+    | 'RelQuery'
+    | 'ComparisonExpr'
+    | 'Literal'
+    | 'RelSingularQuery'
+    | 'AbsSingularQuery'
+    | 'FunctionExpr'
+    | 'ChildSegment'
+    | 'DescendantSegment'
+    | 'BracketedSelection';
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.1.1
+export interface JSONPathQueryASTNode extends ASTNode {
+  readonly type: 'JSONPathQuery';
+  segments: SegmentASTNode[];
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.3.1.1
+export interface NameSelectorASTNode extends ASTNode {
+  type: 'NameSelector';
+  value: string;
+  format: 'single-quoted' | 'double-quoted' | 'shorthand';
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.3.2.1
+export interface WildcardSelectorASTNode extends ASTNode {
+  type: 'WildcardSelector';
+}
+// https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
+export interface IndexSelectorASTNode extends ASTNode {
+  type: 'IndexSelector';
+  value: number;
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.3.4.1
+export interface SliceSelectorASTNode extends ASTNode {
+  type: 'SliceSelector';
+  start: number | null;
+  end: number | null ;
+  step: number | null;
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.3.5.1
+export interface FilterSelectorASTNode extends ASTNode {
+  type: 'FilterSelector';
+  expression: LogicalExprASTNode;
+}
+export interface LogicalOrExprASTNode extends ASTNode {
+  type: 'LogicalOrExpr';
+  left: LogicalExprASTNode;
+  right: LogicalExprASTNode;
+}
+export interface LogicalAndExprASTNode extends ASTNode {
+  type: 'LogicalAndExpr';
+  left: LogicalExprASTNode;
+  right: LogicalExprASTNode;
+}
+export interface LogicalNotExprASTNode extends ASTNode {
+  type: 'LogicalNotExpr';
+  expression: LogicalExprASTNode;
+}
+export interface TestExprASTNode extends ASTNode {
+  type: 'TestExpr';
+  expression: FilterQueryASTNode | FunctionExprASTNode;
+}
+export interface FilterQueryASTNode extends ASTNode {
+  type: 'FilterQuery';
+  query: RelQueryASTNode | JSONPathQueryASTNode;
+}
+export interface RelQueryASTNode extends ASTNode {
+  type: 'RelQuery';
+  segments: SegmentASTNode[];
+}
+export interface ComparisonExprASTNode extends ASTNode {
+  type: 'ComparisonExpr';
+  left: ComparableASTNode;
+  operator: '==' | '!=' | '<=' | '>=' | '<' | '>';
+  right: ComparableASTNode;
+}
+export interface LiteralASTNode extends ASTNode {
+  type: 'Literal';
+  value: string | number | boolean | null;
+}
+export interface RelSingularQueryASTNode extends ASTNode {
+  type: 'RelSingularQuery';
+  segments: SingularQuerySegmentASTNode[];
+}
+export interface AbsSingularQueryASTNode extends ASTNode {
+  type: 'AbsSingularQuery';
+  segments: SingularQuerySegmentASTNode[];
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.4
+export interface FunctionExprASTNode extends ASTNode {
+  type: 'FunctionExpr';
+  name: string;
+  arguments: FunctionArgumentASTNode[];
+}
+// https://www.rfc-editor.org/rfc/rfc9535#section-2.5.1.1
+export interface ChildSegmentASTNode extends ASTNode {
+  type: 'ChildSegment';
+  selector: BracketedSelectionASTNode | WildcardSelectorASTNode | NameSelectorASTNode;
+}
+export interface BracketedSelectionASTNode extends ASTNode {
+  type: 'BracketedSelection';
+  selectors: SelectorASTNode[];
+}
+export interface DescendantSegmentASTNode extends ASTNode {
+  type: 'DescendantSegment';
+  selector: BracketedSelectionASTNode | WildcardSelectorASTNode | NameSelectorASTNode;
+}
+// union types
+export type SelectorASTNode =
+  | NameSelectorASTNode
+  | WildcardSelectorASTNode
+  | SliceSelectorASTNode
+  | IndexSelectorASTNode
+  | FilterQueryASTNode;
+export type LogicalExprASTNode =
+  | LogicalOrExprASTNode
+  | LogicalAndExprASTNode
+  | LogicalNotExprASTNode
+  | TestExprASTNode
+  | ComparisonExprASTNode;
+export type ComparableASTNode =
+  | RelSingularQueryASTNode
+  | AbsSingularQueryASTNode
+  | FunctionExprASTNode
+  | LiteralASTNode;
+export type SegmentASTNode =
+  | ChildSegmentASTNode
+  | DescendantSegmentASTNode;
+export type FunctionArgumentASTNode =
+  | LogicalExprASTNode
+  | FilterQueryASTNode
+  | FunctionExprASTNode
+  | LiteralASTNode;
+export type SingularQuerySegmentASTNode =
+  | NameSelectorASTNode
+  | IndexSelectorASTNode;
+/* AST Tree end */
+
 export interface Stats {
   displayStats(): string;
   displayHits(): string;