{"id":23906820,"url":"https://github.com/swaggerexpert/asyncapi-runtime-expression","last_synced_at":"2026-06-14T18:35:29.927Z","repository":{"id":64074860,"uuid":"572237369","full_name":"swaggerexpert/asyncapi-runtime-expression","owner":"swaggerexpert","description":"AsyncAPI Runtime Expressions parser and validator.","archived":false,"fork":false,"pushed_at":"2025-02-14T17:24:47.000Z","size":703,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-22T06:53:43.203Z","etag":null,"topics":["asyncapi","expression","parser","runtime","validator"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swaggerexpert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["char0n"],"patreon":"char0n","ko_fi":"char0n","liberapay":"char0n","issuehunt":"char0n"}},"created_at":"2022-11-29T20:59:22.000Z","updated_at":"2025-02-14T17:24:50.000Z","dependencies_parsed_at":"2023-11-10T19:23:23.338Z","dependency_job_id":"ed15fe3e-fd14-4973-a465-b17c74c6c8bd","html_url":"https://github.com/swaggerexpert/asyncapi-runtime-expression","commit_stats":{"total_commits":70,"total_committers":2,"mean_commits":35.0,"dds":0.0714285714285714,"last_synced_commit":"744c54462f6d019e7e64e24feb133d11a81f3ed8"},"previous_names":["swaggerexpert/asyncapi-runtime-expression"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerexpert%2Fasyncapi-runtime-expression","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerexpert%2Fasyncapi-runtime-expression/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerexpert%2Fasyncapi-runtime-expression/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggerexpert%2Fasyncapi-runtime-expression/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swaggerexpert","download_url":"https://codeload.github.com/swaggerexpert/asyncapi-runtime-expression/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240324069,"owners_count":19783455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncapi","expression","parser","runtime","validator"],"created_at":"2025-01-05T02:14:49.429Z","updated_at":"2026-06-14T18:35:24.902Z","avatar_url":"https://github.com/swaggerexpert.png","language":"JavaScript","funding_links":["https://github.com/sponsors/char0n","https://patreon.com/char0n","https://ko-fi.com/char0n","https://liberapay.com/char0n","https://issuehunt.io/r/char0n"],"categories":[],"sub_categories":[],"readme":"# asyncapi-runtime-expression\n\n[Runtime Expressions](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#runtimeExpression) allow values to be defined based on information that will be available within the message.\nThis mechanism is used by [Correlation ID Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#correlationIdObject) of [AsyncAPI specification](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md).\n\n`asyncapi-runtime-expression` is a **parser** and **validator** for AsyncAPI Runtime Expressions. It supports\nRuntime Expressions defined in following AsyncAPI specification versions:\n\n- [AsynCAPI 2.0.0](https://www.asyncapi.com/docs/reference/specification/v2.0.0#runtimeExpression)\n- [AsynCAPI 2.1.0](https://www.asyncapi.com/docs/reference/specification/v2.1.0#runtimeExpression)\n- [AsyncAPI 2.2.0](https://www.asyncapi.com/docs/reference/specification/v2.2.0#runtimeExpressionn)\n- [AsyncAPI 2.3.0](https://www.asyncapi.com/docs/reference/specification/v2.3.0#runtimeExpression)\n- [AsyncAPI 2.4.0](https://www.asyncapi.com/docs/reference/specification/v2.4.0#runtimeExpression)\n- [AsyncAPI 2.5.0](https://www.asyncapi.com/docs/reference/specification/v2.5.0#runtimeExpression)\n- [AsyncAPI 2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0#runtimeExpression)\n\n## Table of Contents\n\n- [Getting started](#getting-started)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [Parsing](#parsing)\n    - [Validation](#validation)\n    - [Grammar](#grammar)\n- [More about AsyncAPI runtime expressions](#more-about-asyncapi-runtime-expressions)\n- [License](#license)\n- [Software Bill Of Materials (SBOM)](#software-bill-of-materials-sbom)\n\n\n## Getting started\n\n### Installation\n\nYou can install `asyncapi-runtime-expression` using `npm`:\n\n```sh\n $ npm install asyncapi-runtime-expression\n```\n\nGiven that `asyncapi-runtime-expression` is a [pure ESM package](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)\nyou can also install it directly from GitHub.\n\n```sh\n $ npm install github:char0n/asyncapi-runtime-expression\n```\n\n### Usage\n\n`asyncapi-runtime-expression` currently supports **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-js](https://github.com/ldthomas/apg-js) parser generator.\n\n#### Parsing\n\nParsing a Runtime Expression is as simple as importing the **parse** function\nand calling it.\n\n```js\nimport { parse } from 'asyncapi-runtime-expression';\n\nconst parseResult = parse('$message.payload#/user/id');\n```\n\n**parseResult** variable has the following shape:\n\n```\n{\n  result: {\n    success: true,\n    state: 101,\n    length: 22,\n    matched: 22,\n    maxMatched: 22,\n    maxTreeDepth: 14,\n    nodeHits: 152,\n    inputLength: 22,\n    subBegin: 0,\n    subEnd: 22,\n    subLength: 22\n  },\n  ast: exportsAst {\n    callbacks: [\n      expression: [Function: expression],\n      source: [Function: source],\n      'payload-reference': [Function: payloadReference],\n      fragment': [Function: fragment],\n      'reference-token': [Function: referenceToken],\n    ],\n    astObject: 'astObject',\n    init: [Function: init],\n    ruleDefined: [Function: ruleDefined],\n    udtDefined: [Function: udtDefined],\n    down: [Function: down],\n    up: [Function: up],\n    translate: [Function: translate],\n    setLength: [Function: setLength],\n    getLength: [Function: getLength],\n    toXml: [Function: toSml],\n    phrases: [Function: phrases]\n  }\n}\n```\n\n###### Interpreting AST as list of entries\n\n```js\nimport { parse } from 'asyncapi-runtime-expression';\n\nconst parseResult = parse('$message.payload#/user/id');\nconst parts = [];\n\nparseResult.ast.translate(parts);\n```\n\nAfter running the above code, **parts** variable has the following shape:\n\n```js\n[\n  ['expression', '$message.payload#/user/id'],\n  ['source', 'payload#/user/id'],\n  ['payload-reference', 'payload#/user/id'],\n  ['fragment', '/user/id'],\n  ['reference-token', 'user'],\n  ['reference-token', 'id']\n]\n```\n\n###### Interpreting AST as XML\n\n```js\nimport { parse } from 'asyncapi-runtime-expression';\n\nconst parseResult = parse('$message.payload#/user/id');\nconst xml = parseResult.ast.toXml();\n```\n\nAfter running the above code, **xml** variable has the following content:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n\u003croot nodes=\"6\" characters=\"25\"\u003e\n  \u003c!-- input string, decimal integer character codes --\u003e\n  36,109,101,115,115,97,103,101,46,112,97,121,108,111,97,100,35,47,117,115,101,114,47,105,100\n  \u003cnode name=\"expression\" index=\"0\" length=\"25\"\u003e\n    36,109,101,115,115,97,103,101,46,112,97,121,108,111,97,100,35,47,117,115,101,114,47,105,100\n    \u003cnode name=\"source\" index=\"9\" length=\"16\"\u003e\n      112,97,121,108,111,97,100,35,47,117,115,101,114,47,105,100\n      \u003cnode name=\"payload-reference\" index=\"9\" length=\"16\"\u003e\n        112,97,121,108,111,97,100,35,47,117,115,101,114,47,105,100\n        \u003cnode name=\"fragment\" index=\"17\" length=\"8\"\u003e\n          47,117,115,101,114,47,105,100\n          \u003cnode name=\"reference-token\" index=\"18\" length=\"4\"\u003e\n            117,115,101,114\n          \u003c/node\u003e\u003c!-- name=\"reference-token\" --\u003e\n          \u003cnode name=\"reference-token\" index=\"23\" length=\"2\"\u003e\n            105,100\n          \u003c/node\u003e\u003c!-- name=\"reference-token\" --\u003e\n        \u003c/node\u003e\u003c!-- name=\"fragment\" --\u003e\n      \u003c/node\u003e\u003c!-- name=\"payload-reference\" --\u003e\n    \u003c/node\u003e\u003c!-- name=\"source\" --\u003e\n  \u003c/node\u003e\u003c!-- name=\"expression\" --\u003e\n\u003c/root\u003e\n```\n\n\u003e 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).\n\n#### Validation\n\nValidating a Runtime Expression is as simple as importing the **test** function\nand calling it.\n\n```js\nimport { test } from 'asyncapi-runtime-expression';\n\ntest('$message.payload#/user/id'); // =\u003e true\ntest('nonsensical string'); // =\u003e false\n```\n\n#### Grammar\n\nNew grammar instance can be created in following way:\n\n```js\nimport { Grammar } from 'asyncapi-runtime-expression';\n\nconst grammar = new Grammar();\n```\n\nTo obtain original ABNF (SABNF) grammar as a string:\n\n```js\nimport { Grammar } from 'asyncapi-runtime-expression';\n\nconst grammar = new Grammar();\n\ngrammar.toString();\n// or\nString(grammar);\n```\n\n## More about AsyncAPI runtime expressions\n\nThe runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax\n\n```abnf\nexpression = ( \"$message\" \".\" source )\nsource = ( header-reference | payload-reference )\nheader-reference = \"header\" [\"#\" fragment]\npayload-reference = \"payload\" [\"#\" fragment]\nfragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)\n```\n\n\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---|:---|:---|\nMessage Header Property | `$message.header#/MQMD/CorrelId` | Correlation ID is set using the `CorrelId` value from the `MQMD` header.\nMessage Payload Property | `$message.payload#/messageId` | Correlation ID is set using the `messageId` value from the message payload.\n\nRuntime expressions preserve the type of the referenced value.\n\n## License\n\n`asyncapi-runtime-expression` is licensed under [Apache 2.0 license](https://github.com/char0n/asyncapi-runtime-expression/blob/main/LICENSE).\n`asyncapi-runtime-expression` comes with an explicit [NOTICE](https://github.com/char0n/asyncapi-runtime-expression/blob/main/NOTICE) file\ncontaining additional legal notices and information.\n\n## Software Bill Of Materials (SBOM)\n\nSoftware Bill Of materials is available in [sbom.spdx.yaml](https://github.com/char0n/asyncapi-runtime-expression/blob/main/sbom.spdx.yaml) using [SPDX](https://spdx.dev/) language.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggerexpert%2Fasyncapi-runtime-expression","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswaggerexpert%2Fasyncapi-runtime-expression","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggerexpert%2Fasyncapi-runtime-expression/lists"}