@nanobpm/workflow 0.2.0 → 0.4.0

package/src/envelope.ts

@@ -0,0 +1,130 @@
+// Typed data envelopes — the code-first expression of a nano:shape.
+//
+// An envelope declares a named, typed payload contract IN CODE. It carries two
+// things at once:
+//   - a runtime schema (ordered fields + scalar types), which the model emitter
+//     LIFTS into the BPMN as a `nano:shape` (under `nano:shapes` on the process)
+//     plus the `io.nanobpm.dataEnvelope.in/out` `zeebe:property` on the service
+//     task / message — exactly the carrier the console derives worker I/O from
+//     (server/src/console/envelope_scan.rs); and
+//   - a phantom TypeScript type, inferred from the field spec, so `run`/`task`
+//     handlers and message payloads are statically typed at the call site.
+//
+// This is what makes code-first EJECTABLE to model-first: the generated `.bpmn`
+// already carries the typed shapes + envelope wiring the modeller and the Fused
+// Domain Model (ADR 0040) expect, so opening it in the Modeller loses nothing.
+//
+//   const PrReviewRoundIn = envelope("PrReviewRoundIn", {
+//     prUrl: "string", repo: "string", prNumber: "integer",
+//     prompt: "string", round: "integer",
+//     answer: { type: "string", optional: true },
+//   });
+//   // PrReviewRoundIn.type  ≅  { prUrl: string; repo: string; prNumber: number;
+//   //                            prompt: string; round: number; answer?: string }
+
+import { assertIdent } from "./xml.js";
+
+/** The scalar types a `nano:extend` field may declare (mirrors the vocabulary
+ *  the console's shape scan understands). `integer`/`number` are both `number`
+ *  in TS; `datetime` is an ISO `string`. */
+export type ScalarType = "string" | "integer" | "number" | "boolean" | "datetime";
+
+/** Map a scalar envelope type to its TypeScript representation. */
+export type ScalarTs<T extends ScalarType> = T extends "string" | "datetime"
+  ? string
+  : T extends "integer" | "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : never;
+
+/** A field spec: either a bare scalar type, or an object with modifiers. */
+export type FieldSpec =
+  | ScalarType
+  | { type: ScalarType; optional?: boolean; list?: boolean };
+
+/** The TS type of a single field spec (applies `list` before `optional`). */
+export type FieldTs<F> = F extends ScalarType
+  ? ScalarTs<F>
+  : F extends { type: infer T extends ScalarType; list: true }
+    ? ScalarTs<T>[]
+    : F extends { type: infer T extends ScalarType }
+      ? ScalarTs<T>
+      : never;
+
+type OptionalKeys<S> = {
+  [K in keyof S]: S[K] extends { optional: true } ? K : never;
+}[keyof S];
+type RequiredKeys<S> = Exclude<keyof S, OptionalKeys<S>>;
+
+/** The inferred payload type of an envelope: required + optional fields. */
+export type EnvelopeType<S extends Record<string, FieldSpec>> = {
+  [K in RequiredKeys<S>]: FieldTs<S[K]>;
+} & {
+  [K in OptionalKeys<S>]?: FieldTs<S[K]>;
+};
+
+/** A normalised field, as stored on an `Envelope` and lifted to `nano:extend`. */
+export interface EnvelopeField {
+  name: string;
+  type: ScalarType;
+  optional: boolean;
+  list: boolean;
+}
+
+/**
+ * A typed data envelope: a named schema (for the model) plus a phantom TS type
+ * (for the call site). Construct with {@link envelope}. `type` is a phantom
+ * property — it is `undefined` at runtime and exists only to carry the inferred
+ * payload type (use `typeof env.type` in type positions).
+ */
+export interface Envelope<S extends Record<string, FieldSpec> = Record<string, FieldSpec>> {
+  readonly name: string;
+  readonly fields: EnvelopeField[];
+  /** Phantom: the inferred payload type. Do not read at runtime. */
+  readonly type: EnvelopeType<S>;
+}
+
+const SCALARS: ReadonlySet<string> = new Set([
+  "string",
+  "integer",
+  "number",
+  "boolean",
+  "datetime",
+]);
+
+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`);
+  }
+  const raw = typeof spec === "string" ? { type: spec } : spec;
+  if (!SCALARS.has(raw.type)) {
+    throw new Error(
+      `envelope field "${name}": unknown type "${raw.type}" (expected one of ${[...SCALARS].join(", ")})`,
+    );
+  }
+  return {
+    name,
+    type: raw.type,
+    optional: typeof spec === "object" && spec.optional === true,
+    list: typeof spec === "object" && spec.list === true,
+  };
+}
+
+/**
+ * Declare a typed data envelope. `name` becomes the `nano:shape` id lifted into
+ * the model (must be a valid BPMN identifier); `fields` declares the payload.
+ * The returned envelope's `type` phantom carries the inferred TS payload type.
+ */
+export function envelope<const S extends Record<string, FieldSpec>>(
+  name: string,
+  fields: S,
+): Envelope<S> {
+  assertIdent("envelope name", name);
+  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> };
+}

package/src/index.ts

@@ -41,8 +41,19 @@
 // discipline). Retained for advanced durable-orchestration use only.
 export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
 export type { Journal, ReplayStep } from "./imperative.js";
-export { defineFlow, declarativeToBpmn, externalJobTypes } from "./declarative.js";
+export { defineFlow, declarativeToBpmn, externalJobTypes, walkNodes } from "./declarative.js";
 export type { FlowBuilder } from "./declarative.js";
+export { layoutBpmn, declarativeToLayoutedBpmn } from "./layout.js";
+export { envelope } from "./envelope.js";
+export type {
+  Envelope,
+  EnvelopeType,
+  EnvelopeField,
+  FieldSpec,
+  ScalarType,
+  ScalarTs,
+  FieldTs,
+} from "./envelope.js";
 export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
 export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
 export { Worker } from "./worker.js";
@@ -54,6 +65,11 @@ export type {
   StepHandler,
   DeclarativeFlow,
   DeclarativeStep,
+  FlowNode,
+  SwitchCase,
+  NodeEnvelopes,
+  StepContract,
+  FlowContracts,
   ImperativeWorkflow,
   Orchestration,
   WorkflowContext,

package/src/layout.ts

@@ -0,0 +1,68 @@
+// Optional diagram-interchange (DI) generation for the code-first surfaces.
+//
+// The authoring surfaces emit *semantic* BPMN — process, flow nodes, sequence
+// flows, messages — with no `bpmndi:` diagram: the engine runs the semantic model
+// and DI is an authoring-time concern only (a derived flow has no diagram of its
+// own). This module layers bpmn-io's `bpmn-auto-layout` on top so a derived model
+// opens with a rendered, auto-laid-out diagram in a modeller/viewer, which makes
+// code-first flows visually inspectable, reviewable, and round-trippable.
+//
+// `bpmn-auto-layout` is an *optional peer dependency*: the runtime client stays
+// dependency-free and the layout engine is loaded lazily, only when you ask for a
+// diagram. Install it alongside this package (`npm i bpmn-auto-layout`) to use
+// these helpers.
+//
+// DI is best-effort and *regenerable* — the semantic model (`declarativeToBpmn`)
+// stays authoritative. Re-run layout whenever the flow changes rather than
+// hand-editing the generated diagram.
+
+import type { DeclarativeFlow } from "./types.js";
+import { declarativeToBpmn } from "./declarative.js";
+
+/**
+ * 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
+ * (`bpmndi:BPMNDiagram`). Works on DI-less *or* already-laid-out input, and
+ * preserves `zeebe:` extension elements (task definitions, message
+ * subscriptions) through the round-trip.
+ *
+ * Requires the optional peer dependency `bpmn-auto-layout` to be installed; a
+ * clear error is thrown if it is missing.
+ */
+export async function layoutBpmn(bpmnXml: string): Promise<string> {
+  let layoutProcess: typeof import("bpmn-auto-layout").layoutProcess;
+  try {
+    ({ layoutProcess } = await import("bpmn-auto-layout"));
+  } catch (cause) {
+    // Only substitute the friendly "not installed" message when the module
+    // 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") {
+      throw cause;
+    }
+    throw new Error(
+      'layoutBpmn requires the optional peer dependency "bpmn-auto-layout". ' +
+        "Install it to generate diagram layout: npm i bpmn-auto-layout",
+      { cause },
+    );
+  }
+  const result = await layoutProcess(bpmnXml);
+  // Version-shape normalization: bpmn-auto-layout 2.x (and >= 1.4) resolves to
+  // `{ xml, warnings }`; 1.3.x resolved to the laid-out XML string directly. We
+  // pin >= 2.0.0-alpha.2 but normalize both so the SDK tolerates the whole range.
+  return typeof result === "string" ? result : result.xml;
+}
+
+/**
+ * Derive an executable BPMN model from a declarative flow AND auto-generate its
+ * diagram (DI), so the model opens rendered in a modeller/viewer. Convenience
+ * over `layoutBpmn(declarativeToBpmn(flow))`; async because layout is async. The
+ * semantic model stays authoritative — see `declarativeToBpmn` for the DI-less
+ * model the engine actually runs.
+ *
+ * Requires the optional peer dependency `bpmn-auto-layout` to be installed.
+ */
+export function declarativeToLayoutedBpmn(flow: DeclarativeFlow): Promise<string> {
+  return layoutBpmn(declarativeToBpmn(flow));
+}

package/src/types.ts

@@ -1,32 +1,79 @@
 // Public types for @nanobpm/workflow.
 
+import type { Envelope } from "./envelope.js";
+
 /** A JSON-serialisable value, as carried by process variables. */
 export type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
 export type JsonObject = { [k: string]: Json };
 
-/** A job as delivered by the nanobpmn gateway's `POST /v2/jobs/activation`. */
-export interface Job {
+/** A job as delivered by the nanobpmn gateway's `POST /v2/jobs/activation`. The
+ *  `variables` type parameter carries the input envelope's inferred payload when
+ *  a step is declared with a typed envelope; it defaults to the untyped
+ *  `JsonObject`. */
+export interface Job<V extends JsonObject = JsonObject> {
   jobKey: string;
   processInstanceKey: string;
   elementId: string;
   type: string;
-  variables: JsonObject;
+  variables: V;
 }
 
-// --- Declarative surface (Strategy A: compile a step list to a linear model) --
+// --- 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.
+
+/** The input/output data envelopes lifted onto an activity node. */
+export interface NodeEnvelopes {
+  in?: Envelope;
+  out?: Envelope;
+}
+
+/** A typed I/O contract for one step: its input and/or output data envelope.
+ *  For a `signal`, `in` types the message payload. */
+export interface StepContract {
+  in?: Envelope;
+  out?: Envelope;
+}
+
+/** A flow's typed I/O registry, keyed by step name — the single source of truth
+ *  for each step's envelopes. Passed to `defineFlow`; a step whose name is a key
+ *  is typed (and its envelopes lifted to the model), others fall back to the
+ *  untyped `JsonObject`. */
+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 DeclarativeStep =
-  | { kind: "run"; name: string }
-  | { kind: "task"; name: string }
-  | { kind: "signal"; name: string; correlationKey: string };
+/** A node in a declarative flow tree. Leaf activities carry optional data
+ *  envelopes (lifted to `nano:shape` + `dataEnvelope` in the model); structural
+ *  combinators carry nested `FlowNode[]` bodies. */
+export type FlowNode =
+  | { kind: "run"; name: string; envelopes?: NodeEnvelopes }
+  | { kind: "task"; name: string; envelopes?: NodeEnvelopes; jobType?: string }
+  | { kind: "signal"; name: string; correlationKey: string; payload?: Envelope }
+  | { kind: "switch"; subject: string; cases: SwitchCase[]; default?: FlowNode[] }
+  | { kind: "branch"; condition: string; then: FlowNode[]; else?: FlowNode[] }
+  | { kind: "loop"; body: FlowNode[] }
+  | { kind: "break" }
+  | { kind: "continue" };
+
+/** One case of a `switch`: routed when `subject = value` (FEEL equality). */
+export interface SwitchCase {
+  value: string;
+  body: FlowNode[];
+}
+
+/** @deprecated Renamed to {@link FlowNode} now that a flow is a tree of nodes,
+ *  not a flat list of steps. Kept as an alias for source compatibility. */
+export type DeclarativeStep = FlowNode;
 
 export interface DeclarativeFlow {
   kind: "declarative";
   id: string;
-  steps: DeclarativeStep[];
+  /** The flow's node tree (top-level sequence). */
+  steps: FlowNode[];
   handlers: Record<string, StepHandler>;
 }
 

package/src/worker.ts

@@ -14,6 +14,7 @@
 
 import { WorkflowClient } from "./client.js";
 import { replayOnce } from "./imperative.js";
+import { walkNodes } from "./declarative.js";
 import type { Job, JsonObject, Workflow } from "./types.js";
 import { jobType } from "./xml.js";
 
@@ -86,10 +87,12 @@ export class Worker {
         },
       });
     } else {
-      for (const s of wf.steps) {
-        // Only `run` steps are hosted locally; `signal` (message catch) and
-        // `task` (external worker) contribute no in-process route.
-        if (s.kind !== "run") continue;
+      // 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.
+      walkNodes(wf.steps, (s) => {
+        if (s.kind !== "run") return;
         const handler = wf.handlers[s.name];
         if (typeof handler !== "function") {
           // `DeclarativeFlow` is a public type; a consumer-constructed flow could
@@ -104,7 +107,7 @@ export class Worker {
           workflowId: wf.id,
           handle: async (job) => ({ variables: ((await handler(job)) ?? {}) as JsonObject }),
         });
-      }
+      });
     }
   }
 

package/src/xml.ts

@@ -1,6 +1,6 @@
 // XML helpers + derived-name conventions shared by both model emitters.
 
-import type { Workflow } from "./types.js";
+import type { FlowNode, Workflow } from "./types.js";
 
 export function escapeXml(s: string): string {
   return String(s)
@@ -27,9 +27,51 @@ export function assertIdent(kind: string, value: string): void {
   }
 }
 
+/** An explicit job type override (e.g. a `rank:capability` worker token like
+ *  `senior:pr-review`). Unlike a step name it is NOT a BPMN element id, so it may
+ *  carry the `:`/`+` token delimiters a `c8ctl nano work` matrix uses; it only
+ *  has to be a non-empty, whitespace-free token. */
+const JOB_TYPE = /^[A-Za-z0-9_][A-Za-z0-9_.:+-]*$/;
+export function assertJobType(kind: string, value: string): void {
+  if (typeof value !== "string" || !JOB_TYPE.test(value)) {
+    throw new Error(
+      `${kind} "${value}" is not a valid job type (expected a non-empty token of letters, digits, and _ . : + -)`,
+    );
+  }
+}
+
 export function assertWorkflowIds(wf: Workflow): void {
   assertIdent("workflow id", wf.id);
   if (wf.kind === "declarative") {
-    for (const step of wf.steps) assertIdent("step name", step.name);
+    assertNodeNames(wf.steps);
+  }
+}
+
+function assertNodeNames(nodes: FlowNode[]): void {
+  for (const node of nodes) {
+    switch (node.kind) {
+      case "run":
+      case "signal":
+        assertIdent("step name", node.name);
+        break;
+      case "task":
+        assertIdent("step name", node.name);
+        if (node.jobType !== undefined) assertJobType("job type", node.jobType);
+        break;
+      case "switch":
+        for (const c of node.cases) assertNodeNames(c.body);
+        if (node.default) assertNodeNames(node.default);
+        break;
+      case "branch":
+        assertNodeNames(node.then);
+        if (node.else) assertNodeNames(node.else);
+        break;
+      case "loop":
+        assertNodeNames(node.body);
+        break;
+      case "break":
+      case "continue":
+        break;
+    }
   }
 }