@swaggerexpert/jsonpath 3.2.2 → 3.2.4

package/es/index.mjs

@@ -0,0 +1,13 @@
+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 Trace } from "./parse/trace/Trace.mjs";
+export { default as test } from "./test/index.mjs";
+export { default as compile } from "./compile.mjs";
+export { default as escape } from "./escape.mjs";
+export { default as JSONPathError } from "./errors/JSONPathError.mjs";
+export { default as JSONPathParseError } from "./errors/JSONPathParseError.mjs";
+export { default as JSONPathCompileError } from "./errors/JSONPathCompileError.mjs";

package/es/parse/callbacks/cst.mjs

@@ -0,0 +1,44 @@
+import { utilities, identifiers } from 'apg-lite';
+import JSONPathParseError from "../../errors/JSONPathParseError.mjs";
+const cst = nodeType => {
+  return (state, chars, phraseIndex, phraseLength, data) => {
+    var _data$options, _data$options2;
+    if (!(typeof data === 'object' && data !== null && !Array.isArray(data))) {
+      throw new JSONPathParseError("parser's user data must be an object");
+    }
+
+    // drop the empty nodes
+    if ((_data$options = data.options) !== null && _data$options !== void 0 && _data$options.optimize && phraseLength === 0 && (_data$options2 = data.options) !== null && _data$options2 !== void 0 && (_data$options2 = _data$options2.droppableTypes) !== null && _data$options2 !== void 0 && _data$options2.includes(nodeType)) {
+      return;
+    }
+    if (state === identifiers.SEM_PRE) {
+      const node = {
+        type: nodeType,
+        text: utilities.charsToString(chars, phraseIndex, phraseLength),
+        start: phraseIndex,
+        length: phraseLength,
+        children: []
+      };
+      if (data.stack.length > 0) {
+        var _data$options3, _data$options4;
+        const parent = data.stack[data.stack.length - 1];
+        const prevSibling = parent.children[parent.children.length - 1];
+        const isTextNodeWithinTextNode = parent.type === 'text' && node.type === 'text';
+        const shouldCollapse = ((_data$options3 = data.options) === null || _data$options3 === void 0 ? void 0 : _data$options3.optimize) && ((_data$options4 = data.options) === null || _data$options4 === void 0 || (_data$options4 = _data$options4.collapsibleTypes) === null || _data$options4 === void 0 ? void 0 : _data$options4.includes(node.type)) && (prevSibling === null || prevSibling === void 0 ? void 0 : prevSibling.type) === node.type;
+        if (shouldCollapse) {
+          prevSibling.text += node.text;
+          prevSibling.length += node.length;
+        } else if (!isTextNodeWithinTextNode) {
+          parent.children.push(node);
+        }
+      } else {
+        data.root = node;
+      }
+      data.stack.push(node);
+    }
+    if (state === identifiers.SEM_POST) {
+      data.stack.pop();
+    }
+  };
+};
+export default cst;

package/es/parse/index.mjs

@@ -0,0 +1,36 @@
+import { Parser, Stats } from 'apg-lite';
+import Trace from "./trace/Trace.mjs";
+import Grammar from "../grammar.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 ASTTranslator()
+} = {}) => {
+  if (typeof jsonPath !== 'string') {
+    throw new TypeError('JSONPath must be a string');
+  }
+  try {
+    const parser = new Parser();
+    if (translator) parser.ast = translator;
+    if (stats) parser.stats = new Stats();
+    if (trace) parser.trace = new Trace();
+    const startRule = normalized ? 'normalized-path' : 'jsonpath-query';
+    const result = parser.parse(grammar, startRule, jsonPath);
+    return {
+      result,
+      tree: result.success && translator ? parser.ast.getTree() : undefined,
+      stats: parser.stats,
+      trace: parser.trace
+    };
+  } catch (error) {
+    throw new JSONPathParseError('Unexpected error during JSONPath parsing', {
+      cause: error,
+      jsonPath
+    });
+  }
+};
+export default parse;

package/es/parse/trace/Expectations.mjs

@@ -0,0 +1,6 @@
+class Expectations extends Array {
+  toString() {
+    return this.map(c => `"${String(c)}"`).join(', ');
+  }
+}
+export default Expectations;

package/es/parse/trace/Trace.mjs

@@ -0,0 +1,30 @@
+import { Trace as BaseTrace } from 'apg-lite';
+import Expectations from "./Expectations.mjs";
+class Trace extends BaseTrace {
+  inferExpectations() {
+    const lines = this.displayTrace().split('\n');
+    const expectations = new Set();
+    let lastMatchedIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // capture the max match line (first one that ends in a single character match)
+      if (line.includes('M|')) {
+        const textMatch = line.match(/]'(.*)'$/);
+        if (textMatch && textMatch[1]) {
+          lastMatchedIndex = i;
+        }
+      }
+
+      // collect terminal failures after the deepest successful match
+      if (i > lastMatchedIndex) {
+        const terminalFailMatch = line.match(/N\|\[TLS\(([^)]+)\)]/);
+        if (terminalFailMatch) {
+          expectations.add(terminalFailMatch[1]);
+        }
+      }
+    }
+    return new Expectations(...expectations);
+  }
+}
+export default Trace;

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

@@ -0,0 +1,75 @@
+export const decodeDoubleQuotedString = str => {
+  return decodeJSONValue(`"${str}"`);
+};
+export const decodeSingleQuotedString = str => {
+  // Decode single-quoted string escape sequences into raw text, then let JSON.stringify
+  // produce a correctly escaped double-quoted JSON string.
+  let decoded = '';
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === '\\') {
+      i++;
+      if (i >= str.length) {
+        // Trailing backslash, treat it as a literal backslash
+        decoded += '\\';
+        break;
+      }
+      const esc = str[i];
+      switch (esc) {
+        case 'n':
+          decoded += '\n';
+          break;
+        case 'r':
+          decoded += '\r';
+          break;
+        case 't':
+          decoded += '\t';
+          break;
+        case 'b':
+          decoded += '\b';
+          break;
+        case 'f':
+          decoded += '\f';
+          break;
+        case '/':
+          decoded += '/';
+          break;
+        case '\\':
+          decoded += '\\';
+          break;
+        case "'":
+          decoded += "'";
+          break;
+        case '"':
+          decoded += '"';
+          break;
+        case 'u':
+          {
+            // Unicode escape \uXXXX - grammar guarantees exactly 4 hex digits
+            const hex = str.slice(i + 1, i + 5);
+            decoded += String.fromCharCode(parseInt(hex, 16));
+            i += 4;
+            break;
+          }
+        default:
+          // Unrecognized escape, keep the escaped character literally
+          decoded += esc;
+          break;
+      }
+    } else {
+      decoded += ch;
+    }
+  }
+  // Use JSON.stringify to produce a valid JSON string literal
+  return decodeJSONValue(JSON.stringify(decoded));
+};
+export const decodeInteger = str => {
+  const value = parseInt(str, 10);
+  if (!Number.isSafeInteger(value)) {
+    throw new RangeError(`Integer value out of safe range [-(2^53)+1, (2^53)-1], got: ${str}`);
+  }
+  return value;
+};
+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,405 @@
+import JSONPathParseError from "../../../errors/JSONPathParseError.mjs";
+import { decodeSingleQuotedString, decodeDoubleQuotedString, 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));
+    const decodeString = isSingleQuoted ? decodeSingleQuotedString : decodeDoubleQuotedString;
+    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 ? decodeSingleQuotedString(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

@@ -0,0 +1,34 @@
+import CSTTranslator from "./CSTTranslator.mjs";
+class CSTOptimizedTranslator extends CSTTranslator {
+  collapsibleTypes = ['single-quoted', 'double-quoted', 'normal-single-quoted'];
+  droppableTypes = ['text', 'segments', 'singular-query-segments'];
+  constructor({
+    collapsibleTypes,
+    droppableTypes
+  } = {}) {
+    super();
+    if (Array.isArray(collapsibleTypes)) {
+      this.collapsibleTypes = collapsibleTypes;
+    }
+    if (Array.isArray(droppableTypes)) {
+      this.droppableTypes = droppableTypes;
+    }
+  }
+  getTree() {
+    const options = {
+      optimize: true,
+      collapsibleTypes: this.collapsibleTypes,
+      droppableTypes: this.droppableTypes
+    };
+    const data = {
+      stack: [],
+      root: null,
+      options
+    };
+    this.translate(data);
+    delete data.stack;
+    delete data.options;
+    return data;
+  }
+}
+export default CSTOptimizedTranslator;