@bpmnkit/engine 0.1.7

package/README.md

@@ -0,0 +1,130 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/bpmn-sdk/monorepo/main/doc/logos/logo-2-gateway.svg" width="72" height="72" alt="BPMN Kit logo">
+  <h1>@bpmnkit/engine</h1>
+  <p>Lightweight BPMN 2.0 process execution engine for browsers and Node.js — zero dependencies</p>
+
+  [![npm](https://img.shields.io/npm/v/@bpmnkit/engine?style=flat-square&color=6244d7)](https://www.npmjs.com/package/@bpmnkit/engine)
+  [![license](https://img.shields.io/npm/l/@bpmnkit/engine?style=flat-square)](https://github.com/bpmnkit/monorepo/blob/main/LICENSE)
+  [![typescript](https://img.shields.io/badge/TypeScript-strict-6244d7?style=flat-square&logo=typescript&logoColor=white)](https://github.com/bpmnkit/monorepo)
+
+  [Documentation](https://bpmn-sdk-docs.pages.dev) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/engine/CHANGELOG.md)
+</div>
+
+---
+
+## Overview
+
+`@bpmnkit/engine` simulates BPMN 2.0 process execution. Deploy a diagram, start instances, track active elements, evaluate DMN decisions, and step through execution — all without a Camunda cluster.
+
+Perfect for: workflow testing, visual debugging, interactive demos, offline simulation, and process-driven UI flows.
+
+## Features
+
+- **Full control flow** — exclusive, parallel, inclusive, event-based, complex gateways
+- **Variable scopes** — hierarchical scope chain; FEEL expression evaluation for conditions/mappings
+- **All event types** — message, signal, timer (ISO 8601 duration/date/cycle), error, escalation, compensation
+- **Boundary events** — interrupting and non-interrupting error, timer, compensation
+- **Sub-processes** — embedded, call activity (process invocation by ID)
+- **DMN decisions** — inline decision table evaluation via `@bpmnkit/feel`
+- **Job workers** — register handlers for service tasks by job type
+- **Step-by-step** — `beforeComplete` hook pauses between elements for debugging UIs
+- **Zero dependencies** — browser + Node.js, no server required
+
+## Installation
+
+```sh
+npm install @bpmnkit/engine
+```
+
+## Quick Start
+
+```typescript
+import { Engine } from "@bpmnkit/engine"
+
+const engine = new Engine()
+
+// Deploy a BPMN process
+engine.deploy({ bpmn: xml })
+
+// Register job workers
+engine.registerJobWorker("payment-service", async (job) => {
+  const result = await processPayment(job.variables)
+  return { success: result.ok }
+})
+
+// Start an instance
+const instance = engine.start("order-process", {
+  orderId: "ORD-001",
+  amount: 99.99,
+})
+
+// Track execution
+instance.onChange((state) => {
+  console.log("Active:", state.activeElements)
+  console.log("Vars:", state.variables_snapshot)
+})
+
+// Wait for completion
+await new Promise((resolve) => {
+  instance.onChange((state) => {
+    if (state.state === "completed" || state.state === "terminated") resolve(undefined)
+  })
+})
+```
+
+## Step-by-step execution
+
+```typescript
+const steps: Array<() => void> = []
+
+const instance = engine.start("my-process", {}, {
+  beforeComplete: (elementId) =>
+    new Promise((resolve) => {
+      console.log("Paused at:", elementId)
+      steps.push(resolve)  // advance by calling steps.pop()()
+    }),
+})
+```
+
+## API Reference
+
+### `Engine`
+
+| Method | Description |
+|--------|-------------|
+| `deploy({ bpmn, forms?, decisions? })` | Register BPMN (+ optional DMN/form assets) |
+| `start(processId, variables?, options?)` | Start a new instance; returns `ProcessInstance` |
+| `registerJobWorker(type, handler)` | Handle service tasks with a given job type |
+| `getDeployedProcesses()` | List all deployed process IDs |
+
+### `ProcessInstance`
+
+| Member | Description |
+|--------|-------------|
+| `state` | `"running" \| "completed" \| "terminated" \| "failed"` |
+| `activeElements` | IDs of currently active flow nodes |
+| `variables_snapshot` | Flat snapshot of current variable scope |
+| `onChange(cb)` | Subscribe to state changes |
+| `cancel()` | Terminate the instance |
+| `deliverMessage(name, variables?)` | Correlate a message catch event |
+| `beforeComplete?` | Optional step hook (set after `start()`) |
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@bpmnkit/core`](https://www.npmjs.com/package/@bpmnkit/core) | BPMN/DMN/Form parser, builder, layout engine |
+| [`@bpmnkit/canvas`](https://www.npmjs.com/package/@bpmnkit/canvas) | Zero-dependency SVG BPMN viewer |
+| [`@bpmnkit/editor`](https://www.npmjs.com/package/@bpmnkit/editor) | Full-featured interactive BPMN editor |
+| [`@bpmnkit/feel`](https://www.npmjs.com/package/@bpmnkit/feel) | FEEL expression language parser & evaluator |
+| [`@bpmnkit/plugins`](https://www.npmjs.com/package/@bpmnkit/plugins) | 22 composable canvas plugins |
+| [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
+| [`@bpmnkit/ascii`](https://www.npmjs.com/package/@bpmnkit/ascii) | Render BPMN diagrams as Unicode ASCII art |
+| [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
+| [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring & operations frontend for Camunda clusters |
+
+## License
+
+[MIT](https://github.com/bpmnkit/monorepo/blob/main/LICENSE) © bpmn-sdk

package/dist/dmn.d.ts

@@ -0,0 +1,7 @@
+import type { DmnDecision } from "@bpmnkit/core";
+/**
+ * Evaluate a DMN decision table against the provided variables.
+ * Returns the result per the table's hit policy.
+ */
+export declare function evaluateDecision(decision: DmnDecision, vars: Record<string, unknown>): unknown;
+//# sourceMappingURL=dmn.d.ts.map

package/dist/dmn.js

@@ -0,0 +1,115 @@
+import { evaluate, evaluateUnaryTests, parseExpression, parseUnaryTests } from "@bpmnkit/feel";
+/**
+ * Evaluate a DMN decision table against the provided variables.
+ * Returns the result per the table's hit policy.
+ */
+export function evaluateDecision(decision, vars) {
+    const table = decision.decisionTable;
+    if (table === undefined)
+        return null;
+    const hitPolicy = table.hitPolicy ?? "UNIQUE";
+    const matchedOutputs = [];
+    for (const rule of table.rules) {
+        if (ruleMatches(table.inputs, rule.inputEntries, vars)) {
+            const output = {};
+            for (let i = 0; i < table.outputs.length; i++) {
+                const col = table.outputs[i];
+                const entry = rule.outputEntries[i];
+                if (col === undefined || entry === undefined)
+                    continue;
+                const colName = col.name ?? col.label ?? col.id;
+                output[colName] = evalOutputEntry(entry.text, vars);
+            }
+            matchedOutputs.push(output);
+            if (hitPolicy === "FIRST")
+                break;
+        }
+    }
+    return buildResult(hitPolicy, table.aggregation, matchedOutputs, table.outputs.length);
+}
+function ruleMatches(inputs, inputEntries, vars) {
+    const feelVars = vars;
+    for (let i = 0; i < inputs.length; i++) {
+        const col = inputs[i];
+        const entry = inputEntries[i];
+        if (col === undefined || entry === undefined)
+            continue;
+        if (entry.text.trim() === "")
+            continue; // empty = "any"
+        const inputExpr = col.inputExpression.text ?? "";
+        const inputValue = inputExpr.trim() === "" ? null : evalExpression(inputExpr, vars);
+        const parsed = parseUnaryTests(entry.text);
+        if (parsed.ast === null)
+            continue;
+        if (!evaluateUnaryTests(parsed.ast, inputValue, { vars: feelVars }))
+            return false;
+    }
+    return true;
+}
+function evalExpression(expr, vars) {
+    const parsed = parseExpression(expr.trim());
+    if (parsed.ast === null)
+        return undefined;
+    return evaluate(parsed.ast, { vars: vars });
+}
+function evalOutputEntry(text, vars) {
+    if (text.trim() === "")
+        return null;
+    return evalExpression(text, vars);
+}
+function buildResult(hitPolicy, aggregation, rows, outputCount) {
+    if (rows.length === 0)
+        return null;
+    const singleOutput = outputCount === 1;
+    switch (hitPolicy) {
+        case "UNIQUE":
+        case "FIRST":
+        case "ANY": {
+            const row = rows[0];
+            if (row === undefined)
+                return null;
+            return singleOutput ? firstValue(row) : row;
+        }
+        case "RULE ORDER":
+        case "OUTPUT ORDER":
+        case "PRIORITY": {
+            if (singleOutput)
+                return rows.map(firstValue);
+            return rows;
+        }
+        case "COLLECT": {
+            if (aggregation === undefined) {
+                if (singleOutput)
+                    return rows.map(firstValue);
+                return rows;
+            }
+            const values = rows.map(firstValue).filter((v) => typeof v === "number");
+            return aggregate(aggregation, values);
+        }
+        default:
+            return null;
+    }
+}
+function firstValue(row) {
+    for (const k of Object.keys(row)) {
+        return row[k];
+    }
+    return null;
+}
+function aggregate(op, values) {
+    if (values.length === 0)
+        return null;
+    switch (op) {
+        case "SUM":
+            return values.reduce((a, b) => a + b, 0);
+        case "MIN":
+            return Math.min(...values);
+        case "MAX":
+            return Math.max(...values);
+        case "COUNT":
+            return values.length;
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=dmn.js.map

package/dist/engine.d.ts

@@ -0,0 +1,36 @@
+import type { BpmnDefinitions, DmnDefinitions, FormDefinition } from "@bpmnkit/core";
+import { ProcessInstance } from "./instance.js";
+import type { JobHandler } from "./types.js";
+/** Options for {@link Engine.start}. */
+export interface StartOptions {
+    /**
+     * Hook called just before each element completes. Return a Promise to pause
+     * execution at that point — useful for step-by-step simulation.
+     */
+    beforeComplete?: (elementId: string) => Promise<void>;
+}
+export declare class Engine {
+    private readonly processes;
+    private readonly decisions;
+    private readonly forms;
+    private readonly workers;
+    /**
+     * Deploy BPMN processes, DMN decisions, and form definitions.
+     * Calling deploy multiple times merges into the registry.
+     */
+    deploy(d: {
+        bpmn?: BpmnDefinitions | BpmnDefinitions[];
+        forms?: FormDefinition | FormDefinition[];
+        decisions?: DmnDefinitions | DmnDefinitions[];
+    }): void;
+    /** Start a new process instance. Throws if processId is not deployed. */
+    start(processId: string, variables?: Record<string, unknown>, options?: StartOptions): ProcessInstance;
+    /**
+     * Register a job worker for a given task type.
+     * Returns an unsubscribe function.
+     */
+    registerJobWorker(type: string, handler: JobHandler): () => void;
+    /** Return all deployed process IDs. */
+    getDeployedProcesses(): string[];
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.js

@@ -0,0 +1,66 @@
+import { ProcessInstance } from "./instance.js";
+export class Engine {
+    processes = new Map();
+    decisions = new Map();
+    forms = new Map();
+    workers = new Map();
+    /**
+     * Deploy BPMN processes, DMN decisions, and form definitions.
+     * Calling deploy multiple times merges into the registry.
+     */
+    deploy(d) {
+        if (d.bpmn !== undefined) {
+            const defs = Array.isArray(d.bpmn) ? d.bpmn : [d.bpmn];
+            for (const def of defs) {
+                for (const process of def.processes) {
+                    this.processes.set(process.id, process);
+                }
+            }
+        }
+        if (d.decisions !== undefined) {
+            const defs = Array.isArray(d.decisions) ? d.decisions : [d.decisions];
+            for (const def of defs) {
+                for (const decision of def.decisions) {
+                    this.decisions.set(decision.id, decision);
+                }
+            }
+        }
+        if (d.forms !== undefined) {
+            const defs = Array.isArray(d.forms) ? d.forms : [d.forms];
+            for (const form of defs) {
+                const id = form.id;
+                if (id !== undefined)
+                    this.forms.set(id, form);
+            }
+        }
+    }
+    /** Start a new process instance. Throws if processId is not deployed. */
+    start(processId, variables, options) {
+        const process = this.processes.get(processId);
+        if (process === undefined) {
+            throw new Error(`Process "${processId}" is not deployed`);
+        }
+        const instance = new ProcessInstance(process, this.decisions, this.forms, this.workers, variables ?? {});
+        if (options?.beforeComplete !== undefined) {
+            instance.beforeComplete = options.beforeComplete;
+        }
+        instance.start();
+        return instance;
+    }
+    /**
+     * Register a job worker for a given task type.
+     * Returns an unsubscribe function.
+     */
+    registerJobWorker(type, handler) {
+        this.workers.set(type, handler);
+        return () => {
+            if (this.workers.get(type) === handler)
+                this.workers.delete(type);
+        };
+    }
+    /** Return all deployed process IDs. */
+    getDeployedProcesses() {
+        return [...this.processes.keys()];
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Engine } from "./engine.js";
+export type { StartOptions } from "./engine.js";
+export { ProcessInstance } from "./instance.js";
+export type { ProcessEvent, Job, JobHandler } from "./types.js";
+export { VariableStore } from "./variables.js";
+export { evaluateDecision } from "./dmn.js";
+export { scheduleTimer, parseDurationMs } from "./timers.js";
+export { parseZeebeExt } from "./zeebe.js";
+export type { ParsedZeebeExt } from "./zeebe.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,7 @@
+export { Engine } from "./engine.js";
+export { ProcessInstance } from "./instance.js";
+export { VariableStore } from "./variables.js";
+export { evaluateDecision } from "./dmn.js";
+export { scheduleTimer, parseDurationMs } from "./timers.js";
+export { parseZeebeExt } from "./zeebe.js";
+//# sourceMappingURL=index.js.map

package/dist/instance.d.ts

@@ -0,0 +1,72 @@
+import type { BpmnProcess, DmnDecision, FormDefinition } from "@bpmnkit/core";
+import type { JobHandler, ProcessEvent } from "./types.js";
+type InstanceState = "active" | "completed" | "terminated" | "failed";
+export declare class ProcessInstance {
+    readonly id: string;
+    readonly processId: string;
+    private _state;
+    private _error;
+    /** tokenId → Token */
+    private readonly allTokens;
+    /** Scope stack: rootScopeId + any active sub-process scopes */
+    private readonly scopes;
+    /** Message correlation: messageName → resolve callback */
+    private readonly messageSubscriptions;
+    /** Timer cancel functions keyed by tokenId */
+    private readonly timerCancels;
+    /** Activation count per elementId — used to detect infinite loops. */
+    private readonly activationCount;
+    private static readonly MAX_ACTIVATIONS;
+    /** Active boundary timer cancels, keyed by elementId */
+    private readonly boundaryTimerCancels;
+    private readonly variables;
+    private readonly rootScopeId;
+    private readonly listeners;
+    private readonly decisions;
+    private readonly forms;
+    private readonly jobWorkers;
+    /**
+     * Optional hook called just before an element completes (token moves on).
+     * Returning a Promise lets the caller pause execution — useful for
+     * step-by-step simulation. Set via {@link Engine.start} options.
+     */
+    beforeComplete?: (elementId: string) => Promise<void>;
+    constructor(process: BpmnProcess, decisions: Map<string, DmnDecision>, forms: Map<string, FormDefinition>, jobWorkers: Map<string, JobHandler>, initialVars: Record<string, unknown>);
+    get state(): InstanceState;
+    get error(): string | undefined;
+    get activeElements(): string[];
+    get variables_snapshot(): Record<string, unknown>;
+    onChange(callback: (event: ProcessEvent) => void): () => void;
+    cancel(): void;
+    /** Kick off execution. Called by Engine after construction. */
+    start(): void;
+    /** Deliver a message to a waiting element. */
+    deliverMessage(messageName: string): void;
+    private buildScopeCtx;
+    private createToken;
+    private removeToken;
+    /** elementId → set of incomingFlowIds received */
+    private readonly joins;
+    private activate;
+    private dispatch;
+    private handleEndEvent;
+    private handleJobTask;
+    private handleScriptTask;
+    private handleBusinessRuleTask;
+    private handleExclusiveGateway;
+    private handleInclusiveGateway;
+    private handleIntermediateCatchEvent;
+    private handleSubProcess;
+    private scheduleBoundaryTimers;
+    private cancelBoundaryTimers;
+    private propagateError;
+    private complete;
+    private getOutgoingFlows;
+    private finishProcess;
+    private cancelAllTimers;
+    private evalFeel;
+    private evalCondition;
+    private emit;
+}
+export {};
+//# sourceMappingURL=instance.d.ts.map