@nanobpm/workflow 0.7.0 → 0.8.1

package/README.md

@@ -45,6 +45,14 @@ human-in-the-loop path), composed with control-flow combinators:
 - `w.branch(condition, { then, else? })` — a two-way choice on a FEEL boolean.
 - `w.loop(body)` — a durable loop (back-edge to the loop head).
 - `w.break()` / `w.continue()` — exit the enclosing loop, or jump back to its head.
+- `w.parallel([blockA, blockB, …])` — a static fork/join: every block runs
+  concurrently on its own branch, rejoined by an AND-join (all branches must
+  arrive before the flow continues).
+- `w.forEach(collection, itemVar, body, opts?)` — a data-driven fan-out over a
+  FEEL `collection`: one child instance of `body` runs per item (the item bound to
+  `itemVar`). `{ sequential }` runs children one at a time; `{ outputCollection,
+  outputElement }` collects each child's result into a list; `{ completionCondition }`
+  completes the body early.
 
 ```ts
 import { defineFlow, WorkflowClient, Worker } from "@nanobpm/workflow";
@@ -89,8 +97,10 @@ const convergence = defineFlow("convergence-loop", (w) => {
 Each combinator compiles to a BPMN primitive the engine already runs: `switch` /
 `branch` → an exclusive gateway (in-order conditions, first match wins, default =
 unconditional flow); `loop` → a convergent gateway whose body falls through back to
-the head; nodes with multiple incoming flows are an implicit XOR merge. See
-**ADR 0047**.
+the head; nodes with multiple incoming flows are an implicit XOR merge; `parallel`
+→ a diverging/converging **parallel gateway** pair (AND fork/join); `forEach` → a
+**parallel multi-instance** activity (a single-step body) or an embedded
+multi-instance sub-process (a multi-step body). See **ADR 0047**.
 
 #### Typed data envelopes (eject to model-first with contracts intact)
 
@@ -178,7 +188,7 @@ once.
 | Export | Purpose |
 | --- | --- |
 | `defineWorkflow(id, orchFn)` | Imperative (replayed) workflow — experimental/internal. |
-| `defineFlow(id, [contracts,] build)` | Declarative flow: `run`/`task`/`signal` + `switch`/`branch`/`loop`/`break`/`continue`, with an optional typed contracts map. |
+| `defineFlow(id, [contracts,] build)` | Declarative flow: `run`/`task`/`signal`/`timer` + `switch`/`branch`/`loop`/`break`/`continue` + `parallel`/`forEach`, with an optional typed contracts map. |
 | `envelope(name, fields)` | A typed data envelope; lifted into the model as a `nano:shape` + `dataEnvelope` wiring. |
 | `externalJobTypes(flow)` | The job types of a flow's external `task` steps (each overridable per-step via `w.task(name, { jobType })`). |
 | `WorkflowClient` | `deploy`, `start`, `signal`, `getInstance` over REST v2. |

package/dist/client.d.ts

@@ -26,23 +26,23 @@ export interface NanoSdkClient {
     createDeployment(input: {
         resources: File[];
         [k: string]: unknown;
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     createProcessInstance(input: {
         processDefinitionId: string;
         variables?: JsonObject;
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     correlateMessage(input: {
         name: string;
         correlationKey: string;
         variables?: JsonObject;
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     getProcessInstance(input: {
         processInstanceKey: string;
     }, consistency: {
         consistency: {
             waitUpToMs: number;
         };
-    }, options?: unknown): Promise<Record<string, unknown>>;
+    }, options?: unknown): Promise<unknown>;
     createJobWorker(cfg: JobWorkerConfig): NanoJobWorker;
 }
 /** Config for a nano-sdk job worker (the subset the Worker runtime sets). */

package/dist/client.js

@@ -3,11 +3,57 @@
 // deploys it (with diagram interchange), starts instances, and correlates
 // signals; the low-level job protocol used by the Worker runtime is the SDK's
 // own job worker, reached through the exposed `sdk` client.
-import { createCamundaClient } from "@nanobpm/nano-sdk";
+import { createCamundaClient, JobActionReceiptSymbol, ProcessDefinitionId, ProcessInstanceKey } from "@nanobpm/nano-sdk";
 import { declarativeToBpmn, walkNodes } from "./declarative.js";
 import { imperativeToBpmn } from "./imperative.js";
 import { layoutBpmn } from "./layout.js";
 import { assertWorkflowIds, messageName } from "./xml.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function errorCause(e) {
+    return isRecord(e) ? e.cause : undefined;
+}
+function errorCode(e) {
+    return isRecord(e) ? e.code : undefined;
+}
+function errorMessage(e) {
+    return isRecord(e) && typeof e.message === "string" ? e.message : String(e);
+}
+function errorStatus(e) {
+    if (!isRecord(e))
+        return undefined;
+    if (typeof e.status === "number")
+        return e.status;
+    const response = e.response;
+    return isRecord(response) && typeof response.status === "number" ? response.status : undefined;
+}
+function isJson(v) {
+    if (v === null)
+        return true;
+    switch (typeof v) {
+        case "boolean":
+        case "number":
+        case "string":
+            return true;
+        case "object":
+            if (Array.isArray(v))
+                return v.every(isJson);
+            return Object.values(v).every(isJson);
+        default:
+            return false;
+    }
+}
+function toJsonObject(v) {
+    if (!isRecord(v))
+        throw new Error("SDK response was not an object");
+    const result = {};
+    for (const [key, value] of Object.entries(v)) {
+        if (isJson(value))
+            result[key] = value;
+    }
+    return result;
+}
 /** Render a workflow (either surface) to its executable BPMN model. */
 export function toBpmn(wf) {
     assertWorkflowIds(wf);
@@ -37,8 +83,8 @@ export async function toDeployableBpmn(wf, opts = {}) {
         // Only fall back for the "optional dep not installed" case (layoutBpmn wraps
         // it with an ERR_MODULE_NOT_FOUND cause). Any other failure is a real layout
         // problem and must surface rather than silently deploy an uninspectable model.
-        const cause = e?.cause;
-        if (cause?.code !== "ERR_MODULE_NOT_FOUND")
+        const cause = errorCause(e);
+        if (errorCode(cause) !== "ERR_MODULE_NOT_FOUND")
             throw e;
         if (!warnedNoLayout) {
             warnedNoLayout = true;
@@ -65,9 +111,8 @@ export class WorkflowError extends Error {
 function asWorkflowError(e, what) {
     if (e instanceof WorkflowError)
         return e;
-    const err = e;
-    const status = err?.status ?? err?.response?.status;
-    return new WorkflowError(`${what} failed: ${err?.message ?? String(e)}`, status);
+    const status = errorStatus(e);
+    return new WorkflowError(`${what} failed: ${errorMessage(e)}`, status);
 }
 export class WorkflowClient {
     /** The underlying nano-sdk client, exposed so the Worker runtime and app
@@ -83,13 +128,42 @@ export class WorkflowClient {
         }
         if (!opts?.baseUrl)
             throw new Error("WorkflowClient needs a baseUrl or a client");
-        this.sdk = createCamundaClient({
+        const raw = createCamundaClient({
             config: {
                 CAMUNDA_REST_ADDRESS: opts.baseUrl.replace(/\/+$/, ""),
                 ...(opts.token ? { CAMUNDA_TOKEN: opts.token } : {}),
                 CAMUNDA_TRANSPORT: opts.transport ?? "auto",
             },
         });
+        this.sdk = {
+            createDeployment: (input) => raw.createDeployment(input),
+            createProcessInstance: (input) => raw.createProcessInstance({
+                ...input,
+                processDefinitionId: ProcessDefinitionId.assumeExists(input.processDefinitionId),
+            }),
+            correlateMessage: (input) => raw.correlateMessage(input),
+            getProcessInstance: (input, consistency) => raw.getProcessInstance({
+                processInstanceKey: ProcessInstanceKey.assumeExists(input.processInstanceKey),
+            }, consistency),
+            createJobWorker: (cfg) => {
+                const worker = raw.createJobWorker({
+                    ...cfg,
+                    jobHandler: async (job) => {
+                        await cfg.jobHandler(job);
+                        return JobActionReceiptSymbol;
+                    },
+                });
+                return {
+                    start: () => {
+                        void worker.start();
+                    },
+                    stop: () => worker.stop(),
+                    stopGracefully: async (opts) => {
+                        await worker.stopGracefully(opts);
+                    },
+                };
+            },
+        };
     }
     /**
      * Deploy a workflow's derived BPMN model. The deployed model includes
@@ -102,7 +176,7 @@ export class WorkflowClient {
         const xml = await toDeployableBpmn(wf, opts);
         const file = new File([xml], `${wf.id}.bpmn`, { type: "text/xml" });
         try {
-            return (await this.sdk.createDeployment({ resources: [file] }));
+            return toJsonObject(await this.sdk.createDeployment({ resources: [file] }));
         }
         catch (e) {
             throw asWorkflowError(e, "deploy");
@@ -116,7 +190,7 @@ export class WorkflowClient {
     async start(wf, input = {}) {
         const variables = wf.kind === "imperative" ? { input, journal: {}, wfDone: false } : input;
         try {
-            return (await this.sdk.createProcessInstance({
+            return toJsonObject(await this.sdk.createProcessInstance({
                 processDefinitionId: wf.id,
                 variables,
             }));
@@ -140,7 +214,7 @@ export class WorkflowClient {
             throw new WorkflowError(`unknown signal "${signalName}" on flow "${flow.id}" — declared signals: ${signals.length ? signals.map((s) => `"${s}"`).join(", ") : "(none)"}`);
         }
         try {
-            return (await this.sdk.correlateMessage({
+            return toJsonObject(await this.sdk.correlateMessage({
                 name: messageName(flow.id, signalName),
                 correlationKey,
                 variables,
@@ -154,7 +228,7 @@ export class WorkflowClient {
      *  zero-wait consistency; returns null when the instance is not (yet) visible. */
     async getInstance(processInstanceKey) {
         try {
-            return (await this.sdk.getProcessInstance({ processInstanceKey }, { consistency: { waitUpToMs: 0 } }));
+            return toJsonObject(await this.sdk.getProcessInstance({ processInstanceKey }, { consistency: { waitUpToMs: 0 } }));
         }
         catch {
             return null;

package/dist/declarative.d.ts

@@ -3,18 +3,18 @@ import type { Envelope } from "./envelope.js";
 /** The TS payload type of a contract's input envelope (untyped fallback). */
 type InPayload<Ct> = Ct extends {
     in: Envelope;
-} ? Ct["in"]["type"] : JsonObject;
+} ? Ct["in"]["type"] & JsonObject : JsonObject;
 /** The TS payload type of a contract's output envelope (untyped fallback). */
 type OutPayload<Ct> = Ct extends {
     out: Envelope;
-} ? Ct["out"]["type"] : JsonObject;
+} ? Ct["out"]["type"] & JsonObject : JsonObject;
 /** The input payload type of step `K` under contracts `C`. */
 type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
 /** The output payload type of step `K` under contracts `C`. */
 type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : JsonObject;
 /** A typed handler for a `run` step: its job variables and result are resolved
  *  from the flow contracts by the step name. */
-type TypedHandler<V, R> = (job: {
+type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
     jobKey: string;
     processInstanceKey: string;
     elementId: string;
@@ -22,8 +22,19 @@ type TypedHandler<V, R> = (job: {
     variables: V;
 }) => Promise<R | void> | R | void;
 /** A block: the callback that populates a nested body (a case, arm, or loop). */
-type Block<C extends FlowContracts> = (b: FlowBuilder<C>) => void;
-export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
+type Block<C extends object> = (b: FlowBuilder<C>) => void;
+/** The typed builder for a flow body.
+ *
+ * `C` is the flow's contracts map (step name → `{ in, out }` envelopes). The
+ * default is `object`, NOT `Record<string, never>`: with a `never`-valued record
+ * `keyof C` is `string`, so `VarsOf`/`ResultOf` route EVERY step name into
+ * `InPayload<never>`/`OutPayload<never>`, which distribute over `never` to
+ * `never` — typing an untyped flow's `job.variables` as `never` and forcing its
+ * handler return to `void` (so no untyped flow that returns data compiles). With
+ * `object`, `keyof C` is `never`, so every step falls back to the intended
+ * `JsonObject`. The public `defineFlow<C extends FlowContracts>` overload keeps
+ * the stricter contracts constraint; this is only the untyped-builder default. */
+export interface FlowBuilder<C extends object = object> {
     /**
      * A durable activity served by a worker THIS program hosts (a BPMN service
      * task; the handler runs in the in-process `Worker`). If `name` is a key in
@@ -109,6 +120,36 @@ export interface FlowBuilder<C extends FlowContracts = Record<string, never>> {
      * the loop run once `break()` is reached.
      */
     loop(body: Block<C>): FlowBuilder<C>;
+    /**
+     * A static parallel fork/join (a pair of BPMN parallel gateways). Every block
+     * runs concurrently on its own branch; control continues past `parallel` only
+     * once ALL branches have reached the joining gateway (AND-join). Pass at least
+     * two branch blocks. Unlike `switch`/`branch` (exclusive choice), no branch is
+     * conditional — all of them run.
+     */
+    parallel(branches: Block<C>[]): FlowBuilder<C>;
+    /**
+     * A data-driven fan-out over a runtime collection (a BPMN parallel
+     * multi-instance activity). `collection` is a FEEL expression (no leading `=`)
+     * evaluating to a list; one child instance of `body` runs per item, with the
+     * item bound to the `itemVar` variable in the child's scope. A single-activity
+     * body attaches the multi-instance characteristics to that activity; a
+     * multi-step body is wrapped in an embedded multi-instance sub-process. Options:
+     *  - `sequential` — run children one at a time (a sequential MI) instead of all
+     *    at once (the default: a parallel MI).
+     *  - `outputCollection` / `outputElement` — collect each child's `outputElement`
+     *    (a FEEL expression, no leading `=`) into the `outputCollection` list
+     *    variable, in item order.
+     *  - `completionCondition` — a FEEL boolean (no leading `=`); when it holds
+     *    after a child completes, the remaining children are cancelled and the body
+     *    completes early.
+     */
+    forEach(collection: string, itemVar: string, body: Block<C>, opts?: {
+        sequential?: boolean;
+        outputCollection?: string;
+        outputElement?: string;
+        completionCondition?: string;
+    }): FlowBuilder<C>;
     /** Exit the enclosing loop (routes to whatever follows it). Only valid inside
      *  a `loop`. */
     break(): FlowBuilder<C>;