bunqueue 2.6.116 → 2.7.1

package/README.md

@@ -481,6 +481,91 @@ process.on('SIGINT', async () => {
 
 ---
 
+## Workflow Engine
+
+Orchestrate multi-step business processes with branching, saga compensation, and human-in-the-loop signals. Built on top of bunqueue — no new infrastructure.
+
+```typescript
+import { Workflow, Engine } from 'bunqueue/workflow';
+
+const orderFlow = new Workflow('order-pipeline')
+  .step('validate', async (ctx) => {
+    const { orderId, amount } = ctx.input as { orderId: string; amount: number };
+    if (amount <= 0) throw new Error('Invalid amount');
+    return { orderId };
+  })
+  .step('reserve-stock', async () => {
+    await inventory.reserve();
+    return { reserved: true };
+  }, {
+    compensate: async () => await inventory.release(), // Auto-rollback on failure
+  })
+  .step('charge', async () => {
+    return { txId: await payments.charge() };
+  }, {
+    compensate: async () => await payments.refund(),
+  })
+  .step('confirm', async (ctx) => {
+    const { txId } = ctx.steps['charge'] as { txId: string };
+    return { emailSent: true, txId };
+  });
+
+const engine = new Engine({ embedded: true });
+engine.register(orderFlow);
+await engine.start('order-pipeline', { orderId: 'ORD-1', amount: 99.99 });
+```
+
+**Features:**
+
+- **Saga pattern** — Compensation handlers run in reverse when a step fails
+- **Branching** — Route to different paths based on runtime conditions
+- **Parallel steps** — Run independent steps concurrently with `.parallel()`
+- **Human-in-the-loop** — `waitFor('event')` pauses execution, `engine.signal()` resumes it
+- **Signal timeout** — `waitFor('event', { timeout })` fails if signal doesn't arrive in time
+- **Step retry** — Automatic retry with exponential backoff and jitter
+- **Nested workflows** — Compose workflows with `.subWorkflow()`, child results passed back
+- **Observability** — Typed event emitter with 11 event types (`engine.on/onAny`)
+- **Cleanup & archival** — `engine.cleanup()` / `engine.archive()` for execution history management
+- **Step timeouts** — Prevent steps from running indefinitely
+- **Context passing** — Each step accesses input and all previous step results
+- **SQLite persistence** — Execution state survives restarts
+
+**vs Competitors:**
+
+| | **bunqueue** | **Temporal** | **Inngest** | **AWS Step Functions** |
+|---|---|---|---|---|
+| **Infrastructure** | None (embedded) | PostgreSQL + 7 services | Cloud-only | AWS-native |
+| **Saga compensation** | Built-in | Manual | Manual | Manual |
+| **Human-in-the-loop** | `.waitFor()` | Signals API | `step.waitForEvent()` | Callback tasks |
+| **Self-hosted** | Zero-config | Complex | No | No |
+| **Pricing** | Free (MIT) | Free / Cloud $$ | Per-execution | Per-transition |
+
+```typescript
+// Branching
+const flow = new Workflow('tiered')
+  .step('classify', async (ctx) => ({ tier: ctx.input.amount > 1000 ? 'vip' : 'basic' }))
+  .branch((ctx) => ctx.steps['classify'].tier)
+  .path('vip', (w) => w.step('vip-handler', async () => ({ discount: 20 })))
+  .path('basic', (w) => w.step('basic-handler', async () => ({ discount: 0 })))
+  .step('done', async () => ({ processed: true }));
+
+// Human-in-the-loop
+const approvalFlow = new Workflow('expense')
+  .step('submit', async (ctx) => ({ amount: ctx.input.amount }))
+  .waitFor('manager-approval')
+  .step('reimburse', async (ctx) => {
+    const decision = ctx.signals['manager-approval'] as { approved: boolean };
+    return { status: decision.approved ? 'paid' : 'rejected' };
+  });
+
+// Signal a waiting workflow
+await engine.signal(run.id, 'manager-approval', { approved: true });
+```
+
+[Workflow Engine docs →](https://bunqueue.dev/guide/workflow/)
+
+---
+
 <p align="center">
   <strong>bunqueue Dashboard</strong><br/>
   <sub>A visual interface for managing queues, jobs, workers and monitoring in real time. Currently in beta.</sub>
@@ -728,6 +813,7 @@ docker compose --profile monitoring up -d
 **[Read the full documentation →](https://bunqueue.dev/)**
 
 - [Quick Start](https://bunqueue.dev/guide/quickstart/)
+- [Workflow Engine](https://bunqueue.dev/guide/workflow/)
 - [MCP Server (AI Agents)](https://bunqueue.dev/guide/mcp/)
 - [Simple Mode](https://bunqueue.dev/guide/simple-mode/)
 - [Queue API](https://bunqueue.dev/guide/queue/)

package/dist/client/workflow/emitter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * WorkflowEmitter - Typed event system for workflow observability
+ */
+import type { WorkflowEventType, StepEvent, WorkflowLifecycleEvent, WorkflowEventListener, ExecutionState } from './types';
+export declare class WorkflowEmitter {
+    private readonly listeners;
+    private readonly globalListeners;
+    on(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    onAny(listener: WorkflowEventListener): this;
+    off(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    offAny(listener: WorkflowEventListener): this;
+    emitStep(type: 'step:started' | 'step:completed' | 'step:failed' | 'step:retry', executionId: string, workflowName: string, stepName: string, extra?: Partial<Omit<StepEvent, 'type' | 'executionId' | 'workflowName' | 'timestamp' | 'stepName'>>): void;
+    emitWorkflow(type: 'workflow:started' | 'workflow:completed' | 'workflow:failed' | 'workflow:compensating' | 'workflow:waiting', executionId: string, workflowName: string, state: ExecutionState, extra?: Partial<Omit<WorkflowLifecycleEvent, 'type' | 'executionId' | 'workflowName' | 'timestamp' | 'state'>>): void;
+    emitSignal(type: 'signal:received' | 'signal:timeout', executionId: string, workflowName: string, event: string, payload?: unknown): void;
+    removeAllListeners(): void;
+    private dispatch;
+}
+//# sourceMappingURL=emitter.d.ts.map

package/dist/client/workflow/emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../../src/client/workflow/emitter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,SAAS,EACT,sBAAsB,EAEtB,qBAAqB,EACrB,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4D;IACtF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAUlE,KAAK,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAK5C,GAAG,CAAC,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAKnE,MAAM,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAK7C,QAAQ,CACN,IAAI,EAAE,cAAc,GAAG,gBAAgB,GAAG,aAAa,GAAG,YAAY,EACtE,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,OAAO,CACb,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC,CACpF,GACA,IAAI;IAYP,YAAY,CACV,IAAI,EACA,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GACjB,uBAAuB,GACvB,kBAAkB,EACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,cAAc,EACrB,KAAK,CAAC,EAAE,OAAO,CACb,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,WAAW,GAAG,OAAO,CAAC,CAC9F,GACA,IAAI;IAYP,UAAU,CACR,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,EAC1C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,GAChB,IAAI;IAYP,kBAAkB,IAAI,IAAI;IAK1B,OAAO,CAAC,QAAQ;CAOjB"}

package/dist/client/workflow/emitter.js

@@ -0,0 +1,75 @@
+/**
+ * WorkflowEmitter - Typed event system for workflow observability
+ */
+export class WorkflowEmitter {
+    listeners = new Map();
+    globalListeners = new Set();
+    on(type, listener) {
+        let set = this.listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(type, set);
+        }
+        set.add(listener);
+        return this;
+    }
+    onAny(listener) {
+        this.globalListeners.add(listener);
+        return this;
+    }
+    off(type, listener) {
+        this.listeners.get(type)?.delete(listener);
+        return this;
+    }
+    offAny(listener) {
+        this.globalListeners.delete(listener);
+        return this;
+    }
+    emitStep(type, executionId, workflowName, stepName, extra) {
+        const event = {
+            type,
+            executionId,
+            workflowName,
+            timestamp: Date.now(),
+            stepName,
+            ...extra,
+        };
+        this.dispatch(type, event);
+    }
+    emitWorkflow(type, executionId, workflowName, state, extra) {
+        const event = {
+            type,
+            executionId,
+            workflowName,
+            timestamp: Date.now(),
+            state,
+            ...extra,
+        };
+        this.dispatch(type, event);
+    }
+    emitSignal(type, executionId, workflowName, event, payload) {
+        const evt = {
+            type,
+            executionId,
+            workflowName,
+            timestamp: Date.now(),
+            event,
+            payload,
+        };
+        this.dispatch(type, evt);
+    }
+    removeAllListeners() {
+        this.listeners.clear();
+        this.globalListeners.clear();
+    }
+    dispatch(type, event) {
+        const typed = this.listeners.get(type);
+        if (typed) {
+            for (const fn of typed)
+                fn(event);
+        }
+        for (const fn of this.globalListeners)
+            fn(event);
+    }
+}
+//# sourceMappingURL=emitter.js.map

package/dist/client/workflow/emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.js","sourceRoot":"","sources":["../../../src/client/workflow/emitter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,OAAO,eAAe;IACT,SAAS,GAAG,IAAI,GAAG,EAAiD,CAAC;IACrE,eAAe,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEpE,EAAE,CAAC,IAAuB,EAAE,QAA+B;QACzD,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChC,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,QAA+B;QACnC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAuB,EAAE,QAA+B;QAC1D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,QAA+B;QACpC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,QAAQ,CACN,IAAsE,EACtE,WAAmB,EACnB,YAAoB,EACpB,QAAgB,EAChB,KAEC;QAED,MAAM,KAAK,GAAc;YACvB,IAAI;YACJ,WAAW;YACX,YAAY;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,QAAQ;YACR,GAAG,KAAK;SACT,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,YAAY,CACV,IAKsB,EACtB,WAAmB,EACnB,YAAoB,EACpB,KAAqB,EACrB,KAEC;QAED,MAAM,KAAK,GAA2B;YACpC,IAAI;YACJ,WAAW;YACX,YAAY;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,KAAK;YACL,GAAG,KAAK;SACT,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,UAAU,CACR,IAA0C,EAC1C,WAAmB,EACnB,YAAoB,EACpB,KAAa,EACb,OAAiB;QAEjB,MAAM,GAAG,GAAgB;YACvB,IAAI;YACJ,WAAW;YACX,YAAY;YACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,KAAK;YACL,OAAO;SACR,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED,kBAAkB;QAChB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;IAC/B,CAAC;IAEO,QAAQ,CAAC,IAAuB,EAAE,KAAoB;QAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,MAAM,EAAE,IAAI,KAAK;gBAAE,EAAE,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,eAAe;YAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/client/workflow/engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Engine - Public facade for the workflow engine
+ * Manages lifecycle of internal Queue, Worker, and Store.
+ */
+import type { Workflow } from './workflow';
+import type { EngineOptions, RunHandle, Execution, ExecutionState, WorkflowEventType, WorkflowEventListener } from './types';
+export declare class Engine {
+    private readonly queue;
+    private readonly worker;
+    private readonly store;
+    private readonly executor;
+    private readonly emitter;
+    constructor(opts?: EngineOptions);
+    /** Register a workflow definition */
+    register(workflow: Workflow): this;
+    /** Start a new workflow execution */
+    start(workflowName: string, input?: unknown): Promise<RunHandle>;
+    /** Get execution state by ID */
+    getExecution(id: string): Execution | null;
+    /** List executions with optional filters */
+    listExecutions(workflowName?: string, state?: ExecutionState): Execution[];
+    /** Send a signal to a waiting execution */
+    signal(executionId: string, event: string, payload?: unknown): Promise<void>;
+    /** Subscribe to a specific workflow event type */
+    on(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    /** Subscribe to all workflow events */
+    onAny(listener: WorkflowEventListener): this;
+    /** Unsubscribe from a specific event type */
+    off(type: WorkflowEventType, listener: WorkflowEventListener): this;
+    /** Unsubscribe a catch-all listener */
+    offAny(listener: WorkflowEventListener): this;
+    /** Remove old completed/failed executions */
+    cleanup(maxAgeMs: number, states?: ExecutionState[]): number;
+    /** Archive old executions to a separate table */
+    archive(maxAgeMs: number, states?: ExecutionState[]): number;
+    /** Get archived execution count */
+    getArchivedCount(): number;
+    /** Shut down the engine */
+    close(force?: boolean): Promise<void>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/client/workflow/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/client/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,SAAS,EACT,cAAc,EAEd,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAIjB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,IAAI,GAAE,aAAkB;IAiCpC,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAKlC,qCAAqC;IAC/B,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAItE,gCAAgC;IAChC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI1C,4CAA4C;IAC5C,cAAc,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,SAAS,EAAE;IAI1E,2CAA2C;IACrC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlF,kDAAkD;IAClD,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAKlE,uCAAuC;IACvC,KAAK,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAK5C,6CAA6C;IAC7C,GAAG,CAAC,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAKnE,uCAAuC;IACvC,MAAM,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAO7C,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,MAAM;IAI5D,iDAAiD;IACjD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,GAAG,MAAM;IAI5D,mCAAmC;IACnC,gBAAgB,IAAI,MAAM;IAI1B,2BAA2B;IACrB,KAAK,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAM1C"}

package/dist/client/workflow/engine.js

@@ -0,0 +1,103 @@
+/**
+ * Engine - Public facade for the workflow engine
+ * Manages lifecycle of internal Queue, Worker, and Store.
+ */
+import { Queue } from '../queue/queue';
+import { Worker } from '../worker/worker';
+import { WorkflowStore } from './store';
+import { WorkflowExecutor } from './executor';
+import { WorkflowEmitter } from './emitter';
+const DEFAULT_QUEUE_NAME = '__wf:steps';
+export class Engine {
+    queue;
+    worker;
+    store;
+    executor;
+    emitter;
+    constructor(opts = {}) {
+        const queueName = opts.queueName ?? DEFAULT_QUEUE_NAME;
+        this.queue = new Queue(queueName, {
+            connection: opts.connection,
+            embedded: opts.embedded,
+            dataPath: opts.dataPath,
+        });
+        this.store = new WorkflowStore(opts.dataPath);
+        this.emitter = new WorkflowEmitter();
+        if (opts.onEvent) {
+            this.emitter.onAny(opts.onEvent);
+        }
+        this.executor = new WorkflowExecutor(this.store, this.queue, this.emitter);
+        this.worker = new Worker(queueName, async (job) => {
+            const data = job.data;
+            return this.executor.processStep(data);
+        }, {
+            connection: opts.connection,
+            embedded: opts.embedded,
+            dataPath: opts.dataPath,
+            concurrency: opts.concurrency ?? 5,
+        });
+    }
+    /** Register a workflow definition */
+    register(workflow) {
+        this.executor.register(workflow);
+        return this;
+    }
+    /** Start a new workflow execution */
+    async start(workflowName, input) {
+        return this.executor.start(workflowName, input);
+    }
+    /** Get execution state by ID */
+    getExecution(id) {
+        return this.executor.getExecution(id);
+    }
+    /** List executions with optional filters */
+    listExecutions(workflowName, state) {
+        return this.executor.listExecutions(workflowName, state);
+    }
+    /** Send a signal to a waiting execution */
+    async signal(executionId, event, payload) {
+        return this.executor.signal(executionId, event, payload);
+    }
+    // ============ Observability ============
+    /** Subscribe to a specific workflow event type */
+    on(type, listener) {
+        this.emitter.on(type, listener);
+        return this;
+    }
+    /** Subscribe to all workflow events */
+    onAny(listener) {
+        this.emitter.onAny(listener);
+        return this;
+    }
+    /** Unsubscribe from a specific event type */
+    off(type, listener) {
+        this.emitter.off(type, listener);
+        return this;
+    }
+    /** Unsubscribe a catch-all listener */
+    offAny(listener) {
+        this.emitter.offAny(listener);
+        return this;
+    }
+    // ============ Cleanup ============
+    /** Remove old completed/failed executions */
+    cleanup(maxAgeMs, states) {
+        return this.store.cleanup(maxAgeMs, states);
+    }
+    /** Archive old executions to a separate table */
+    archive(maxAgeMs, states) {
+        return this.store.archive(maxAgeMs, states);
+    }
+    /** Get archived execution count */
+    getArchivedCount() {
+        return this.store.getArchivedCount();
+    }
+    /** Shut down the engine */
+    async close(force = false) {
+        await this.worker.close(force);
+        this.queue.close();
+        this.store.close();
+        this.emitter.removeAllListeners();
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/client/workflow/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/client/workflow/engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAY5C,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAExC,MAAM,OAAO,MAAM;IACA,KAAK,CAAQ;IACb,MAAM,CAAS;IACf,KAAK,CAAgB;IACrB,QAAQ,CAAmB;IAC3B,OAAO,CAAkB;IAE1C,YAAY,OAAsB,EAAE;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;QAEvD,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE;YAChC,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,EAAE,CAAC;QAErC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAE3E,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB,SAAS,EACT,KAAK,EAAE,GAAG,EAAE,EAAE;YACZ,MAAM,IAAI,GAAG,GAAG,CAAC,IAA8B,CAAC;YAChD,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC,EACD;YACE,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC;SACnC,CACF,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,QAAQ,CAAC,QAAkB;QACzB,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,YAAoB,EAAE,KAAe;QAC/C,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IAED,gCAAgC;IAChC,YAAY,CAAC,EAAU;QACrB,OAAO,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,4CAA4C;IAC5C,cAAc,CAAC,YAAqB,EAAE,KAAsB;QAC1D,OAAO,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC;IAED,2CAA2C;IAC3C,KAAK,CAAC,MAAM,CAAC,WAAmB,EAAE,KAAa,EAAE,OAAiB;QAChE,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED,0CAA0C;IAE1C,kDAAkD;IAClD,EAAE,CAAC,IAAuB,EAAE,QAA+B;QACzD,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uCAAuC;IACvC,KAAK,CAAC,QAA+B;QACnC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,GAAG,CAAC,IAAuB,EAAE,QAA+B;QAC1D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uCAAuC;IACvC,MAAM,CAAC,QAA+B;QACpC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oCAAoC;IAEpC,6CAA6C;IAC7C,OAAO,CAAC,QAAgB,EAAE,MAAyB;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,iDAAiD;IACjD,OAAO,CAAC,QAAgB,EAAE,MAAyB;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,mCAAmC;IACnC,gBAAgB;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC;IACvC,CAAC;IAED,2BAA2B;IAC3B,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK;QACvB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IACpC,CAAC;CACF"}

package/dist/client/workflow/executor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WorkflowExecutor - Core execution logic
+ * Processes steps as bunqueue jobs, handles transitions, branching, compensation.
+ */
+import type { Queue } from '../queue/queue';
+import type { Workflow } from './workflow';
+import type { WorkflowStore } from './store';
+import type { WorkflowEmitter } from './emitter';
+import type { Execution, StepJobData, RunHandle } from './types';
+export declare class WorkflowExecutor {
+    private readonly store;
+    private readonly queue;
+    private readonly emitter;
+    private readonly workflows;
+    private readonly timeoutTimers;
+    constructor(store: WorkflowStore, queue: Queue, emitter?: WorkflowEmitter | null);
+    register(workflow: Workflow): void;
+    start(workflowName: string, input: unknown): Promise<RunHandle>;
+    processStep(data: StepJobData): Promise<unknown>;
+    signal(executionId: string, event: string, payload: unknown): Promise<void>;
+    getExecution(id: string): Execution | null;
+    listExecutions(workflowName?: string, state?: Execution['state']): Execution[];
+    private executeNode;
+    private runStep;
+    private runBranch;
+    private runParallel;
+    private runSubWorkflow;
+    private runWaitFor;
+    private advance;
+    private enqueue;
+    private scheduleTimeoutCheck;
+    private compensate;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/client/workflow/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/client/workflow/executor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAgC,MAAM,SAAS,CAAC;AAe/F,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoD;gBAG/D,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,KAAK,EACZ,OAAO,GAAE,eAAe,GAAG,IAAW;IAGzD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAS5B,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAwB/D,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BhD,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjF,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI1C,cAAc,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,SAAS,EAAE;YAMhE,WAAW;YAaX,OAAO;YAQP,SAAS;YAkBT,WAAW;YAYX,cAAc;YAiBd,UAAU;YA6CV,OAAO;YAYP,OAAO;IASrB,OAAO,CAAC,oBAAoB;YASd,UAAU;CAwBzB"}

package/dist/client/workflow/executor.js

@@ -0,0 +1,241 @@
+/**
+ * WorkflowExecutor - Core execution logic
+ * Processes steps as bunqueue jobs, handles transitions, branching, compensation.
+ */
+import { executeStepWithRetry, executeParallelSteps, executeSubWorkflow, findStepDef, buildContext, } from './runner';
+class WaitForSignalError extends Error {
+    event;
+    constructor(event) {
+        super(`Waiting for signal: ${event}`);
+        this.event = event;
+    }
+}
+export class WorkflowExecutor {
+    store;
+    queue;
+    emitter;
+    workflows = new Map();
+    timeoutTimers = new Map();
+    constructor(store, queue, emitter = null) {
+        this.store = store;
+        this.queue = queue;
+        this.emitter = emitter;
+    }
+    register(workflow) {
+        const names = workflow.getStepNames();
+        const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+        if (dupes.length > 0) {
+            throw new Error(`Duplicate step names in "${workflow.name}": ${dupes.join(', ')}`);
+        }
+        this.workflows.set(workflow.name, workflow);
+    }
+    async start(workflowName, input) {
+        const wf = this.workflows.get(workflowName);
+        if (!wf)
+            throw new Error(`Workflow "${workflowName}" not registered`);
+        if (wf.nodes.length === 0)
+            throw new Error(`Workflow "${workflowName}" has no steps`);
+        const now = Date.now();
+        const exec = {
+            id: `wf_${now}_${Math.random().toString(36).slice(2, 10)}`,
+            workflowName,
+            state: 'running',
+            input,
+            steps: {},
+            currentNodeIndex: 0,
+            signals: {},
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.save(exec);
+        this.emitter?.emitWorkflow('workflow:started', exec.id, workflowName, 'running', { input });
+        await this.enqueue(exec);
+        return { id: exec.id, workflowName };
+    }
+    async processStep(data) {
+        const exec = this.store.get(data.executionId);
+        if (!exec || (exec.state !== 'running' && exec.state !== 'waiting'))
+            return null;
+        // If waiting, set back to running for timeout re-check
+        if (exec.state === 'waiting')
+            exec.state = 'running';
+        const wf = this.workflows.get(exec.workflowName);
+        if (!wf)
+            throw new Error(`Workflow "${exec.workflowName}" not registered`);
+        const node = wf.nodes[data.nodeIndex];
+        if (!node) {
+            exec.state = 'completed';
+            this.store.update(exec);
+            this.emitter?.emitWorkflow('workflow:completed', exec.id, exec.workflowName, 'completed');
+            return null;
+        }
+        try {
+            await this.executeNode(exec, node, data.nodeIndex, wf);
+        }
+        catch (err) {
+            if (err instanceof WaitForSignalError)
+                return null;
+            exec.state = 'failed';
+            this.store.update(exec);
+            this.emitter?.emitWorkflow('workflow:failed', exec.id, exec.workflowName, 'failed');
+            await this.compensate(exec, wf);
+            throw err;
+        }
+        return null;
+    }
+    async signal(executionId, event, payload) {
+        const exec = this.store.get(executionId);
+        if (!exec)
+            throw new Error(`Execution "${executionId}" not found`);
+        // Cancel any pending timeout timer for this execution
+        const timer = this.timeoutTimers.get(executionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.timeoutTimers.delete(executionId);
+        }
+        exec.signals[event] = payload;
+        exec.state = 'running';
+        this.store.update(exec);
+        this.emitter?.emitSignal('signal:received', exec.id, exec.workflowName, event, payload);
+        await this.enqueue(exec);
+    }
+    getExecution(id) {
+        return this.store.get(id);
+    }
+    listExecutions(workflowName, state) {
+        return this.store.list(workflowName, state);
+    }
+    // ============ Node dispatch ============
+    async executeNode(exec, node, idx, wf) {
+        if (node.type === 'step')
+            await this.runStep(exec, node.def, idx, wf);
+        else if (node.type === 'branch')
+            await this.runBranch(exec, node, idx, wf);
+        else if (node.type === 'parallel')
+            await this.runParallel(exec, node, idx, wf);
+        else if (node.type === 'subWorkflow')
+            await this.runSubWorkflow(exec, node, idx, wf);
+        else
+            await this.runWaitFor(exec, node, idx, wf);
+    }
+    async runStep(exec, def, idx, wf) {
+        const ctx = buildContext(exec);
+        await executeStepWithRetry(def, ctx, exec, this.emitter, (e) => {
+            this.store.update(e);
+        });
+        await this.advance(exec, idx + 1, wf);
+    }
+    async runBranch(exec, node, idx, wf) {
+        const pathName = node.def.condition(buildContext(exec));
+        const pathSteps = node.def.paths.get(pathName);
+        if (pathSteps && pathSteps.length > 0) {
+            for (const step of pathSteps) {
+                await executeStepWithRetry(step, buildContext(exec), exec, this.emitter, (e) => {
+                    this.store.update(e);
+                });
+            }
+        }
+        await this.advance(exec, idx + 1, wf);
+    }
+    async runParallel(exec, node, idx, wf) {
+        await executeParallelSteps(node.def.steps, buildContext(exec), exec, this.emitter, (e) => {
+            this.store.update(e);
+        });
+        await this.advance(exec, idx + 1, wf);
+    }
+    async runSubWorkflow(exec, node, idx, wf) {
+        const subInput = node.inputMapper(buildContext(exec));
+        const result = await executeSubWorkflow(node.name, subInput, (name, input) => this.start(name, input), (id) => this.store.get(id));
+        exec.steps[`sub:${node.name}`] = { status: 'completed', result, completedAt: Date.now() };
+        await this.advance(exec, idx + 1, wf);
+    }
+    async runWaitFor(exec, node, idx, wf) {
+        if (exec.signals[node.event] !== undefined) {
+            await this.advance(exec, idx + 1, wf);
+            return;
+        }
+        const waitKey = `__waitFor:${node.event}`;
+        if (node.timeout !== undefined) {
+            const existing = exec.steps[waitKey];
+            const waitingSince = existing?.startedAt ?? Date.now();
+            if (!existing) {
+                exec.steps[waitKey] = { status: 'running', startedAt: waitingSince };
+            }
+            if (Date.now() - waitingSince >= node.timeout) {
+                this.emitter?.emitSignal('signal:timeout', exec.id, exec.workflowName, node.event);
+                exec.steps[waitKey] = {
+                    status: 'failed',
+                    error: `Signal "${node.event}" timed out after ${node.timeout}ms`,
+                    startedAt: waitingSince,
+                    completedAt: Date.now(),
+                };
+                exec.state = 'failed';
+                this.store.update(exec);
+                await this.compensate(exec, wf);
+                throw new Error(`Signal "${node.event}" timed out`);
+            }
+            this.store.update(exec);
+            // Schedule a timer to re-check after timeout
+            const remaining = node.timeout - (Date.now() - waitingSince);
+            this.scheduleTimeoutCheck(exec.id, exec.workflowName, exec.currentNodeIndex, remaining);
+        }
+        exec.state = 'waiting';
+        this.store.update(exec);
+        this.emitter?.emitWorkflow('workflow:waiting', exec.id, exec.workflowName, 'waiting');
+        throw new WaitForSignalError(node.event);
+    }
+    // ============ Helpers ============
+    async advance(exec, nextIdx, wf) {
+        exec.currentNodeIndex = nextIdx;
+        this.store.update(exec);
+        if (nextIdx >= wf.nodes.length) {
+            exec.state = 'completed';
+            this.store.update(exec);
+            this.emitter?.emitWorkflow('workflow:completed', exec.id, exec.workflowName, 'completed');
+        }
+        else {
+            await this.enqueue(exec);
+        }
+    }
+    async enqueue(exec) {
+        const jobData = {
+            executionId: exec.id,
+            workflowName: exec.workflowName,
+            nodeIndex: exec.currentNodeIndex,
+        };
+        await this.queue.add('wf:step', jobData);
+    }
+    scheduleTimeoutCheck(execId, workflowName, nodeIdx, ms) {
+        const timer = setTimeout(() => {
+            this.timeoutTimers.delete(execId);
+            const jobData = { executionId: execId, workflowName, nodeIndex: nodeIdx };
+            this.queue.add('wf:step', jobData).catch(() => { }); // Queue may be closed
+        }, ms);
+        this.timeoutTimers.set(execId, timer);
+    }
+    async compensate(exec, wf) {
+        const completed = Object.entries(exec.steps)
+            .filter(([name, s]) => s.status === 'completed' && !name.startsWith('__'))
+            .reverse();
+        if (completed.length === 0)
+            return;
+        exec.state = 'compensating';
+        this.store.update(exec);
+        this.emitter?.emitWorkflow('workflow:compensating', exec.id, exec.workflowName, 'compensating');
+        const ctx = buildContext(exec);
+        for (const [name] of completed) {
+            const def = findStepDef(wf, name);
+            if (def?.compensate) {
+                try {
+                    await def.compensate(ctx);
+                }
+                catch {
+                    // Compensation errors don't stop the chain
+                }
+            }
+        }
+        exec.state = 'failed';
+        this.store.update(exec);
+    }
+}
+//# sourceMappingURL=executor.js.map