@nanobpm/workflow 0.6.0 → 0.8.0

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 {
@@ -53,11 +54,50 @@ 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: "timer"; name: string } & TimerAt)
   | { kind: "switch"; subject: string; cases: SwitchCase[]; default?: 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).
+ *  Encoded as an XOR so downstream consumers can rely on exactly-one. */
+export type TimerAt =
+  | { after: string; at?: never }
+  | { at: string; after?: never };
+
+/** A flow's start-timer: the plain none start event becomes a durable timer
+ *  start the engine fires on schedule. Exactly one of:
+ *  - `cycle` — a recurring ISO-8601 interval (`R/PT1H`, `R5/PT30M`) or bare
+ *    duration; the engine re-fires on each period. This is the model-native,
+ *    durable, single-fire-per-cluster replacement for an app-side cron.
+ *  - `after` — a one-shot ISO-8601 delay (`PT10S`) measured from deployment.
+ *  - `at`    — a one-shot absolute instant (an ISO-8601 date-time, or a FEEL
+ *    `=` expression).
+ *  Encoded as an XOR so the exactly-one invariant holds at the type level. */
+export type TimerStart =
+  | { cycle: string; after?: never; at?: never }
+  | { after: string; cycle?: never; at?: never }
+  | { at: string; cycle?: never; after?: never };
 
 /** One case of a `switch`: routed when `subject = value` (FEEL equality). */
 export interface SwitchCase {
@@ -75,6 +115,9 @@ export interface DeclarativeFlow {
   /** The flow's node tree (top-level sequence). */
   steps: FlowNode[];
   handlers: Record<string, StepHandler>;
+  /** When set, the flow's start event is a durable timer start (see
+   *  {@link TimerStart}) rather than a plain none start. */
+  startTimer?: TimerStart;
 }
 
 // --- Imperative surface (Strategy B: a replayed orchestration function) -------

package/src/worker.ts

@@ -112,8 +112,9 @@ export class Worker {
     } 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];

package/src/xml.ts

@@ -40,6 +40,68 @@ export function assertJobType(kind: string, value: string): void {
   }
 }
 
+// --- Timer definitions (BPMN timerEventDefinition bodies) --------------------
+//
+// The engine (engine-core/src/bpmn.rs) accepts a nested `timeDuration`,
+// `timeCycle`, or `timeDate` as either a static ISO-8601 literal or a FEEL
+// expression (a leading `=`). We validate the literal forms at authoring time so
+// a malformed timer fails fast in the DSL rather than at deploy.
+
+/** An ISO-8601 duration with integer week/day/hour/minute/second components
+ *  (no years/months — ambiguous length — matching the engine's parser). */
+const ISO_DURATION = /^P(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$/;
+function isIsoDuration(v: string): boolean {
+  if (!ISO_DURATION.test(v) || v === "P" || v === "PT" || v.endsWith("T")) return false;
+  return /\d/.test(v);
+}
+
+/** A recurring ISO-8601 interval: an optional `R[n]/` repeat prefix + a
+ *  duration, or a bare duration (the engine repeats it unboundedly). */
+function isIsoCycle(v: string): boolean {
+  const slash = v.indexOf("/");
+  if (slash < 0) return isIsoDuration(v);
+  const repeat = v.slice(0, slash);
+  const interval = v.slice(slash + 1);
+  return /^R\d*$/.test(repeat) && isIsoDuration(interval);
+}
+
+/** An ISO-8601 date-time instant (a `timeDate`). A `timeDate` is an absolute
+ *  instant, so a zone designator (`Z` or an explicit `±HH:MM` offset) is
+ *  required — a bare local datetime like `2026-01-01T09:00:00` is ambiguous. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/** A FEEL expression body (a leading `=`, non-empty). */
+function isFeel(v: string): boolean {
+  return v.startsWith("=") && v.length > 1;
+}
+
+export function assertTimerDuration(kind: string, value: string): void {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (v === "" || (!isFeel(v) && !isIsoDuration(v))) {
+    throw new Error(
+      `${kind} "${value}" is not an ISO-8601 duration (e.g. PT1M30S, P1DT6H) or a FEEL expression (=...)`,
+    );
+  }
+}
+
+export function assertTimerCycle(kind: string, value: string): void {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (v === "" || (!isFeel(v) && !isIsoCycle(v))) {
+    throw new Error(
+      `${kind} "${value}" is not an ISO-8601 repeating interval (e.g. R/PT1H, R5/PT30M), a bare duration (e.g. PT1H), or a FEEL expression (=...)`,
+    );
+  }
+}
+
+export function assertTimerDate(kind: string, value: string): void {
+  const v = typeof value === "string" ? value.trim() : "";
+  if (v === "" || (!isFeel(v) && !ISO_DATE.test(v))) {
+    throw new Error(
+      `${kind} "${value}" is not an ISO-8601 instant (e.g. 2026-01-01T09:00:00Z) or a FEEL expression (=...)`,
+    );
+  }
+}
+
 export function assertWorkflowIds(wf: Workflow): void {
   assertIdent("workflow id", wf.id);
   if (wf.kind === "declarative") {
@@ -54,6 +116,9 @@ function assertNodeNames(nodes: FlowNode[]): void {
       case "signal":
         assertIdent("step name", node.name);
         break;
+      case "timer":
+        assertIdent("step name", node.name);
+        break;
       case "task":
         assertIdent("step name", node.name);
         if (node.jobType !== undefined) assertJobType("job type", node.jobType);