@swaggerexpert/arazzo-runtime-expression 1.0.1 → 2.0.2

package/README.md

@@ -20,7 +20,7 @@ It supports Runtime Expressions defined in following Arazzo specification versio
 <table>
   <tr>
     <td align="right" valign="middle">
-        <img src="https://cdn2.hubspot.net/hubfs/4008838/website/logos/logos_for_download/Tidelift_primary-shorthand-logo.png" alt="Tidelift" width="60" />
+        <img src="https://raw.githubusercontent.com/swaggerexpert/arazzo-runtime-expression/main/assets/tidelift.webp" alt="Tidelift" width="60" />
       </td>
       <td valign="middle">
         <a href="https://tidelift.com/subscription/pkg/npm-.swaggerexpert-arazzo-runtime-expression?utm_source=npm-swaggerexpert-arazzo-runtime-expression&utm_medium=referral&utm_campaign=readme">
@@ -37,7 +37,11 @@ It supports Runtime Expressions defined in following Arazzo specification versio
   - [Usage](#usage)
     - [Extraction](#extraction)
     - [Parsing](#parsing)
+      - [Translators](#translators)
+      - [Statistics](#statistics)
+      - [Tracing](#tracing)
     - [Validation](#validation)
+    - [Errors](#errors)
     - [Grammar](#grammar)
 - [More about Arazzo runtime expressions](#more-about-arazzo-runtime-expressions)
 - [License](#license)
@@ -63,17 +67,32 @@ and use [apg-lite](https://github.com/ldthomas/apg-lite) parser generator.
 
 Arazzo embeds Runtime Expressions into string values surrounded with `{}` curly braces.
 To extract Runtime Expressions from this embedded form, use the **extract** function.
-Extracted Runtime Expression can be used for further parsing of validation.
+The function returns an array of all extracted expressions, which can be used for further parsing or validation.
 
 ```js
 import { extract, test, parse } from '@swaggerexpert/arazzo-runtime-expression';
 
-const expression = extract('{$request.header.accept}'); // => '$request.header.accept'
+// Extract single expression
+extract('{$request.header.accept}'); // => ['$request.header.accept']
 
-test(expression); // => true
-parse(expression); // => { result, ast }
+// Extract multiple expressions from a template string
+extract('client_id={$inputs.clientId}&grant_type={$inputs.grantType}');
+// => ['$inputs.clientId', '$inputs.grantType']
+
+// No expressions found
+extract('no expressions here'); // => []
+
+// Use extracted expressions
+const expressions = extract('{$url}');
+test(expressions[0]); // => true
+parse(expressions[0]); // => { result, tree }
 ```
 
+**Known limitation:** `$request.body#/...` and `$response.body#/...` expressions with JSON pointers cannot be reliably
+extracted from `{expression}` syntax. This is because [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
+(JSON Pointer) allows the `}` character in pointer paths, making it impossible to determine where the expression ends.
+Use `parse()` directly on the raw expression for these cases.
+
 #### Parsing
 
 Parsing a Runtime Expression is as simple as importing the **parse** function and calling it.
@@ -88,97 +107,101 @@ const parseResult = parse('$request.header.accept');
 
 ```
 {
-  result: {
-    success: true,
-    state: 101,
-    stateName: 'MATCH',
-    length: 22,
-    matched: 22,
-    maxMatched: 22,
-    maxTreeDepth: 13,
-    nodeHits: 152
-  },
-  ast: fnast {
-    callbacks: [
-      expression: [Function: expression],
-      'parameter-name': [Function: parameterName],
-      source: [Function: source],
-      'header-reference': [Function: headerReference],
-      'query-reference': [Function: queryReference],
-      'path-reference': [Function: pathReference],
-      'body-reference': [Function: bodyReference],
-      'json-pointer': [Function: jsonPointer],
-      'reference-token': [Function: referenceToken],
-      name: [Function: name],
-      token: [Function: token]
-    ],
-    init: [Function (anonymous)],
-    ruleDefined: [Function (anonymous)],
-    udtDefined: [Function (anonymous)],
-    down: [Function (anonymous)],
-    up: [Function (anonymous)],
-    translate: [Function (anonymous)],
-    setLength: [Function (anonymous)],
-    getLength: [Function (anonymous)],
-    toXml: [Function (anonymous)]
-  }
+  result: <ParseResult['result']>,
+  tree: <ParseResult['tree']>,
+  stats: <ParseResult['stats']>,
+  trace: <ParseResult['trace']>,
 }
 ```
 
-###### Interpreting AST as list of entries
+[TypeScript typings](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/types/index.d.ts) are available for all fields attached to parse result object returned by the `parse` function.
+
+##### Translators
+
+`@swaggerexpert/arazzo-runtime-expression` 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
+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, CSTTranslator } from '@swaggerexpert/arazzo-runtime-expression';
+
+const { tree: cst } = parse('$request.header.accept', { translator: new CSTTranslator() });
+```
+
+CST tree has a shape documented by [TypeScript typings (CSTNode)](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/types/index.d.ts).
+
+###### 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 runtime expression.
 
 ```js
 import { parse } from '@swaggerexpert/arazzo-runtime-expression';
 
-const parseResult = parse('$request.header.accept');
-const parts = [];
+const { tree: ast } = parse('$request.header.accept');
+```
+
+or
+
+```js
+import { parse, ASTTranslator } from '@swaggerexpert/arazzo-runtime-expression';
 
-parseResult.ast.translate(parts);
+const { tree: ast } = parse('$request.header.accept', { translator: new ASTTranslator() });
 ```
 
-After running the above code, **parts** variable has the following shape:
+AST tree has a shape documented by [TypeScript typings (ASTNode)](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/types/index.d.ts).
+
+###### XML translator
 
 ```js
-[
-  [ 'expression', '$request.header.accept' ],
-  [ 'source', 'header.accept' ],
-  [ 'header-reference', 'header.accept' ],
-  [ 'token', 'accept' ],
-]
+import { parse, XMLTranslator } from '@swaggerexpert/arazzo-runtime-expression';
+
+const { tree: xml } = parse('$request.header.accept', { translator: new XMLTranslator() });
 ```
 
-###### Interpreting AST as XML
+##### 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/arazzo-runtime-expression';
 
-const parseResult = parse('$request.header.accept');
-const xml = parseResult.ast.toXml();
+const { stats } = parse('$request.header.accept', { stats: true });
+
+stats.displayStats(); // returns operator statistics as string
 ```
 
-After running the above code, **xml** variable has the following content:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<root nodes="4" characters="22">
-  <!-- input string -->
-  $request.header.accept
-  <node name="expression" index="0" length="22">
-    $request.header.accept
-    <node name="source" index="9" length="13">
-      header.accept
-      <node name="header-reference" index="9" length="13">
-        header.accept
-        <node name="token" index="16" length="6">
-          accept
-        </node><!-- name="token" -->
-      </node><!-- name="header-reference" -->
-    </node><!-- name="source" -->
-  </node><!-- name="expression" -->
-</root>
+##### 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 parses or analyzing rule execution flow.
+
+```js
+import { parse } from '@swaggerexpert/arazzo-runtime-expression';
+
+const { result, trace } = parse('$invalid', { trace: true });
+
+result.success; // false
+trace.displayTrace(); // returns trace information as string
 ```
 
-> NOTE: AST can also be traversed in classical way using [depth first traversal](https://www.tutorialspoint.com/data_structures_algorithms/depth_first_traversal.htm). For more information about this option please refer to [apg-js](https://github.com/ldthomas/apg-js) and [apg-js-examples](https://github.com/ldthomas/apg-js-examples).
+Tracing also allows you to infer expected tokens at a failure point. This is useful for generating meaningful syntax error messages.
+
+```js
+import { parse } from '@swaggerexpert/arazzo-runtime-expression';
+
+const { trace } = parse('$invalid', { trace: true });
+
+const expectations = trace.inferExpectations();
+console.log(expectations.toString()); // e.g., "expected '$url', '$method', '$statusCode', '$request.', ..."
+```
 
 #### Validation
 
@@ -191,6 +214,30 @@ test('$request.header.accept'); // => true
 test('nonsensical string'); // => false
 ```
 
+#### Errors
+
+`@swaggerexpert/arazzo-runtime-expression` provides a structured error class hierarchy,
+enabling precise error handling across runtime expression operations.
+
+```js
+import { ArazzoRuntimeExpressionError, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';
+```
+
+**ArazzoRuntimeExpressionError** is the base class for all errors. **ArazzoRuntimeExpressionParseError** is thrown when parsing fails
+and includes additional context about the expression that failed to parse.
+
+```js
+import { parse, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';
+
+try {
+  parse(123); // non-string input
+} catch (error) {
+  if (error instanceof ArazzoRuntimeExpressionParseError) {
+    console.log(error.runtimeExpression); // the expression that failed
+  }
+}
+```
+
 #### Grammar
 
 New grammar instance can be created in following way:
@@ -219,8 +266,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org
 
 ```abnf
 ; Arazzo runtime expression ABNF syntax
-expression       = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name)
-parameter-name   = name ; Reuses 'name' rule for parameter names
+expression       = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name )
 source           = ( header-reference / query-reference / path-reference / body-reference )
 header-reference = "header." token
 query-reference  = "query." name
@@ -228,6 +274,39 @@ path-reference   = "path." name
 body-reference   = "body" ["#" json-pointer ]
 name             = *( CHAR )
 
+; Grammar for parsing template strings with embedded expressions
+expression-string    = *( literal-char / embedded-expression )
+embedded-expression  = "{" expression "}"
+literal-char         = %x00-7A / %x7C / %x7E-10FFFF  ; anything except { (%x7B) and } (%x7D)
+
+; Secondary grammar for parsing $steps name part
+; Format: {stepId}.{field}.{subField}[#/{jsonPointer}]
+steps-name       = steps-id "." steps-field "." steps-sub-field ["#" json-pointer]
+steps-id         = 1*(ALPHA / DIGIT / "_" / "-")
+steps-field      = "outputs"
+steps-sub-field  = 1*(ALPHA / DIGIT / "." / "-" / "_")
+
+; Secondary grammar for parsing $workflows name part
+; Format: {workflowId}.{field}.{subField}[#/{jsonPointer}]
+workflows-name       = workflows-id "." workflows-field "." workflows-sub-field ["#" json-pointer]
+workflows-id         = 1*(ALPHA / DIGIT / "_" / "-")
+workflows-field      = "inputs" / "outputs"
+workflows-sub-field  = 1*(ALPHA / DIGIT / "." / "-" / "_")
+
+; Secondary grammar for parsing $sourceDescriptions name part
+; Format: {sourceName}.{reference}
+; reference can be operationId (unconstrained) or workflowId (constrained)
+source-descriptions-name        = source-descriptions-source-name "." source-descriptions-reference
+source-descriptions-source-name = 1*(ALPHA / DIGIT / "_" / "-")
+source-descriptions-reference   = 1*CHAR
+
+; Secondary grammar for parsing $components name part
+; Format: {field}.{subField}
+; Allowed fields: parameters, successActions, failureActions
+components-name      = components-field "." components-sub-field
+components-field     = "parameters" / "successActions" / "failureActions"
+components-sub-field = 1*(ALPHA / DIGIT / "." / "-" / "_")
+
 ; https://datatracker.ietf.org/doc/html/rfc6901#section-3
 json-pointer     = *( "/" reference-token )
 reference-token  = *( unescaped / escaped )
@@ -256,7 +335,8 @@ CHAR = unescape /
         %x74 /          ; t    tab             U+0009
         %x75 4HEXDIG )  ; uXXXX                U+XXXX
 escape         = %x5C   ; \
-unescape       = %x20-21 / %x23-5B / %x5D-10FFFF
+unescape       = %x20-21 / %x23-5B / %x5D-7A / %x7C / %x7E-10FFFF
+               ; %x7B ('{') and %x7D ('}') are excluded from 'unescape'
 
 ; https://datatracker.ietf.org/doc/html/rfc5234#appendix-B.1
 HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"

package/SECURITY.md

@@ -6,7 +6,8 @@ If you believe you've found an exploitable security issue in @swaggerexpert/araz
 
 | Version | Supported          |
 |---------|--------------------|
-| ^1.0.0  | :white_check_mark: |
+| ^1.0.0  | :x:                |
+| ^2.0.0  | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

package/cjs/apg-lite.cjs

@@ -2,31 +2,31 @@
 
 exports.__esModule = true;
 exports.utilities = exports.identifiers = exports.Trace = exports.Stats = exports.Parser = exports.Ast = void 0;
-/*  *************************************************************************************
- *   copyright: Copyright (c) 2023 Lowell D. Thomas, all rights reserved
- *     license: BSD-2-Clause (https://opensource.org/licenses/BSD-2-Clause)
- *
- *    Redistribution and use in source and binary forms, with or without
- *    modification, are permitted provided that the following conditions are met:
- *
- *    1. Redistributions of source code must retain the above copyright notice, this
- *       list of conditions and the following disclaimer.
- *
- *    2. Redistributions in binary form must reproduce the above copyright notice,
- *       this list of conditions and the following disclaimer in the documentation
- *       and/or other materials provided with the distribution.
- *
- *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
- *    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
- *    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- *    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
- *    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
- *    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
- *    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- *    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
+/*  *************************************************************************************
+ *   copyright: Copyright (c) 2023 Lowell D. Thomas, all rights reserved
+ *     license: BSD-2-Clause (https://opensource.org/licenses/BSD-2-Clause)
+ *
+ *    Redistribution and use in source and binary forms, with or without
+ *    modification, are permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this
+ *       list of conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice,
+ *       this list of conditions and the following disclaimer in the documentation
+ *       and/or other materials provided with the distribution.
+ *
+ *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ *    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ *    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ *    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ *    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ *    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ *    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ *    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
  *   ********************************************************************************* */
 
 const Parser = exports.Parser = function fnparser() {
@@ -665,7 +665,7 @@ const Ast = exports.Ast = function fnast() {
   a.ruleDefined = index => !!nodeCallbacks[index];
   /* AST node UDT callbacks - called by the parser's `UDT` operator */
   a.udtDefined = index => !!nodeCallbacks[rules.length + index];
-  /* called by the parser's `RNM` & `UDT` operators
+  /* called by the parser's `RNM` & `UDT` operators
      builds a record for the downward traversal of the node */
   a.down = (callbackIndex, name) => {
     const thisIndex = records.length;
@@ -963,8 +963,8 @@ const Stats = exports.Stats = function fnstats() {
     out += displayRow('TOTAL', totals.match, totals.empty, totals.nomatch, totals.total);
     return out;
   };
-  /*
-  Display rule/udt
+  /*
+  Display rule/udt
   */
   this.displayHits = type => {
     let out = '';

package/cjs/errors/ArazzoRuntimeExpressionError.cjs

@@ -0,0 +1,44 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class ArazzoRuntimeExpressionError extends Error {
+  constructor(message, options = undefined) {
+    super(message, options);
+    this.name = this.constructor.name;
+    if (typeof message === 'string') {
+      this.message = message;
+    }
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, this.constructor);
+    } else {
+      this.stack = new Error(message).stack;
+    }
+
+    /**
+     * This needs to stay here until our minimum supported version of Node.js is >= 16.9.0.
+     * Node.js is >= 16.9.0 supports error causes natively.
+     */
+    if (options != null && typeof options === 'object' && Object.hasOwn(options, 'cause') && !('cause' in this)) {
+      const {
+        cause
+      } = options;
+      this.cause = cause;
+      if (cause instanceof Error && 'stack' in cause) {
+        this.stack = `${this.stack}\nCAUSE: ${cause.stack}`;
+      }
+    }
+
+    /**
+     * Allows to assign arbitrary properties to the error object.
+     */
+    if (options != null && typeof options === 'object') {
+      const {
+        cause,
+        ...causelessOptions
+      } = options;
+      Object.assign(this, causelessOptions);
+    }
+  }
+}
+var _default = exports.default = ArazzoRuntimeExpressionError;

package/cjs/errors/ArazzoRuntimeExpressionParseError.cjs

@@ -0,0 +1,8 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _ArazzoRuntimeExpressionError = _interopRequireDefault(require("./ArazzoRuntimeExpressionError.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+class ArazzoRuntimeExpressionParseError extends _ArazzoRuntimeExpressionError.default {}
+var _default = exports.default = ArazzoRuntimeExpressionParseError;

package/cjs/extract.cjs

@@ -2,20 +2,46 @@
 
 exports.__esModule = true;
 exports.default = void 0;
+var _apgLite = require("apg-lite.cjs");
+var _grammar = _interopRequireDefault(require("./grammar.cjs"));
+var _CSTTranslator = _interopRequireDefault(require("./parse/translators/CSTTranslator.cjs"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const grammar = new _grammar.default();
+
 /**
- * This function is used for extracting the expression from Arazzo Runtime Expression notation.
+ * Extract runtime expressions from a string containing embedded {expression} patterns.
  *
  * @example
  *
- * extract('{$url}'); // => '$url'
+ * extract('{$url}'); // => ['$url']
+ * extract('id={$inputs.id}&name={$inputs.name}'); // => ['$inputs.id', '$inputs.name']
  */
-
-const extract = arazzoRuntimeExpression => {
-  var _match$groups$express, _match$groups;
-  if (typeof arazzoRuntimeExpression !== 'string') {
-    return null;
+const extract = str => {
+  if (typeof str !== 'string') {
+    return [];
   }
-  const match = arazzoRuntimeExpression.match(/^{(?<expression>.+)}$/);
-  return (_match$groups$express = match == null || (_match$groups = match.groups) == null ? void 0 : _match$groups.expression) != null ? _match$groups$express : null;
+  const parser = new _apgLite.Parser();
+  parser.ast = new _CSTTranslator.default();
+  const result = parser.parse(grammar, 'expression-string', str);
+  if (!result.success) {
+    return [];
+  }
+  const cst = parser.ast.getTree();
+  const expressions = [];
+
+  // Traverse CST to find all embedded-expression nodes
+  const traverse = node => {
+    if (node.type === 'embedded-expression') {
+      const exprNode = node.children.find(c => c.type === 'expression');
+      if (exprNode) {
+        expressions.push(exprNode.text);
+      }
+    }
+    for (const child of node.children || []) {
+      traverse(child);
+    }
+  };
+  traverse(cst);
+  return expressions;
 };
 var _default = exports.default = extract;