@n8n/expression-runtime 0.2.0

package/dist/types/evaluator.d.ts

@@ -0,0 +1,197 @@
+import type { RuntimeBridge } from './bridge';
+export interface TournamentHooks {
+    before?: Array<(ast: unknown) => unknown>;
+    after?: Array<(ast: unknown) => unknown>;
+}
+/**
+ * Configuration for ExpressionEvaluator.
+ *
+ * Note: Slice 1 keeps this minimal. Tournament integration and code caching
+ * will be added in later slices.
+ */
+export interface EvaluatorConfig {
+    /**
+     * Runtime bridge implementation.
+     */
+    bridge: RuntimeBridge;
+    /**
+     * Observability provider for metrics, traces, and logs.
+     */
+    observability?: ObservabilityProvider;
+    /**
+     * AST security hooks for tournament expression transformation.
+     * Provided by the caller (e.g., workflow package's expression-sandboxing.ts).
+     * If omitted, expressions are transformed with no security hooks (dev/testing use).
+     */
+    hooks?: TournamentHooks;
+}
+/**
+ * Expression evaluator - main public API.
+ *
+ * This is the primary interface used by the workflow package.
+ */
+export interface IExpressionEvaluator {
+    /**
+     * Initialize the evaluator and bridge.
+     * Must be called before evaluate().
+     */
+    initialize(): Promise<void>;
+    /**
+     * Evaluate an expression string against workflow data.
+     *
+     * @param expression - Expression string (e.g., "{{ $json.email }}")
+     * @param data - Workflow data context
+     * @param options - Evaluation options
+     * @returns Result of the expression
+     *
+     * Note: Synchronous for Slice 1 (Node.js vm module).
+     *       Will be async for Slice 2 (isolated-vm).
+     */
+    evaluate(expression: string, data: WorkflowData, options?: EvaluateOptions): unknown;
+    /**
+     * Dispose of the evaluator and free resources.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Check if the evaluator has been disposed.
+     */
+    isDisposed(): boolean;
+}
+/**
+ * Workflow data proxy from WorkflowDataProxy.getDataProxy().
+ *
+ * For Slice 1: We pass this directly via VM context (simple pass-through).
+ * Later: Will implement deep lazy proxy for field-level data fetching.
+ */
+export type WorkflowData = Record<string, unknown>;
+/**
+ * Options for evaluate().
+ */
+/**
+ * Options for evaluate().
+ *
+ * Note: Slice 1 is minimal. Tournament options will be added later.
+ */
+export interface EvaluateOptions {
+    /**
+     * Custom timeout for this evaluation (in milliseconds).
+     * Overrides the bridge's default timeout.
+     */
+    timeout?: number;
+}
+/**
+ * Observability provider interface.
+ *
+ * Implementations: NoOpProvider, OpenTelemetryProvider, PostHogProvider
+ */
+export interface ObservabilityProvider {
+    /**
+     * Metrics API.
+     */
+    metrics: MetricsAPI;
+    /**
+     * Traces API.
+     */
+    traces: TracesAPI;
+    /**
+     * Logs API.
+     */
+    logs: LogsAPI;
+}
+/**
+ * Metrics API.
+ */
+export interface MetricsAPI {
+    /**
+     * Increment a counter.
+     */
+    counter(name: string, value: number, tags?: Record<string, string>): void;
+    /**
+     * Set a gauge value.
+     */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    /**
+     * Record a histogram value.
+     */
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+}
+/**
+ * Traces API.
+ */
+export interface TracesAPI {
+    /**
+     * Start a new span.
+     */
+    startSpan(name: string, attributes?: Record<string, unknown>): Span;
+}
+/**
+ * Span interface.
+ */
+export interface Span {
+    /**
+     * Set span status.
+     */
+    setStatus(status: 'ok' | 'error'): void;
+    /**
+     * Set span attribute.
+     */
+    setAttribute(key: string, value: unknown): void;
+    /**
+     * Record an exception.
+     */
+    recordException(error: Error): void;
+    /**
+     * End the span.
+     */
+    end(): void;
+}
+/**
+ * Logs API.
+ */
+export interface LogsAPI {
+    /**
+     * Log an error.
+     */
+    error(message: string, error?: Error, context?: Record<string, unknown>): void;
+    /**
+     * Log a warning.
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log info.
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log debug.
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Expression evaluation error.
+ */
+export declare class ExpressionError extends Error {
+    context: {
+        expression?: string;
+        workflowId?: string;
+        nodeId?: string;
+        [key: string]: unknown;
+    };
+    constructor(message: string, context: {
+        expression?: string;
+        workflowId?: string;
+        nodeId?: string;
+        [key: string]: unknown;
+    });
+}
+/**
+ * Specific error types.
+ */
+export declare class MemoryLimitError extends ExpressionError {
+}
+export declare class TimeoutError extends ExpressionError {
+}
+export declare class SecurityViolationError extends ExpressionError {
+}
+export declare class SyntaxError extends ExpressionError {
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/types/evaluator.d.ts.map

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

package/dist/types/evaluator.js

@@ -0,0 +1,29 @@
+// ============================================================================
+// Phase 1.4: Error Handling (IMPLEMENT WITH EVALUATOR)
+//
+// These error types provide structured error information.
+// Start with basic Error, add these types in Phase 1.4.
+// ============================================================================
+/**
+ * Expression evaluation error.
+ */
+export class ExpressionError extends Error {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'ExpressionError';
+    }
+}
+/**
+ * Specific error types.
+ */
+export class MemoryLimitError extends ExpressionError {
+}
+export class TimeoutError extends ExpressionError {
+}
+export class SecurityViolationError extends ExpressionError {
+}
+export class SyntaxError extends ExpressionError {
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/types/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../src/types/evaluator.ts"],"names":[],"mappings":"AAoNA,+EAA+E;AAC/E,uDAAuD;AACvD,EAAE;AACF,0DAA0D;AAC1D,wDAAwD;AACxD,+EAA+E;AAE/E;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAGjC;IAFR,YACC,OAAe,EACR,OAKN;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QAPR,YAAO,GAAP,OAAO,CAKb;QAGD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAC/B,CAAC;CACD;AAED;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,eAAe;CAAG;AACxD,MAAM,OAAO,YAAa,SAAQ,eAAe;CAAG;AACpD,MAAM,OAAO,sBAAuB,SAAQ,eAAe;CAAG;AAC9D,MAAM,OAAO,WAAY,SAAQ,eAAe;CAAG"}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Expression Runtime Types
+ *
+ * This module exports all TypeScript interfaces and types for the expression runtime.
+ */
+export type { RuntimeBridge, BridgeConfig } from './bridge';
+export type { RuntimeHostInterface, RuntimeGlobals, RuntimeConfig, LazyProxyConfig, } from './runtime';
+export { RuntimeError } from './runtime';
+export type { EvaluatorConfig, IExpressionEvaluator, WorkflowData, EvaluateOptions, ObservabilityProvider, MetricsAPI, TracesAPI, Span, LogsAPI, TournamentHooks, } from './evaluator';
+export { ExpressionError, MemoryLimitError, TimeoutError, SecurityViolationError, SyntaxError, } from './evaluator';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG5D,YAAY,EACX,oBAAoB,EACpB,cAAc,EACd,aAAa,EACb,eAAe,GACf,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,YAAY,EACX,eAAe,EACf,oBAAoB,EACpB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,UAAU,EACV,SAAS,EACT,IAAI,EACJ,OAAO,EACP,eAAe,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,EACtB,WAAW,GACX,MAAM,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * Expression Runtime Types
+ *
+ * This module exports all TypeScript interfaces and types for the expression runtime.
+ */
+export { RuntimeError } from './runtime';
+export { ExpressionError, MemoryLimitError, TimeoutError, SecurityViolationError, SyntaxError, } from './evaluator';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAgBzC,OAAO,EACN,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,sBAAsB,EACtB,WAAW,GACX,MAAM,aAAa,CAAC"}

package/dist/types/runtime.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Runtime interface exposed to isolated context.
+ *
+ * This interface defines what the runtime code (running inside the isolated context)
+ * can call. The bridge implements these functions on the host side.
+ */
+export interface RuntimeHostInterface {
+    /**
+     * Get data from host by path (synchronous).
+     * Used by lazy loading proxies to fetch data on-demand.
+     *
+     * IMPORTANT: This is SYNCHRONOUS because JavaScript Proxy traps cannot be async.
+     * - IsolatedVmBridge: Uses ivm.Reference for true sync callbacks
+     * - WebWorkerBridge: Not supported - must pre-fetch all data
+     *
+     * @param path - Property path to fetch (e.g., "user.email", "items[0].json")
+     * @returns Value at the path, or undefined if not found
+     */
+    getDataSync(path: string): unknown;
+}
+/**
+ * Lazy-loading proxy for workflow data.
+ *
+ * At runtime, these appear as plain objects but are actually Proxy objects
+ * that fetch data on-demand from the host using getDataSync().
+ */
+type LazyDataProxy = Record<string, unknown>;
+/**
+ * Runtime globals available in isolated context.
+ *
+ * These are injected by the bridge when initializing the context.
+ */
+export interface RuntimeGlobals {
+    /**
+     * Host interface for calling back to host process.
+     */
+    __host: RuntimeHostInterface;
+    /**
+     * Workflow data proxy ($json, $item, etc.).
+     * Set by bridge before each execute() call.
+     */
+    /** Current item data (lazy-loaded proxy) */
+    $json: LazyDataProxy;
+    /** Alias for $json (lazy-loaded proxy) */
+    $: LazyDataProxy;
+    /** Get item by index (lazy-loaded) */
+    $item: (index: number, runIndex?: number) => LazyDataProxy;
+    /** Access to all items */
+    $input: {
+        all: () => Array<{
+            json: LazyDataProxy;
+        }>;
+        first: () => {
+            json: LazyDataProxy;
+        } | undefined;
+        last: () => {
+            json: LazyDataProxy;
+        } | undefined;
+        item: {
+            json: LazyDataProxy;
+        };
+    };
+    /**
+     * Standard libraries available in runtime.
+     */
+    _: typeof import('lodash');
+    DateTime: typeof import('luxon').DateTime;
+}
+/**
+ * Configuration for runtime initialization.
+ */
+export interface RuntimeConfig {
+    /**
+     * Enable debug logging in runtime.
+     * Default: false
+     */
+    debug?: boolean;
+    /**
+     * Custom timeout for data fetches.
+     * Default: 1000ms
+     */
+    dataFetchTimeout?: number;
+}
+/**
+ * Runtime error thrown inside isolated context.
+ *
+ * These errors are thrown by the runtime code when something goes wrong during
+ * expression evaluation. The bridge must catch these and translate them to the
+ * appropriate ExpressionError subclass (see evaluator.ts).
+ *
+ * Translation mapping:
+ * - code: 'MEMORY_LIMIT' → MemoryLimitError
+ * - code: 'TIMEOUT' → TimeoutError
+ * - code: 'SECURITY_VIOLATION' → SecurityViolationError
+ * - code: 'SYNTAX_ERROR' → SyntaxError
+ * - other → ExpressionError
+ */
+export declare class RuntimeError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Lazy proxy configuration.
+ */
+export interface LazyProxyConfig {
+    /**
+     * Host interface for fetching data.
+     */
+    host: RuntimeHostInterface;
+    /**
+     * Property path prefix (for nested proxies).
+     * Example: If this proxy represents $json.user, pathPrefix would be "user"
+     */
+    pathPrefix?: string;
+    /**
+     * Cache for fetched values to avoid repeated host calls.
+     */
+    cache?: Map<string, unknown>;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/types/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/types/runtime.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;;;;;OAUG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;GAKG;AACH,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,MAAM,EAAE,oBAAoB,CAAC;IAE7B;;;OAGG;IAEH,4CAA4C;IAC5C,KAAK,EAAE,aAAa,CAAC;IAErB,0CAA0C;IAC1C,CAAC,EAAE,aAAa,CAAC;IAEjB,sCAAsC;IACtC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC;IAE3D,0BAA0B;IAC1B,MAAM,EAAE;QACP,GAAG,EAAE,MAAM,KAAK,CAAC;YAAE,IAAI,EAAE,aAAa,CAAA;SAAE,CAAC,CAAC;QAC1C,KAAK,EAAE,MAAM;YAAE,IAAI,EAAE,aAAa,CAAA;SAAE,GAAG,SAAS,CAAC;QACjD,IAAI,EAAE,MAAM;YAAE,IAAI,EAAE,aAAa,CAAA;SAAE,GAAG,SAAS,CAAC;QAChD,IAAI,EAAE;YAAE,IAAI,EAAE,aAAa,CAAA;SAAE,CAAC;KAC9B,CAAC;IAEF;;OAEG;IACH,CAAC,EAAE,cAAc,QAAQ,CAAC,CAAC;IAC3B,QAAQ,EAAE,cAAc,OAAO,EAAE,QAAQ,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAG9B,IAAI,EAAE,MAAM;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFxC,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKzC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,IAAI,EAAE,oBAAoB,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7B"}

package/dist/types/runtime.js

@@ -0,0 +1,31 @@
+// ============================================================================
+// Phase 1.1: Runtime Interfaces (IMPLEMENT WITH BRIDGE)
+//
+// These interfaces define how the runtime (inside isolation) communicates
+// with the host. Implement these when building the runtime code.
+// ============================================================================
+/**
+ * Runtime error thrown inside isolated context.
+ *
+ * These errors are thrown by the runtime code when something goes wrong during
+ * expression evaluation. The bridge must catch these and translate them to the
+ * appropriate ExpressionError subclass (see evaluator.ts).
+ *
+ * Translation mapping:
+ * - code: 'MEMORY_LIMIT' → MemoryLimitError
+ * - code: 'TIMEOUT' → TimeoutError
+ * - code: 'SECURITY_VIOLATION' → SecurityViolationError
+ * - code: 'SYNTAX_ERROR' → SyntaxError
+ * - other → ExpressionError
+ */
+export class RuntimeError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'RuntimeError';
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/types/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/types/runtime.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wDAAwD;AACxD,EAAE;AACF,0EAA0E;AAC1E,iEAAiE;AACjE,+EAA+E;AAwF/E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAG9B;IACA;IAHR,YACC,OAAe,EACR,IAAY,EACZ,OAAiC;QAExC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAA0B;QAGxC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC5B,CAAC;CACD"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@n8n/expression-runtime",
+  "version": "0.2.0",
+  "description": "Secure, isolated expression evaluation runtime for n8n",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "n8n",
+    "expression",
+    "evaluation",
+    "isolated-vm",
+    "web-worker",
+    "security"
+  ],
+  "license": "SEE LICENSE IN LICENSE.md",
+  "dependencies": {
+    "js-base64": "3.7.2",
+    "jssha": "3.3.1",
+    "lodash": "4.17.23",
+    "luxon": "3.7.2",
+    "md5": "2.3.0",
+    "title-case": "3.0.3",
+    "transliteration": "2.3.5"
+  },
+  "devDependencies": {
+    "@types/lodash": "4.17.17",
+    "@types/luxon": "3.2.0",
+    "@types/md5": "^2.3.5",
+    "typescript": "5.9.2",
+    "vitest": "^3.1.3"
+  },
+  "files": [
+    "dist",
+    "ARCHITECTURE.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:dev": "vitest --watch --silent false",
+    "typecheck": "tsc --noEmit"
+  }
+}