\n\n## Table of Contents\n\n- [Getting started](#getting-started)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Extraction](#extraction)\n - [Interpolation](#interpolation)\n - [Parsing](#parsing)\n - [Translators](#translators)\n - [Statistics](#statistics)\n - [Tracing](#tracing)\n - [Validation](#validation)\n - [Errors](#errors)\n - [Grammar](#grammar)\n- [More about Arazzo runtime expressions](#more-about-arazzo-runtime-expressions)\n- [License](#license)\n\n\n## Getting started\n\n### Installation\n\nYou can install `@swaggerexpert/arazzo-runtime-expression` using `npm`:\n\n```sh\n $ npm install @swaggerexpert/arazzo-runtime-expression\n```\n\n### Usage\n\n`@swaggerexpert/arazzo-runtime-expression` currently supports **extraction**, **interpolation**, **parsing** and **validation**.\nBoth parser and validator are based on a superset of [ABNF](https://www.rfc-editor.org/rfc/rfc5234) ([SABNF](https://cs.github.com/ldthomas/apg-js2/blob/master/SABNF.md))\nand use [apg-lite](https://github.com/ldthomas/apg-lite) parser generator.\n\n#### Extraction\n\nArazzo embeds Runtime Expressions into string values surrounded with `{}` curly braces.\nTo extract Runtime Expressions from this embedded form, use the **extract** function.\nThe function returns an array of all extracted expressions, which can be used for further parsing or validation.\n\n```js\nimport { extract, test, parse } from '@swaggerexpert/arazzo-runtime-expression';\n\n// Extract single expression\nextract('{$request.header.accept}'); // => ['$request.header.accept']\n\n// Extract multiple expressions from a template string\nextract('client_id={$inputs.clientId}&grant_type={$inputs.grantType}');\n// => ['$inputs.clientId', '$inputs.grantType']\n\n// No expressions found\nextract('no expressions here'); // => []\n\n// Use extracted expressions\nconst expressions = extract('{$url}');\ntest(expressions[0]); // => true\nparse(expressions[0]); // => { result, tree }\n```\n\n#### Interpolation\n\nArazzo embeds Runtime Expressions into string values surrounded with `{}` curly braces.\nTo render such a template string, use the **interpolate** function. It replaces every `{expression}`\noccurrence with a value produced by a **resolver** callback, while preserving all literal content.\n\nBecause this package is a parser and has no knowledge of the runtime context (HTTP messages, workflow\ninputs/outputs, etc.), you supply the resolution logic through the `resolver` callback. The callback\nreceives the raw expression (e.g. `$inputs.name`) and returns its value.\n\n```js\nimport { interpolate } from '@swaggerexpert/arazzo-runtime-expression';\n\n// Single expression\ninterpolate('Hello {$inputs.name}!', () => 'world'); // => 'Hello world!'\n\n// Multiple expressions resolved from a lookup table\nconst values = { '$inputs.clientId': 'abc', '$inputs.grantType': 'authorization_code' };\ninterpolate('client_id={$inputs.clientId}&grant_type={$inputs.grantType}', (expression) => values[expression]);\n// => 'client_id=abc&grant_type=authorization_code'\n\n// Strings without expressions are returned unchanged\ninterpolate('no expressions here', () => 'X'); // => 'no expressions here'\n```\n\nResolved values are stringified before being spliced into the template. The default stringification\nrenders `undefined` and `null` as an empty string, uses strings as-is, serializes objects with\n`JSON.stringify` and coerces everything else via `String()`. This can be customized via the\n`stringify` option.\n\n```js\nimport { interpolate } from '@swaggerexpert/arazzo-runtime-expression';\n\ninterpolate('{$request.body}', () => ({ id: 1 }), {\n stringify: (value) => JSON.stringify(value, null, 2),\n});\n// => '{\\n \"id\": 1\\n}'\n```\n\n#### Parsing\n\nParsing a Runtime Expression is as simple as importing the **parse** function and calling it.\n\n```js\nimport { parse } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst parseResult = parse('$request.header.accept');\n```\n\n**parseResult** variable has the following shape:\n\n```\n{\n result: ,\n tree: ,\n stats: ,\n trace: ,\n}\n```\n\n[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.\n\n##### Translators\n\n`@swaggerexpert/arazzo-runtime-expression` provides several translators to convert the parse result into different tree representations.\n\n###### CST translator\n\n[Concrete Syntax Tree](https://en.wikipedia.org/wiki/Parse_tree) (Parse tree) representation is available on parse result\nwhen instance of `CSTTranslator` is provided via a `translator` option to the `parse` function.\nCST is suitable to be consumed by other tools like IDEs, editors, etc...\n\n```js\nimport { parse, CSTTranslator } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { tree: cst } = parse('$request.header.accept', { translator: new CSTTranslator() });\n```\n\nCST tree has a shape documented by [TypeScript typings (CSTNode)](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/types/index.d.ts).\n\n###### AST translator\n\n**Default translator**. [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) representation is available on parse result\nby default or when instance of `ASTTranslator` is provided via a `translator` option to the `parse` function.\nAST is suitable to be consumed by implementations that need to analyze the structure of the runtime expression.\n\n```js\nimport { parse } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { tree: ast } = parse('$request.header.accept');\n```\n\nor\n\n```js\nimport { parse, ASTTranslator } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { tree: ast } = parse('$request.header.accept', { translator: new ASTTranslator() });\n```\n\nAST tree has a shape documented by [TypeScript typings (ASTNode)](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/types/index.d.ts).\n\n###### XML translator\n\n```js\nimport { parse, XMLTranslator } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { tree: xml } = parse('$request.header.accept', { translator: new XMLTranslator() });\n```\n\n##### Statistics\n\n`parse` function returns additional statistical information about the parsing process.\nCollection of the statistics can be enabled by setting `stats` option to `true`.\n\n```js\nimport { parse } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { stats } = parse('$request.header.accept', { stats: true });\n\nstats.displayStats(); // returns operator statistics as string\n```\n\n##### Tracing\n\n`parse` function returns additional tracing information about the parsing process.\nTracing can be enabled by setting `trace` option to `true`. Tracing is essential\nfor debugging failed parses or analyzing rule execution flow.\n\n```js\nimport { parse } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { result, trace } = parse('$invalid', { trace: true });\n\nresult.success; // false\ntrace.displayTrace(); // returns trace information as string\n```\n\nTracing also allows you to infer expected tokens at a failure point. This is useful for generating meaningful syntax error messages.\n\n```js\nimport { parse } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst { trace } = parse('$invalid', { trace: true });\n\nconst expectations = trace.inferExpectations();\nconsole.log(expectations.toString()); // e.g., \"expected '$url', '$method', '$statusCode', '$request.', ...\"\n```\n\n#### Validation\n\nValidating a Runtime Expression is as simple as importing the **test** function and calling it.\n\n```js\nimport { test } from '@swaggerexpert/arazzo-runtime-expression';\n\ntest('$request.header.accept'); // => true\ntest('nonsensical string'); // => false\n```\n\n#### Errors\n\n`@swaggerexpert/arazzo-runtime-expression` provides a structured error class hierarchy,\nenabling precise error handling across runtime expression operations.\n\n```js\nimport { ArazzoRuntimeExpressionError, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';\n```\n\n**ArazzoRuntimeExpressionError** is the base class for all errors. **ArazzoRuntimeExpressionParseError** is thrown when parsing fails\nand includes additional context about the expression that failed to parse.\n\n```js\nimport { parse, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';\n\ntry {\n parse(123); // non-string input\n} catch (error) {\n if (error instanceof ArazzoRuntimeExpressionParseError) {\n console.log(error.runtimeExpression); // the expression that failed\n }\n}\n```\n\n#### Grammar\n\nNew grammar instance can be created in following way:\n\n```js\nimport { Grammar } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst grammar = new Grammar();\n```\n\nTo obtain original ABNF (SABNF) grammar as a string:\n\n```js\nimport { Grammar } from '@swaggerexpert/arazzo-runtime-expression';\n\nconst grammar = new Grammar();\n\ngrammar.toString();\n// or\nString(grammar);\n```\n\n## More about Arazzo runtime expressions\n\nThe runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax\n\n```abnf\n; Arazzo runtime expression ABNF syntax\n; Rule order mirrors the Arazzo 1.1.0 specification (Runtime Expressions section).\n\n; Top-level expression\nexpression = (\n \"$url\" /\n \"$method\" /\n \"$statusCode\" /\n \"$request.\" source /\n \"$response.\" source /\n \"$message.\" source /\n \"$inputs.\" inputs-reference /\n \"$outputs.\" outputs-reference /\n \"$steps.\" steps-reference /\n \"$workflows.\" workflows-reference /\n \"$sourceDescriptions.\" source-reference /\n \"$components.\" components-reference /\n \"$self\"\n )\n\n; Request/Response/Message sources\nsource = ( header-reference / query-reference / path-reference / body-reference / payload-reference )\nheader-reference = \"header.\" token\nquery-reference = \"query.\" name\npath-reference = \"path.\" name\nbody-reference = \"body\" [\"#\" json-pointer ]\npayload-reference = \"payload\" [\"#\" json-pointer ]\n\n; Input/Output references\ninputs-reference = input-name [ \"#\" json-pointer ]\noutputs-reference = output-name [ \"#\" json-pointer ]\ninput-name = identifier\noutput-name = identifier\n\n; Steps expressions\nsteps-reference = step-id \".outputs.\" output-name [ \"#\" json-pointer ]\nstep-id = identifier-strict\n\n; Workflows expressions\nworkflows-reference = workflow-id \".\" ( workflows-value-reference / workflows-steps-reference )\nworkflows-value-reference = workflow-field \".\" workflow-field-name [ \"#\" json-pointer ]\nworkflows-steps-reference = \"steps\" \".\" step-id\nworkflow-id = identifier-strict\nworkflow-field = \"inputs\" / \"outputs\"\nworkflow-field-name = identifier\n\n; Source descriptions expressions\nsource-reference = source-name \".\" source-reference-id\nsource-name = identifier-strict\nsource-reference-id = 1*CHAR\n ; operationIds have no character restrictions in OpenAPI/AsyncAPI\n\n; Components expressions\ncomponents-reference = component-type \".\" component-name\ncomponent-type = \"parameters\" / \"successActions\" / \"failureActions\"\ncomponent-name = identifier\n\n; Identifier rules\nidentifier-strict = 1*( ALPHA / DIGIT / \"-\" / \"_\" )\n ; Alphanumeric with hyphens, underscores (no dots)\nidentifier = 1*( ALPHA / DIGIT / \".\" / \"-\" / \"_\" )\n ; Alphanumeric with dots, hyphens, underscores\n\n; Unconstrained name rule for query/path references\nname = *( CHAR )\n\n; JSON Pointer (RFC 6901, adapted)\n; { (%x7B) and } (%x7D) are excluded from 'unescaped' for unambiguous embedded expression parsing\njson-pointer = *( \"/\" reference-token )\nreference-token = *( unescaped / escaped )\nunescaped = %x00-2E / %x30-7A / %x7C / %x7F-10FFFF\n ; %x2F ('/'), %x7E ('~'), %x7B ('{'), %x7D ('}') are excluded\nescaped = \"~\" ( \"0\" / \"1\" )\n ; representing '~' and '/', respectively\n\n; https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6\ntoken = 1*tchar\ntchar = \"!\" / \"#\" / \"$\" / \"%\" / \"&\" / \"'\" / \"*\"\n / \"+\" / \"-\" / \".\" / \"^\" / \"_\" / \"`\" / \"|\" / \"~\"\n / DIGIT / ALPHA\n ; any VCHAR, except delimiters\n\n; https://www.rfc-editor.org/rfc/rfc7159#section-7\nCHAR = unescape /\n escape (\n %x22 / ; \" quotation mark U+0022\n %x5C / ; \\ reverse solidus U+005C\n %x2F / ; / solidus U+002F\n %x62 / ; b backspace U+0008\n %x66 / ; f form feed U+000C\n %x6E / ; n line feed U+000A\n %x72 / ; r carriage return U+000D\n %x74 / ; t tab U+0009\n %x75 4HEXDIG ) ; uXXXX U+XXXX\nescape = %x5C ; \\\nunescape = %x20-21 / %x23-5B / %x5D-7A / %x7C / %x7E-10FFFF\n ; %x7B ('{') and %x7D ('}') are excluded from 'unescape'\n\n; Grammar for parsing template strings with embedded expressions\nexpression-string = *( literal-char / embedded-expression )\nembedded-expression = \"{\" expression \"}\"\nliteral-char = %x00-7A / %x7C / %x7E-10FFFF ; anything except { (%x7B) and } (%x7D)\n\n; https://datatracker.ietf.org/doc/html/rfc5234#appendix-B.1\nALPHA = %x41-5A / %x61-7A ; A-Z / a-z\nDIGIT = %x30-39 ; 0-9\nHEXDIG = DIGIT / \"A\" / \"B\" / \"C\" / \"D\" / \"E\" / \"F\"\n```\n\nThe `name` identifier is case-sensitive, whereas `token` is not.\n\nThe table below provides examples of runtime expressions and examples of their use in a value:\n\n#### Examples\n\nSource Location | example expression | notes\n---|:---|:---|\nHTTP Method | `$method` | The allowable values for the `$method` will be those for the HTTP operation.\nRequested media type | `$request.header.accept` |\nRequest parameter | `$request.path.id` | Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers.\nRequest body property | `$request.body#/user/uuid` | In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body.\nRequest URL | `$url` |\nResponse value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body.\nResponse header | `$response.header.Server` | Single header values only are available.\nMessage payload value | `$message.payload#/user/id` | For event-driven (AsyncAPI) operations, references may be made to portions of the message payload or the entire payload.\nSelf URI | `$self` | References the canonical URI of the current Arazzo Description.\nWorkflow input | `$inputs.username` | Single input values only are available.\nWorkflow input property | `$inputs.customer#/firstName` | To access nested properties within an input object, use JSON Pointer syntax.\nStep output value | `$steps.someStepId.outputs.pets` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$steps.someStepId.outputs.pets#/0/id`) or the entire body.\nWorkflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$workflows.foo.outputs.mappedResponse#/name`) or the entire body.\nStep dependency (`dependsOn`) | `$workflows.foo.steps.bar` | References a step (`bar`) defined in a different workflow (`foo`) within the current Arazzo Document.\nSource description reference | `$sourceDescriptions.petstore.getPetById` | References an operationId or workflowId from the named source description.\nComponents parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object.\nComponents action | `$components.successActions.bar` | Accesses a success or failure action defined within the Components Object.\n\nRuntime expressions preserve the type of the referenced value.\nExpressions can be embedded into string values by surrounding the expression with `{}` curly braces.\n\n## License\n\n`@swaggerexpert/arazzo-runtime-expression` is licensed under [Apache 2.0 license](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/LICENSE).\n`@swaggerexpert/arazzo-runtime-expression` comes with an explicit [NOTICE](https://github.com/swaggerexpert/arazzo-runtime-expression/blob/main/NOTICE) file\ncontaining additional legal notices and information.\n","readmeFilename":"README.md"}
![\"Tidelift\"](\"https://raw.githubusercontent.com/swaggerexpert/arazzo-runtime-expression/main/assets/tidelift.webp\")
\n