@n8n/expression-runtime 0.14.2 → 0.16.0

package/dist/esm/bridge/bridge-messages.js

@@ -0,0 +1,250 @@
+/**
+ * Schemas for messages the in-isolate runtime sends to the host via the
+ * `callHost` typed-RPC dispatcher.
+ *
+ * The isolate is an untrusted source: anything that crosses the bridge must
+ * be validated for shape and types at the boundary. We do that with zod
+ * rather than relying on TypeScript discriminated unions, because TS types
+ * are erased at runtime and contribute zero security.
+ *
+ * Each operation has its own schema. The dispatcher entry validates the
+ * envelope against the discriminated union, throws on any deviation
+ * (unknown `type`, missing/typo'd fields, wrong field types), and then
+ * delegates to a handler that operates on the parsed (statically narrowed)
+ * message.
+ *
+ * Each additional typed RPC lands as a new schema here plus a new `case`
+ * in the bridge's dispatcher switch.
+ */
+import { z } from 'zod';
+/**
+ * `$('NodeName').first(branchIndex?, runIndex?)` — fetch the first item of
+ * a named node's most recent execution data.
+ */
+export const getNodeFirstMessage = z
+    .object({
+    type: z.literal('getNodeFirst'),
+    nodeName: z.string(),
+    branchIndex: z.number().int().nonnegative().optional(),
+    runIndex: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * `$('NodeName').last(branchIndex?, runIndex?)` — fetch the last item of
+ * a named node's most recent execution data.
+ */
+export const getNodeLastMessage = z
+    .object({
+    type: z.literal('getNodeLast'),
+    nodeName: z.string(),
+    branchIndex: z.number().int().nonnegative().optional(),
+    runIndex: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * `$('NodeName').all(branchIndex?, runIndex?)` — fetch every item of a
+ * named node's most recent execution data as an array.
+ */
+export const getNodeAllMessage = z
+    .object({
+    type: z.literal('getNodeAll'),
+    nodeName: z.string(),
+    branchIndex: z.number().int().nonnegative().optional(),
+    runIndex: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * `$input.first()` — fetch the first item of the current node's input.
+ * Host enforces zero arguments; the schema has no fields besides `type`.
+ */
+export const getInputFirstMessage = z.object({ type: z.literal('getInputFirst') }).strict();
+/**
+ * `$input.last()` — fetch the last item of the current node's input.
+ */
+export const getInputLastMessage = z.object({ type: z.literal('getInputLast') }).strict();
+/**
+ * `$input.all()` — fetch every item of the current node's input.
+ */
+export const getInputAllMessage = z.object({ type: z.literal('getInputAll') }).strict();
+/**
+ * `$items(nodeName?, outputIndex?, runIndex?)` — fetch the execution data of
+ * a node by name (or the current node's input if `nodeName` is omitted).
+ *
+ * `runIndex` accepts negative values: the host uses `-1` as a sentinel for
+ * "latest run" (see `WorkflowDataProxy.$items` —
+ * `runIndex === undefined ? -1 : runIndex`). The schema uses
+ * `z.number().int()` without `.nonnegative()` so expressions can pass `-1`
+ * explicitly if they need to.
+ */
+export const getItemsMessage = z
+    .object({
+    type: z.literal('getItems'),
+    nodeName: z.string().optional(),
+    outputIndex: z.number().int().nonnegative().optional(),
+    runIndex: z.number().int().optional(),
+})
+    .strict();
+/**
+ * `$fromAI(name, description?, type?, defaultValue?)` — the AI-builder
+ * placeholder accessor (aliases: `$fromAi`, `$fromai`).
+ *
+ * Two deliberate looseness points in this schema, both to preserve host
+ * contract / parity:
+ *
+ * 1. `name` is `z.string().optional()` (not required) so a call missing
+ *    the argument or passing an empty string reaches the host, which
+ *    throws the user-friendly `ExpressionError("Add a key, e.g. $fromAI('placeholder_name')")`.
+ *    Requiring it here would replace that error with a generic zod
+ *    message. The host also validates the regex `[a-zA-Z0-9_-]{0,64}`;
+ *    we don't pre-empt that either.
+ * 2. `defaultValue` is `z.unknown()` because the host accepts any value
+ *    as the fallback return (`handleFromAi` returns it directly via
+ *    `??`). Structured-clone at the bridge boundary still prevents
+ *    functions and other non-cloneable values from crossing.
+ *
+ * `description` and `type` are forwarded even though the host currently
+ * ignores them (`_description`, `_type`), so the protocol matches the
+ * documented call signature.
+ */
+export const fromAiMessage = z
+    .object({
+    type: z.literal('fromAi'),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    valueType: z.string().optional(),
+    // `z.unknown()` already accepts `undefined`, so no `.optional()` needed.
+    defaultValue: z.unknown(),
+})
+    .strict();
+/**
+ * `$('NodeName').pairedItem(itemIndex?)` / `.itemMatching(itemIndex)` /
+ * `.item` — resolve the paired item for a referenced node.
+ *
+ * All three host-side surface forms share one internal resolver
+ * (`pairedItemMethod` in `WorkflowDataProxy`), but the resolver closes
+ * over the literal property name the bridge accessed on the host proxy
+ * — so the error message and getter-vs-method form depend on *which*
+ * property the bridge reads. Three separate discriminators, each
+ * mapping a handler to a fixed literal property name, are the only way
+ * to preserve the host's friendly errors (e.g. "Missing item index for
+ * .itemMatching()") and the `.item` getter semantics without
+ * duplicating logic in-isolate.
+ *
+ * `itemIndex` is optional on all three at the schema level; the host
+ * throws the appropriate `ExpressionError` when it's missing for
+ * `.itemMatching()`, and applies the current-itemIndex default for
+ * `.pairedItem` and `.item`.
+ */
+export const getNodePairedItemMessage = z
+    .object({
+    type: z.literal('getNodePairedItem'),
+    nodeName: z.string(),
+    itemIndex: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * `itemIndex` is `.optional()` even though `.itemMatching()` requires it
+ * at the host. The host's `pairedItemMethod` closure throws the friendly
+ * `"Missing item index for .itemMatching()"` error when the field is
+ * absent — keeping the schema permissive lets that host error surface
+ * verbatim instead of being replaced by a generic zod parse failure.
+ */
+export const getNodeItemMatchingMessage = z
+    .object({
+    type: z.literal('getNodeItemMatching'),
+    nodeName: z.string(),
+    itemIndex: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const getNodeItemMessage = z
+    .object({
+    type: z.literal('getNodeItem'),
+    nodeName: z.string(),
+})
+    .strict();
+/**
+ * `$evaluateExpression(expression, itemIndex?)` — evaluate a nested
+ * expression string at runtime against the same execution context.
+ *
+ * The host recursively invokes the expression engine on the `expression`
+ * string — under the VM engine this re-enters the bridge with a fresh
+ * evaluation. `itemIndex` is optional and defaults to the current item;
+ * the schema mirrors the existing "nonnegative int" constraint used by
+ * the node-data RPCs.
+ */
+export const evaluateExpressionMessage = z
+    .object({
+    type: z.literal('evaluateExpression'),
+    expression: z.string(),
+    itemIndex: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * `ISourceData` — the source record that accompanies a paired-item
+ * traversal step. Mirrors the host interface used by
+ * `WorkflowDataProxy.getPairedItem`.
+ */
+const sourceDataSchema = z
+    .object({
+    previousNode: z.string(),
+    previousNodeOutput: z.number().int().nonnegative().optional(),
+    previousNodeRun: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * `IPairedItemData` — one paired-item record. `sourceOverwrite` lets a
+ * node override the upstream source while the helper walks the ancestry
+ * chain; the field is optional and recurses through the same schema.
+ */
+const pairedItemDataSchema = z
+    .object({
+    item: z.number().int().nonnegative(),
+    input: z.number().int().nonnegative().optional(),
+    sourceOverwrite: sourceDataSchema.optional(),
+})
+    .strict();
+/**
+ * `$getPairedItem(destinationNodeName, incomingSourceData, initialPairedItem)` —
+ * traverse the paired-item ancestry chain back to the named upstream node
+ * and return the matching execution item.
+ *
+ * Two host-side fields are deliberately omitted from the schema:
+ * - `usedMethodName` defaults to `$getPairedItem` on the host; the isolate
+ *   has no reason to spoof a different method name in the error path.
+ * - `nodeBeforeLast` is an internal recursion argument; only the host
+ *   itself sets it during the recursive walk.
+ *
+ * `incomingSourceData` is nullable because the host's signature accepts
+ * `ISourceData | null` (and throws a paired-item-not-found error when null).
+ */
+export const getPairedItemMessage = z
+    .object({
+    type: z.literal('getPairedItem'),
+    destinationNodeName: z.string(),
+    incomingSourceData: sourceDataSchema.nullable(),
+    initialPairedItem: pairedItemDataSchema,
+})
+    .strict();
+/**
+ * The full set of messages the bridge will accept. Discriminator is `type`.
+ *
+ * Use `.strict()` on each member so unknown fields are rejected rather than
+ * silently ignored — this catches typos in the runtime stubs and keeps the
+ * protocol surface tight.
+ */
+export const bridgeMessageSchema = z.discriminatedUnion('type', [
+    getNodeFirstMessage,
+    getNodeLastMessage,
+    getNodeAllMessage,
+    getInputFirstMessage,
+    getInputLastMessage,
+    getInputAllMessage,
+    getItemsMessage,
+    fromAiMessage,
+    getNodePairedItemMessage,
+    getNodeItemMatchingMessage,
+    getNodeItemMessage,
+    evaluateExpressionMessage,
+    getPairedItemMessage,
+]);
+//# sourceMappingURL=bridge-messages.js.map

package/dist/esm/bridge/bridge-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-messages.js","sourceRoot":"","sources":["../../../src/bridge/bridge-messages.ts"],"names":[],"mappings":"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"}

package/dist/esm/bridge/isolated-vm-bridge.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeBridge, BridgeConfig, ExecuteOptions } from '../types';
+import type { RuntimeBridge, BridgeConfig, ExecuteOptions, WorkflowData } from '../types';
 /**
  * IsolatedVmBridge - Runtime bridge using isolated-vm for secure expression evaluation.
  *
@@ -81,7 +81,13 @@ export declare class IsolatedVmBridge implements RuntimeBridge {
      * Create an ivm.Reference callback for getting value/metadata at a path.
      *
      * Used by createDeepLazyProxy when accessing properties. Returns metadata
-     * markers for functions, arrays, and objects, or the primitive value directly.
+     * markers for arrays and objects, or the primitive value directly.
+     *
+     * Function-typed values are returned as `undefined` — every callable on
+     * the host data surface (`$('Foo').first()`, `$items()`, `$fromAI()`,
+     * `$evaluateExpression()`, `$getPairedItem()`) is wired in-isolate via
+     * the typed-RPC dispatcher (`callHost`). No expression form should
+     * reach a function through this path.
      *
      * @param data - Current workflow data to use for callback responses
      * @private
@@ -97,23 +103,140 @@ export declare class IsolatedVmBridge implements RuntimeBridge {
      */
     private createGetArrayElementRef;
     /**
-     * Create an ivm.Reference callback for calling functions at a path.
+     * Create the single typed-RPC dispatcher.
      *
-     * Used when expressions invoke functions from workflow data.
+     * The isolate sends one envelope per typed RPC invocation:
+     *   `callHost({ type: 'getNodeFirst', nodeName, branchIndex?, runIndex? })`
+     *
+     * Inputs cross a trust boundary, so the dispatcher parses every envelope
+     * with the host-side zod schema (`bridgeMessageSchema`) before any
+     * dispatch happens. Anything that deviates from the declared shape —
+     * unknown `type`, missing required fields, extra unexpected fields,
+     * wrong field types — fails the parse and an error sentinel is returned
+     * to the caller.
+     *
+     * After parsing, `switch (msg.type)` dispatches to a private handler with
+     * a fully narrowed message type. The operation set is exactly the cases
+     * in this switch; the `type` field selects a static branch in source,
+     * not a property lookup on a runtime object.
+     *
+     * @param data - Current workflow data
+     * @private
+     */
+    private createCallHostRef;
+    /**
+     * Handlers for the `$('Foo').{first,last,all}` typed RPCs.
+     *
+     * Each handler reads a fixed literal property name off the host-side node
+     * proxy — the isolate cannot influence which property is dereferenced.
+     * Eliminating `data.$` as a host-callable entirely would require reaching
+     * the `WorkflowDataProxy` internals (e.g. `getNodeExecutionOrPinnedData`)
+     * rather than the public `$()` API; that's a follow-up.
+     *
+     * `data.$` is a host-wired function (`WorkflowDataProxy`'s `$`). If it
+     * ever isn't, optional chaining short-circuits to `undefined` — the same
+     * observable result the runtime's `E()` handler produces from any thrown
+     * error here.
+     *
+     * @private
+     */
+    private handleGetNodeFirst;
+    private handleGetNodeLast;
+    private handleGetNodeAll;
+    /**
+     * Handlers for the `$input.{first,last,all}` typed RPCs.
+     *
+     * Each reads a fixed literal property name off `data.$input` (the host's
+     * `WorkflowDataProxy` input proxy). The host enforces zero arguments on
+     * these methods — the schemas have no fields besides `type`, so the
+     * isolate cannot pass anything that would trigger the "should have no
+     * arguments" error path on the host side.
+     *
+     * @private
+     */
+    private handleGetInputFirst;
+    private handleGetInputLast;
+    private handleGetInputAll;
+    /**
+     * Handler for `$items(nodeName?, outputIndex?, runIndex?)` — the
+     * global accessor for a node's execution data. Reads the literal
+     * `$items` property off `data` (host-wired by `WorkflowDataProxy`)
+     * and forwards the validated args verbatim. The host applies its own
+     * defaults when fields are `undefined`.
+     *
+     * @private
+     */
+    private handleGetItems;
+    /**
+     * Handler for `$fromAI(name, description?, type?, defaultValue?)` and its
+     * `$fromAi` / `$fromai` aliases. Reads the literal `$fromAI` property
+     * off `data` (host-wired) and forwards the args. The host validates
+     * `name` (required + regex) and applies its own resolution / fallback
+     * logic, so empty / invalid names surface as the host's structured
+     * `ExpressionError` rather than a generic zod parse error.
+     *
+     * Note: `msg.valueType` maps to the host's third positional parameter
+     * (`_type` in `WorkflowDataProxy.handleFromAi`). The bridge protocol
+     * renames it to avoid collision with the `type` discriminator on the
+     * envelope — the host parameter currently goes unused, but if it ever
+     * gains a name (`type`), this mapping should stay explicit.
+     *
+     * @private
+     */
+    private handleFromAi;
+    /**
+     * Handlers for the `$('Foo').pairedItem(itemIndex?)` / `.itemMatching(...)` /
+     * `.item` cluster. Three separate typed RPCs, each reading exactly one
+     * literal property off the host node proxy.
+     *
+     * The split is load-bearing: the host's `pairedItemMethod` closure
+     * captures which property name the proxy `get` trap saw, and uses
+     * that to pick the right error message (e.g. "Missing item index for
+     * .itemMatching()") and to decide between method-call vs getter
+     * semantics for `.item`. Reading the matching property here lets
+     * those host-side branches fire exactly as they do in the legacy
+     * engine; no in-isolate validation needed.
+     *
+     * @private
+     */
+    private handleGetNodePairedItem;
+    private handleGetNodeItemMatching;
+    private handleGetNodeItem;
+    /**
+     * Handler for `$evaluateExpression(expression, itemIndex?)`. Forwards
+     * the string to the host's nested-evaluation helper, which re-enters
+     * the expression engine on the inner expression. Under the VM engine
+     * this round-trips through the bridge again on a fresh evaluation
+     * cycle, which is the same shape the legacy engine supports.
+     *
+     * @private
+     */
+    private handleEvaluateExpression;
+    /**
+     * Handler for `$getPairedItem(destinationNodeName, incomingSourceData,
+     * initialPairedItem)`. Forwards directly to the host binding, which
+     * walks the paired-item ancestry chain back to the named upstream node
+     * and returns the matching execution item.
+     *
+     * The two trailing host parameters — `usedMethodName` and
+     * `nodeBeforeLast` — are deliberately not part of the wire protocol:
+     * the host's default for `usedMethodName` is already `$getPairedItem`,
+     * and `nodeBeforeLast` is an internal recursion argument the host sets
+     * during traversal.
      *
-     * @param data - Current workflow data to use for callback responses
      * @private
      */
-    private createCallFunctionAtPathRef;
+    private handleGetPairedItem;
     /**
      * Execute JavaScript code in the isolated context.
      *
      * Flow:
-     * 1. Create three ivm.Reference callbacks scoped to the current data
-     * 2. Use evalClosureSync to run the code in a closure where $0/$1/$2
-     *    are the callback references — no global mutable state
+     * 1. Create three ivm.Reference callbacks scoped to the current data:
+     *    `getValueAtPath`, `getArrayElement`, `callHost`.
+     * 2. Use evalClosureSync to run the code in a closure where `$0`/`$1`/`$2`
+     *    are the callback references — no global mutable state.
      * 3. buildContext() inside the isolate creates a fresh evaluation context
-     *    from the closure-scoped references
+     *    from the closure-scoped references.
      *
      * Each call gets its own closure, so nested and concurrent evaluations
      * cannot interfere with each other.
@@ -123,7 +246,7 @@ export declare class IsolatedVmBridge implements RuntimeBridge {
      * @returns Result of the expression
      * @throws {Error} If bridge not initialized or execution fails
      */
-    execute(code: string, data: Record<string, unknown>, options?: ExecuteOptions): unknown;
+    execute(code: string, data: WorkflowData, options?: ExecuteOptions): unknown;
     /**
      * Reconstruct an error from serialized isolate data.
      *

package/dist/esm/bridge/isolated-vm-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isolated-vm-bridge.d.ts","sourceRoot":"","sources":["../../../src/bridge/isolated-vm-bridge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA0E5E;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,MAAM,CAAmC;gBAErC,MAAM,GAAE,YAAiB;IAYrC;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC;;;;;;;;;;;OAWG;YACW,mBAAmB;IAgCjC;;;;;;;;OAQG;YACW,iBAAiB;IA4B/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,kBAAkB;IAwBhC;;;;;;;;OAQG;IACH,OAAO,CAAC,uBAAuB;IAgE/B;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAyDhC;;;;;;;OAOG;IACH,OAAO,CAAC,2BAA2B;IAkCnC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO;IAsFvF;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;;;OAIG;IACH,UAAU,IAAI,OAAO;CAGrB"}
+{"version":3,"file":"isolated-vm-bridge.d.ts","sourceRoot":"","sources":["../../../src/bridge/isolated-vm-bridge.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AA2E1F;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACrD,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,MAAM,CAAmC;gBAErC,MAAM,GAAE,YAAiB;IAYrC;;;;;;;;;;OAUG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BjC;;;;;;;;;;;OAWG;YACW,mBAAmB;IAgCjC;;;;;;;;OAQG;YACW,iBAAiB;IA4B/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACW,kBAAkB;IAwBhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,uBAAuB;IA+D/B;;;;;;;OAOG;IACH,OAAO,CAAC,wBAAwB;IAyDhC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,iBAAiB;IA+CzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,gBAAgB;IAOxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,iBAAiB;IAIzB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAOtB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,yBAAyB;IAOjC,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO;IA6F5E;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;;;OAIG;IACH,UAAU,IAAI,OAAO;CAGrB"}