@n8n/expression-runtime 0.31.1 → 0.33.0

package/ARCHITECTURE.md

@@ -1,10 +1,10 @@
 # Expression Runtime Architecture
 
-This package provides a secure, isolated expression evaluation runtime that works across multiple execution environments (isolated-vm, Web Workers, and task runners).
+This package provides a secure, isolated expression evaluation runtime that works across multiple execution environments (isolated-vm, QuickJS in WASM, and task runners).
 
 ## Design Goals
 
-1. **Environment Agnostic**: Single codebase that works in Node.js (isolated-vm), browsers (Web Workers), and task runner processes
+1. **Environment Agnostic**: Single codebase that works in Node.js (isolated-vm), browsers (QuickJS in WASM), and task runner processes
 2. **Security**: Expressions run in isolated contexts with memory limits and timeouts
 3. **Performance**: Lazy data loading, code caching, and efficient data transfer
 4. **Observability**: Built-in metrics, traces, and logs
@@ -29,7 +29,7 @@ The architecture is split into three distinct layers:
 │  ┌────────────────▼───────────────────────────────┐     │
 │  │           Bridge (Layer 2)                     │     │
 │  │  - IsolatedVmBridge (Phase 1.1)                │     │
-│  │  - WebWorkerBridge (Phase 2+)                  │     │
+│  │  - QuickJsBridge (WASM)                        │     │
 │  │  - Task Runner Integration (TBD)               │     │
 │  └────────────────┬───────────────────────────────┘     │
 │                   │ IPC/Message Passing                 │
@@ -62,7 +62,7 @@ The architecture is split into three distinct layers:
 - **Libraries**: lodash, Luxon (bundled)
 - **No Node.js APIs**: Pure JavaScript only
 
-**Bundle**: IIFE format for isolated-vm, ESM for Web Workers
+**Bundle**: IIFE format for both isolated-vm and QuickJS
 
 ### Layer 2: Bridge (Host Process)
 
@@ -73,7 +73,7 @@ The architecture is split into three distinct layers:
 **Key Components**:
 - **RuntimeBridge Interface**: Abstract interface for all bridge implementations
 - **IsolatedVmBridge**: Uses isolated-vm API for Node.js backend (Phase 1.1)
-- **WebWorkerBridge**: Uses postMessage API for browser (Phase 2+)
+- **QuickJsBridge**: Uses quickjs-emscripten (WASM) for Node.js and the browser
 - **Task Runner Integration**: TBD - May use IsolatedVmBridge locally or direct evaluation (Phase 2+)
 
 **Responsibilities**:
@@ -175,24 +175,12 @@ class IsolatedVmBridge implements RuntimeBridge {
 }
 ```
 
-### WebWorkerBridge (Browser Frontend)
+### QuickJsBridge (Browser Frontend)
 
-Uses Web Workers for browser-based isolation:
-
-```typescript
-class WebWorkerBridge implements RuntimeBridge {
-  private worker: Worker;
-
-  async initialize(): Promise<void> {
-    this.worker = new Worker('/runtime.worker.js');
-    // Setup message handlers
-  }
-
-  async execute(code: string, dataId: string): Promise<unknown> {
-    // Implementation...
-  }
-}
-```
+The editor runs the same `QuickJsBridge` as Node.
+The browser has no filesystem, so the host passes the runtime bundle in with the
+`runtimeBundle` option. The vite stub in `packages/frontend/editor-ui/vite/` maps
+`@n8n/expression-runtime` to the real bridge for the browser build.
 
 ### Task Runner Integration (TBD - Phase 2+)
 
@@ -294,7 +282,7 @@ packages/@n8n/expression-runtime/
 **Limitation**: Lazy loading requires **synchronous** callbacks from runtime to host. This works for:
 - ✅ **isolated-vm**: Uses `ivm.Reference` for true synchronous callbacks
 - ✅ **Node.js vm**: Direct synchronous function calls
-- ❌ **Web Workers**: postMessage is always async (see Known Limitations below)
+- ✅ **QuickJS**: host functions are plain synchronous calls in the WASM context
 
 ### 3. Why Bundle the Runtime?
 
@@ -304,7 +292,7 @@ packages/@n8n/expression-runtime/
 
 ### 4. Why Abstract Bridge?
 
-**Future-Proofing**: Frontend will use Web Workers. Backend uses isolated-vm. Abstract bridge allows adding new environments without changing other layers.
+**Portability**: The backend uses isolated-vm. The browser uses QuickJS in WASM. The abstract bridge allows adding new environments without changing other layers.
 
 **Testing**: Integration tests use `IsolatedVmBridge` directly (see `src/__tests__/integration.test.ts`).
 
@@ -334,23 +322,9 @@ const proxy = new Proxy({}, {
    - Direct synchronous function calls
    - Full lazy loading support (used for testing)
 
-3. **Web Workers** ❌
-   - `postMessage` is always async
-   - **Phase 1 Limitation**: No lazy loading, must pre-fetch all data before evaluation
-   - **Future Enhancement (Phase 2+)**: Explore `SharedArrayBuffer` + `Atomics` for synchronous data access
-
-### Web Worker Support Roadmap
-
-**Phase 1** (Initial implementation):
-- WebWorkerBridge will pre-fetch all workflow data
-- Transfer complete data object to worker before evaluation
-- Works for small/medium datasets (< 50MB)
-- No lazy loading benefit
-
-**Phase 2+** (Future enhancement):
-- Investigate `SharedArrayBuffer` + `Atomics` for sync access
-- Or accept pre-fetching as the Web Worker approach
-- Decision based on real-world usage patterns
+3. **QuickJS (WASM)** ✅
+   - Host functions are plain synchronous calls in the QuickJS context
+   - Full lazy loading support, in Node.js and in the browser
 
 ### Security Boundaries
 
@@ -422,5 +396,5 @@ See observability package documentation for details.
 ## References
 
 - [isolated-vm GitHub](https://github.com/laverdet/isolated-vm)
-- [Web Workers MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
+- [quickjs-emscripten GitHub](https://github.com/justjake/quickjs-emscripten)
 - [n8n workflow package](../workflow/)

package/README.md

@@ -11,10 +11,10 @@ Secure, isolated expression evaluation runtime for n8n workflows.
 - ✅ `IsolatedVmBridge`: V8 isolate management via `isolated-vm`
 - ✅ `ExpressionEvaluator`: tournament integration, expression code caching, isolate pooling
 - ✅ Workflow integration — default engine; `N8N_EXPRESSION_ENGINE=legacy` opts out
+- ✅ Editor support — the `QuickJsBridge` runs in the browser; `N8N_EXPRESSION_ENGINE_FRONTEND=quickjs` opts in
 - ✅ Observability (metrics, traces, logs) wired up in `packages/cli`
 
 Coming later:
-- 🚧 Web Worker support (Phase 2+)
 - 🚧 Performance optimizations (Phase 3)
 
 ## Overview
@@ -23,9 +23,9 @@ This package provides a secure runtime for evaluating expressions in isolated co
 
 Currently supports:
 - **Node.js Backend**: Uses `isolated-vm` for V8 isolate-based isolation with lazy data loading
+- **Browser Frontend**: Uses `QuickJsBridge` (QuickJS compiled to WASM); `N8N_EXPRESSION_ENGINE_FRONTEND=quickjs` opts in
 
 Future support (Phase 2+):
-- **Browser Frontend**: Will use Web Workers for browser-based isolation
 - **Task Runners**: Will use IPC for separate process isolation
 
 ## Features
@@ -170,7 +170,7 @@ interface RuntimeBridge {
   - Synchronous callbacks via ivm.Reference
   - Security wrappers (SafeObject, SafeError)
   - `E()` error handler for tournament-generated try-catch code
-- **WebWorkerBridge**: 🚧 For browser frontend (Web Workers) - Phase 2+
+- **QuickJsBridge**: ✅ QuickJS in WASM, for the Node.js backend and the browser frontend
 - **Task Runner Integration**: 🚧 TBD - May use IsolatedVmBridge locally or direct evaluation - Phase 2+
 
 ## Configuration
@@ -195,6 +195,9 @@ In n8n, the evaluator is configured via `ExpressionEngineConfig` (`@n8n/config`)
 # Engine selection ('vm' is the default; 'legacy' opts out of isolation)
 N8N_EXPRESSION_ENGINE=vm
 
+# Editor engine selection ('legacy' is the default; 'quickjs' runs the WASM engine in the browser)
+N8N_EXPRESSION_ENGINE_FRONTEND=legacy
+
 # Isolate pool and code cache
 N8N_EXPRESSION_ENGINE_POOL_SIZE=1
 N8N_EXPRESSION_ENGINE_MAX_CODE_CACHE_SIZE=1024