@companion-app/expressions

Parser and evaluator for Bitfocus Companion's expression dialect.

This package parses Companion expressions (a sandboxed JavaScript-like language with $(label:name) variable references) into an AST and evaluates them against a set of variables and builtin functions.

Writing expressions? If you're looking for documentation on the expression language itself — syntax, operators, available functions — see the user guide: https://companion.free/user-guide/beta/expressions/

The rest of this README covers using the library programmatically.

Installation

yarn add @companion-app/expressions

Usage

import { ExpressionFunctions, ParseExpression, ResolveExpression } from '@companion-app/expressions'

// 1. Parse an expression into an AST. This validates the syntax and rejects
//    anything the evaluator does not support, throwing on invalid input.
const node = ParseExpression('$(internal:time_hms) + " — " + round($(my:temperature))')

// 2. Provide variable values. The callback is invoked for each `$(label:name)` reference.
const variables: Record<string, string | number> = {
	'internal:time_hms': '12:34:56',
	'my:temperature': 21.4,
}

// 3. Evaluate, passing in the builtin functions.
const result = ResolveExpression(node, ({ variableId }) => variables[variableId], ExpressionFunctions)

console.log(result) // "12:34:56 — 21"

Execution limits

Evaluation is sandboxed and bounded. ResolveExpression accepts an options object to tune the budget (useful for cheap, hot paths):

ResolveExpression(node, getVariable, ExpressionFunctions, {
	maxOperations: 10_000, // loop iterations + function calls before aborting
	maxCallDepth: 50, // closure call-stack depth before aborting
})

API

• ParseExpression(expression) — parse + validate a string into an AST node (SomeExpressionNode). Throws on invalid syntax.
• ValidateExpression(node) — validate an already-parsed acorn AST against the allowed dialect (used internally by ParseExpression).
• ResolveExpression(node, getVariableValue, functions?, options?) — evaluate a parsed AST and return its value.
• ExpressionFunctions — the builtin function library passed to ResolveExpression.

Development

corepack enable
yarn install
yarn build   # type-check + emit dist/
yarn unit    # run the vitest suite
yarn lint    # eslint

License

MIT