CEL Utilities

The @scenario-labs/sdk/tools/cel subpath exports a shared CEL evaluation environment used by the Scenario backend, frontend, and MCP server to evaluate workflow transform expressions identically. Import from the dedicated subpath — it is not part of the default entry point.

import { evaluateCel, createCelEnvironment } from '@scenario-labs/sdk/tools/cel';

---

evaluateCel(expression, variables?, options?)

Canonical CEL evaluation entry point. Registers exists(name) bound to variables, plus any per-call extra functions, then evaluates the expression.

Signature

evaluateCel<T = unknown>(
  expression: string,
  variables?: Record<string, unknown>,
  options?: EvaluateCelOptions,
): T

Parameters

Name	Type	Description
expression	string	The CEL expression to evaluate.
variables?	Record<string, unknown>	Variable bindings for the expression. Defaults to {}.
options?	EvaluateCelOptions	Extra per-call functions. See EvaluateCelOptions.

Returns

T — the evaluated result, cast to the type parameter. If a registered handler is async, cel-js returns a Promise — use await evaluateCel<Promise<T>>(...) in that case.

Example

import { evaluateCel } from '@scenario-labs/sdk/tools/cel';

const result = evaluateCel<number>('x + 1', { x: 41 });
console.log(result); // 42

// exists() is provided automatically, bound to the variables object:
const hasX = evaluateCel<boolean>('exists("x")', { x: 41 });
console.log(hasX); // true

Note

options.functions must not redeclare a base function (trim, slice, random, randomSample) or exists — cel-js throws on overlapping signatures rather than overriding.

---

createCelEnvironment()

Returns a fresh, extensible clone of the shared base CEL environment with trim, slice, random, and randomSample pre-registered. Consumers may register additional functions on it.

exists() is NOT available through this API — it must be bound per evaluation to a specific variables object. Use evaluateCel if you need exists().

Signature

createCelEnvironment(): Environment

Returns

Environment (from @marcbachmann/cel-js) — a cloned environment with base functions registered.

Example

import { createCelEnvironment } from '@scenario-labs/sdk/tools/cel';

const env = createCelEnvironment();

env.registerFunction('greet(string): string', (name: string) => `Hello, ${name}!`);

const result = env.evaluate('greet(name)', { name: 'world' });
console.log(result); // 'Hello, world!'

---

Base functions

The following functions are always available in every environment created by this module.

trim(value)

Trim leading and trailing whitespace. Null-safe: null becomes "".

CEL signature: trim(dyn): string

---

slice(list, start, end)

Return list[start:end] with JavaScript Array.prototype.slice semantics.

CEL signature: slice(dyn, int, int): list

---

random(digits)

Random integer with exactly digits digits (e.g. random(5) → 48574). Unseeded; not deterministic. Semantics are ported verbatim from the backend for back-compat with deployed workflows.

CEL signature: random(int): int

---

randomSample(list, count[, seed][, withReplacement])

Sample items from a list. An integer seed makes the result reproducible — the same seed produces the same sample across all Scenario runtimes (backend, frontend, MCP server). Without replacement, count is clamped to the list size rather than throwing.

Four overloads are registered:

randomSample(list, int): list
randomSample(list, int, int): list        — with seed
randomSample(list, int, bool): list       — with withReplacement
randomSample(list, int, int, bool): list  — with seed and withReplacement

Example

import { evaluateCel } from '@scenario-labs/sdk/tools/cel';

const items = ['a', 'b', 'c', 'd', 'e'];

// Reproducible 3-item sample with seed 42:
const sample = evaluateCel<string[]>('randomSample(items, 3, 42)', { items });
// The backend will return the same 3 items for the same seed.

---

exists(name) — via evaluateCel only

Returns true when the named variable was provided and is not null. Registered by evaluateCel bound to the current variables object — not available on environments created with createCelEnvironment.

CEL signature: exists(string): bool

---

EvaluateCelOptions

interface EvaluateCelOptions {
  /** Extra functions registered for this evaluation only. */
  functions?: CelFunctionRegistration[];
}

---

CelFunctionRegistration

Descriptor for a function to register in a CEL environment.

interface CelFunctionRegistration {
  /** cel-js signature string, e.g. 'assetJson(string): dyn' */
  signature: string;
  handler: (...args: never[]) => unknown;
  description?: string;
  params?: CelFunctionParam[];
}

Name	Type	Description
signature	string	cel-js signature string, e.g. 'assetJson(string): dyn'.
handler	(...args: never[]) => unknown	The function implementation.
description?	string	Human-readable description surfaced by env.getDefinitions().
params?	CelFunctionParam[]	Parameter metadata for UI tooling (e.g. autocomplete palettes).

---

CelFunctionParam

interface CelFunctionParam {
  name: string;
  description?: string;
}