@nanobpm/workflow 0.7.0 → 0.8.1

package/src/envelope.ts

@@ -93,6 +93,15 @@ const SCALARS: ReadonlySet<string> = new Set([
   "datetime",
 ]);
 
+class EnvelopeDef<S extends Record<string, FieldSpec>> implements Envelope<S> {
+  readonly type!: EnvelopeType<S>;
+
+  constructor(
+    readonly name: string,
+    readonly fields: EnvelopeField[],
+  ) {}
+}
+
 function normaliseField(name: string, spec: FieldSpec): EnvelopeField {
   if (spec === null || (typeof spec !== "string" && typeof spec !== "object")) {
     throw new Error(`envelope field "${name}": must be a scalar type or a { type, optional?, list? } object`);
@@ -124,7 +133,5 @@ export function envelope<const S extends Record<string, FieldSpec>>(
   const list = Object.entries(fields).map(([k, v]) => normaliseField(k, v));
   if (list.length === 0) throw new Error(`envelope "${name}" declares no fields`);
   for (const f of list) assertIdent("envelope field name", f.name);
-  // `type` is phantom: never read at runtime; the cast keeps the value shape
-  // minimal while the declared type carries the inference.
-  return { name, fields: list, type: undefined as unknown as EnvelopeType<S> };
+  return new EnvelopeDef(name, list);
 }

package/src/imperative.ts

@@ -64,8 +64,19 @@ export function imperativeToBpmn(wf: ImperativeWorkflow): string {
 export type Journal = Record<string, Json>;
 
 const SUSPEND = Symbol("nanobpm.workflow.suspend");
-interface SuspendCarrier {
-  [SUSPEND]?: { key: string; result: Json };
+
+class SuspendError extends Error {
+  readonly [SUSPEND]: { key: string; result: Json };
+
+  constructor(key: string, result: Json) {
+    super("nanobpm.workflow suspend");
+    this[SUSPEND] = { key, result };
+  }
+}
+
+function assertReplayValue<T extends Json>(_value: Json, _name: string): asserts _value is T {
+  // The journal value was recorded from the same ordinal/name run call on an
+  // earlier pass; TypeScript cannot express that cross-replay invariant.
 }
 
 /** Outcome of a single replay pass. */
@@ -92,20 +103,20 @@ export async function replayOnce(
     async run<T extends Json = Json>(name: string, fn: () => Promise<T> | T): Promise<T> {
       const key = `${++ordinal}:${name}`;
       if (Object.prototype.hasOwnProperty.call(journal, key)) {
-        return journal[key] as T; // replay: return recorded value, no side effect
+        const value = journal[key];
+        assertReplayValue<T>(value, name);
+        return value; // replay: return recorded value, no side effect
       }
-      const result = ((await fn()) ?? null) as T; // frontier: the ONE real side effect this turn
-      const carrier = new Error("nanobpm.workflow suspend") as Error & SuspendCarrier;
-      carrier[SUSPEND] = { key, result };
-      throw carrier;
+      const result = (await fn()) ?? null; // frontier: the ONE real side effect this turn
+      assertReplayValue<T>(result, name);
+      throw new SuspendError(key, result);
     },
   };
   try {
     await wf.orchestrate(ctx);
     return { done: true };
   } catch (e) {
-    const s = (e as SuspendCarrier)[SUSPEND];
-    if (s) return { done: false, frontier: s };
+    if (e instanceof SuspendError) return { done: false, frontier: e[SUSPEND] };
     throw e; // a genuine error in the orchestration or a handler
   }
 }

package/src/layout.ts

@@ -19,6 +19,10 @@
 import type { DeclarativeFlow } from "./types.js";
 import { declarativeToBpmn } from "./declarative.js";
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 /**
  * Generate BPMN diagram interchange (DI) for a BPMN XML string using bpmn-io's
  * `bpmn-auto-layout`, returning the same model with an auto-laid-out diagram
@@ -38,7 +42,7 @@ export async function layoutBpmn(bpmnXml: string): Promise<string> {
     // genuinely cannot be resolved. A different failure (the package is present
     // but fails to load — syntax, a broken transitive dep, a runtime throw at
     // import time) must surface as-is so it isn't masked as a missing dependency.
-    if ((cause as NodeJS.ErrnoException | undefined)?.code !== "ERR_MODULE_NOT_FOUND") {
+    if (!isRecord(cause) || cause.code !== "ERR_MODULE_NOT_FOUND") {
       throw cause;
     }
     throw new Error(

package/src/types.ts

@@ -21,8 +21,9 @@ export interface Job<V extends JsonObject = JsonObject> {
 // --- Declarative surface (Strategy A: compile a step tree to a BPMN model) ----
 //
 // A flow is a TREE of nodes, not a flat list: leaf activities (`run`/`task`/
-// `signal`) plus structural combinators (`switch`/`branch`/`loop`) that compile
-// to real XOR gateways and back-edges. See declarative.ts for the compiler.
+// `signal`) plus structural combinators (`switch`/`branch`/`loop` — XOR gateways
+// + back-edges — and `parallel`/`forEach` — parallel gateways + multi-instance)
+// that compile to real BPMN the engine runs. See declarative.ts for the compiler.
 
 /** The input/output data envelopes lifted onto an activity node. */
 export interface NodeEnvelopes {
@@ -44,7 +45,12 @@ export interface StepContract {
 export type FlowContracts = Record<string, StepContract>;
 
 /** Handler for a declarative `run` step: does real work, returns variables. */
-export type StepHandler = (job: Job) => Promise<JsonObject | void> | JsonObject | void;
+export type StepHandler<
+  V extends JsonObject = JsonObject,
+  R extends JsonObject = JsonObject,
+> = {
+  bivarianceHack(job: Job<V>): Promise<R | void> | R | void;
+}["bivarianceHack"];
 
 /** A node in a declarative flow tree. Leaf activities carry optional data
  *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
@@ -58,7 +64,24 @@ export type FlowNode =
   | { kind: "branch"; condition: string; then: FlowNode[]; else?: FlowNode[] }
   | { kind: "loop"; body: FlowNode[] }
   | { kind: "break" }
-  | { kind: "continue" };
+  | { kind: "continue" }
+  | { kind: "parallel"; branches: FlowNode[][] }
+  | {
+      kind: "forEach";
+      /** FEEL expression evaluating to the list to fan out over. */
+      collection: string;
+      /** Variable each item is bound to in the child's scope (`inputElement`). */
+      itemVar: string;
+      body: FlowNode[];
+      /** Run children one at a time (sequential MI) instead of all at once. */
+      sequential?: boolean;
+      /** List variable that each child's `outputElement` is collected into. */
+      outputCollection?: string;
+      /** FEEL expression producing each child's contribution to `outputCollection`. */
+      outputElement?: string;
+      /** FEEL boolean that, once true, completes the body early. */
+      completionCondition?: string;
+    };
 
 /** A timer intermediate-catch definition: exactly one of `after` (an ISO-8601
  *  delay or FEEL expression) or `at` (an absolute instant or FEEL expression).

package/src/worker.ts

@@ -70,6 +70,10 @@ export type WorkerOptions =
 
 type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
 
+function isJsonObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
 export class Worker {
   private readonly client: WorkflowClient;
   private readonly name: string;
@@ -101,19 +105,24 @@ export class Worker {
       this.addRoute(wf.orchestrateType, {
         workflowId: wf.id,
         handle: async (job) => {
-          const input = (job.variables.input as JsonObject) ?? {};
-          const journal = (job.variables.journal as JsonObject) ?? {};
+          const input = isJsonObject(job.variables.input) ? job.variables.input : {};
+          const journal = isJsonObject(job.variables.journal) ? job.variables.journal : {};
           const step = await replayOnce(wf, input, journal);
-          if (step.done) return { variables: { wfDone: true } as JsonObject, step: "__done" };
+          if (step.done) {
+            const variables: JsonObject = { wfDone: true };
+            return { variables, step: "__done" };
+          }
           const next = { ...journal, [step.frontier.key]: step.frontier.result };
-          return { variables: { journal: next, wfDone: false } as JsonObject, step: step.frontier.key };
+          const variables: JsonObject = { journal: next, wfDone: false };
+          return { variables, step: step.frontier.key };
         },
       });
     } else {
       // Walk the flow tree; only `run` steps are hosted locally. `signal`
       // (message catch) and `task` (external worker) contribute no in-process
-      // route, and structural combinators (`switch`/`branch`/`loop`) are pure
-      // routing with no job of their own.
+      // route, and structural combinators (`switch`/`branch`/`loop`/`parallel`/
+      // `forEach`) are pure routing with no job of their own — but the `run`
+      // steps NESTED inside them are hosted, since `walkNodes` recurses.
       walkNodes(wf.steps, (s) => {
         if (s.kind !== "run") return;
         const handler = wf.handlers[s.name];
@@ -128,7 +137,10 @@ export class Worker {
         }
         this.addRoute(jobType(wf.id, s.name), {
           workflowId: wf.id,
-          handle: async (job) => ({ variables: ((await handler(job)) ?? {}) as JsonObject }),
+          handle: async (job) => {
+            const variables: JsonObject = (await handler(job)) ?? {};
+            return { variables };
+          },
         });
       });
     }