@nanobpm/workflow 0.6.0 → 0.8.0

package/dist/types.d.ts

@@ -52,7 +52,10 @@ export type FlowNode = {
     name: string;
     correlationKey: string;
     payload?: Envelope;
-} | {
+} | ({
+    kind: "timer";
+    name: string;
+} & TimerAt) | {
     kind: "switch";
     subject: string;
     cases: SwitchCase[];
@@ -69,6 +72,56 @@ export type FlowNode = {
     kind: "break";
 } | {
     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 {
@@ -84,6 +137,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;
 }
 /** The context passed to an imperative orchestration function. */
 export interface WorkflowContext {

package/dist/worker.js

@@ -60,8 +60,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;

package/dist/xml.d.ts

@@ -8,4 +8,7 @@ export declare const messageName: (workflowId: string, step: string) => string;
 export declare const orchestrateType: (workflowId: string) => string;
 export declare function assertIdent(kind: string, value: string): void;
 export declare function assertJobType(kind: string, value: string): void;
+export declare function assertTimerDuration(kind: string, value: string): void;
+export declare function assertTimerCycle(kind: string, value: string): void;
+export declare function assertTimerDate(kind: string, value: string): void;
 export declare function assertWorkflowIds(wf: Workflow): void;

package/dist/xml.js

@@ -29,6 +29,56 @@ export function assertJobType(kind, value) {
         throw new Error(`${kind} "${value}" is not a valid job type (expected a non-empty token of letters, digits, and _ . : + -)`);
     }
 }
+// --- 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) {
+    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) {
+    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) {
+    return v.startsWith("=") && v.length > 1;
+}
+export function assertTimerDuration(kind, value) {
+    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, value) {
+    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, value) {
+    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) {
     assertIdent("workflow id", wf.id);
     if (wf.kind === "declarative") {
@@ -42,6 +92,9 @@ function assertNodeNames(nodes) {
             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)

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@nanobpm/workflow",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Code-first durable orchestration for nanobpmn (ADR 0044/0045). Author a durable workflow as a declarative flow — `defineFlow(id, w => { w.run(...); w.signal(...); w.task(...) })` — and the SDK derives the executable BPMN model, the job types, and the message/correlation wiring, then hosts a generic worker. `w.run` is a local step, `w.signal` is a durable human-in-the-loop wait, `w.task` is a step serviced by an external worker. `defineFlow` is the single code-first surface; the imperative `defineWorkflow` replay function is experimental/internal, not a recommended API. No diagram, no task-type wiring, no correlation plumbing authored by hand — and you can optionally auto-generate a diagram (DI) for the derived model with `declarativeToLayoutedBpmn` via the optional `bpmn-auto-layout` peer dependency. Talks to a running nanobpmn gateway through @nanobpm/nano-sdk (the shared engine-transport spine — ADR 0055), which negotiates the Falcon protocol on a Nano server and REST elsewhere.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jwulf/nano-ide.git",
+    "url": "git+https://github.com/jwulf/nano-ide.git",
     "directory": "packages/workflow"
   },
   "main": "./dist/index.js",
@@ -28,11 +28,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@nanobpm/nano-sdk": "^1.2.0"
+    "@nanobpm/nano-sdk": "^1.2.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.types.json",
     "test": "npm run build && npm run test:ci",
     "test:ci": "node --experimental-strip-types --test test/*.test.ts",
     "test:integration": "node --experimental-strip-types --test test/integration.test.ts",