@nanobpm/workflow 0.1.0

package/src/index.ts

@@ -0,0 +1,47 @@
+// @nanobpm/workflow — code-first durable orchestration for nanobpmn (ADR 0044).
+//
+// Two authoring surfaces over the same engine durability:
+//
+//   defineWorkflow(id, async (ctx) => { await ctx.run(...) })   // imperative (replay)
+//   defineFlow(id, (w) => { w.run(...); w.signal(...); })       // declarative (+signals)
+//
+// The SDK derives the BPMN model, job types, and message/correlation wiring; the
+// Worker runtime hosts them; the WorkflowClient deploys, starts, and signals.
+//
+// Quickstart:
+//
+//   import { defineWorkflow, WorkflowClient, Worker } from "@nanobpm/workflow";
+//
+//   const wf = defineWorkflow("pr-review", async (ctx) => {
+//     const diff = await ctx.run("fetchDiff", () => gh.diff(ctx.input.prId));
+//     await ctx.run("merge", () => gh.merge(ctx.input.prId));
+//   });
+//
+//   const client = new WorkflowClient({ baseUrl: "http://localhost:8080" });
+//   await client.deploy(wf);
+//   const worker = new Worker({ baseUrl: "http://localhost:8080", workflows: [wf] });
+//   worker.start();
+//   await client.start(wf, { prId: "PR-1234" });
+
+export { defineWorkflow, imperativeToBpmn, replayOnce } from "./imperative.js";
+export type { Journal, ReplayStep } from "./imperative.js";
+export { defineFlow, declarativeToBpmn } from "./declarative.js";
+export type { FlowBuilder } from "./declarative.js";
+export { WorkflowClient, WorkflowError, toBpmn } from "./client.js";
+export type { WorkflowClientOptions, ActivateOptions } from "./client.js";
+export { Worker } from "./worker.js";
+export type { WorkerOptions, ActivityEvent } from "./worker.js";
+export type {
+  Json,
+  JsonObject,
+  Job,
+  StepHandler,
+  DeclarativeFlow,
+  DeclarativeStep,
+  ImperativeWorkflow,
+  Orchestration,
+  WorkflowContext,
+  Workflow,
+  DeployResult,
+  StartResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,69 @@
+// Public types for @nanobpm/workflow.
+
+/** 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 {
+  jobKey: string;
+  processInstanceKey: string;
+  elementId: string;
+  type: string;
+  variables: JsonObject;
+}
+
+// --- Declarative surface (Strategy A: compile a step list to a linear model) --
+
+/** 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: "signal"; name: string; correlationKey: string };
+
+export interface DeclarativeFlow {
+  kind: "declarative";
+  id: string;
+  steps: DeclarativeStep[];
+  handlers: Record<string, StepHandler>;
+}
+
+// --- Imperative surface (Strategy B: a replayed orchestration function) -------
+
+/** The context passed to an imperative orchestration function. */
+export interface WorkflowContext {
+  /** The workflow's start input (immutable across replays). */
+  readonly input: JsonObject;
+  /**
+   * A durable activity. On first execution the handler runs (its side effects
+   * happen once); on every subsequent replay the recorded result is returned
+   * WITHOUT invoking the handler. The handler is the only place side effects
+   * (I/O, network, shell, LLM) are allowed — the orchestration body itself must
+   * be deterministic.
+   */
+  run<T extends Json = Json>(name: string, fn: () => Promise<T> | T): Promise<T>;
+}
+
+export type Orchestration = (ctx: WorkflowContext) => Promise<void>;
+
+export interface ImperativeWorkflow {
+  kind: "imperative";
+  id: string;
+  orchestrate: Orchestration;
+  /** Derived job type of the single orchestrator task: `<id>:__orchestrate`. */
+  orchestrateType: string;
+}
+
+export type Workflow = DeclarativeFlow | ImperativeWorkflow;
+
+/** Result of deploying a workflow. */
+export interface DeployResult {
+  [k: string]: Json;
+}
+
+/** Result of starting a workflow instance. */
+export interface StartResult {
+  processInstanceKey?: string;
+  [k: string]: Json | undefined;
+}

package/src/worker.ts

@@ -0,0 +1,165 @@
+// The Worker runtime — hosts one or more workflows against a gateway and drives
+// them: long-polls each derived job type, dispatches jobs to handlers, completes
+// them. It generalises the two surfaces:
+//
+//   - a declarative flow contributes one job type per `run` step, dispatched to
+//     the user handler;
+//   - an imperative workflow contributes its single orchestrator job type,
+//     dispatched to the replay engine (which advances the journal one step).
+//
+// It is resilient to the gateway disappearing (each poll loop backs off and
+// reconnects on its own), so it survives an engine crash/restart — the property
+// the ADR 0044 spike proved.
+
+import { WorkflowClient } from "./client.js";
+import { replayOnce } from "./imperative.js";
+import type { Job, JsonObject, Workflow } from "./types.js";
+import { jobType } from "./xml.js";
+
+/** Fired after a job completes; purely observational. */
+export interface ActivityEvent {
+  workflowId: string;
+  type: string;
+  jobKey: string;
+  elementId: string;
+  /** For an imperative orchestrator turn: the journalled step key, or "__done". */
+  step?: string;
+}
+
+export interface WorkerOptions {
+  /** Provide a baseUrl (a client is created) or an existing client. */
+  baseUrl?: string;
+  client?: WorkflowClient;
+  workflows: Workflow[];
+  /** Worker name reported to the gateway. Default "nanobpm-workflow". */
+  name?: string;
+  /** Long-poll timeout per activation, ms. Also bounds stop() latency. Default 10000. */
+  pollTimeoutMs?: number;
+  /** Job lock timeout, ms. Default 30000. */
+  jobTimeoutMs?: number;
+  /** Backoff after a transport error, ms. Default 500. */
+  backoffMs?: number;
+  onActivity?: (e: ActivityEvent) => void | Promise<void>;
+  onError?: (err: Error, context: { type: string }) => void;
+}
+
+type Handler = (job: Job) => Promise<{ variables: JsonObject; step?: string }>;
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+export class Worker {
+  private readonly client: WorkflowClient;
+  private readonly name: string;
+  private readonly pollTimeoutMs: number;
+  private readonly jobTimeoutMs: number;
+  private readonly backoffMs: number;
+  private readonly onActivity?: WorkerOptions["onActivity"];
+  private readonly onError?: WorkerOptions["onError"];
+  /** job type → { workflowId, handle } */
+  private readonly routes = new Map<string, { workflowId: string; handle: Handler }>();
+  private running = false;
+  private loops: Promise<void>[] = [];
+
+  constructor(opts: WorkerOptions) {
+    this.client = opts.client ?? new WorkflowClient({ baseUrl: requireBaseUrl(opts) });
+    this.name = opts.name ?? "nanobpm-workflow";
+    this.pollTimeoutMs = opts.pollTimeoutMs ?? 10000;
+    this.jobTimeoutMs = opts.jobTimeoutMs ?? 30000;
+    this.backoffMs = opts.backoffMs ?? 500;
+    this.onActivity = opts.onActivity;
+    this.onError = opts.onError;
+    for (const wf of opts.workflows) this.register(wf);
+  }
+
+  private register(wf: Workflow): void {
+    if (wf.kind === "imperative") {
+      this.routes.set(wf.orchestrateType, {
+        workflowId: wf.id,
+        handle: async (job) => {
+          const input = (job.variables.input as JsonObject) ?? {};
+          const journal = (job.variables.journal as JsonObject) ?? {};
+          const step = await replayOnce(wf, input, journal);
+          if (step.done) return { variables: { wfDone: true } as JsonObject, step: "__done" };
+          const next = { ...journal, [step.frontier.key]: step.frontier.result };
+          return { variables: { journal: next, wfDone: false } as JsonObject, step: step.frontier.key };
+        },
+      });
+    } else {
+      for (const s of wf.steps) {
+        if (s.kind !== "run") continue;
+        const handler = wf.handlers[s.name];
+        this.routes.set(jobType(wf.id, s.name), {
+          workflowId: wf.id,
+          handle: async (job) => ({ variables: ((await handler(job)) ?? {}) as JsonObject }),
+        });
+      }
+    }
+  }
+
+  /** The derived job types this worker serves. */
+  get servedTypes(): string[] {
+    return [...this.routes.keys()];
+  }
+
+  /** Begin polling. Resolves once the loops are running (they run until stop()). */
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.loops = [...this.routes.entries()].map(([type, route]) => this.pollLoop(type, route));
+  }
+
+  /** Stop polling and wait for in-flight loops to unwind (≤ pollTimeoutMs). */
+  async stop(): Promise<void> {
+    this.running = false;
+    await Promise.all(this.loops);
+    this.loops = [];
+  }
+
+  private async pollLoop(type: string, route: { workflowId: string; handle: Handler }): Promise<void> {
+    while (this.running) {
+      let jobs: Job[] = [];
+      try {
+        jobs = await this.client.activateJobs(type, {
+          worker: this.name,
+          maxJobsToActivate: 1,
+          timeout: this.jobTimeoutMs,
+          requestTimeout: this.pollTimeoutMs,
+        });
+      } catch (e) {
+        // Transport/gateway error (e.g. engine restarting): back off, reconnect.
+        this.onError?.(e as Error, { type });
+        await sleep(this.backoffMs);
+        continue;
+      }
+      for (const job of jobs) {
+        if (!this.running) break;
+        try {
+          const { variables, step } = await route.handle(job);
+          await this.client.completeJob(job.jobKey, variables);
+          await this.onActivity?.({
+            workflowId: route.workflowId,
+            type,
+            jobKey: job.jobKey,
+            elementId: job.elementId,
+            step,
+          });
+        } catch (e) {
+          // A handler or completion failed. Report; the engine will redeliver the
+          // job after its lock times out (at-least-once → handlers must be
+          // idempotent). Best-effort surface it as an incident-worthy failure.
+          this.onError?.(e as Error, { type });
+          try {
+            await this.client.failJob(job.jobKey, (e as Error).message, 0);
+          } catch {
+            /* engine may be down; the lock will expire and redeliver */
+          }
+        }
+      }
+    }
+  }
+}
+
+function requireBaseUrl(opts: WorkerOptions): string {
+  if (!opts.baseUrl) throw new Error("Worker needs either options.client or options.baseUrl");
+  return opts.baseUrl;
+}

package/src/xml.ts

@@ -0,0 +1,35 @@
+// XML helpers + derived-name conventions shared by both model emitters.
+
+import type { Workflow } from "./types.js";
+
+export function escapeXml(s: string): string {
+  return String(s)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/** Derived job type for a declarative `run` step / imperative orchestrator. */
+export const jobType = (workflowId: string, step: string): string => `${workflowId}:${step}`;
+
+/** Derived message name for a declarative `signal` step. */
+export const messageName = (workflowId: string, step: string): string => `${workflowId}:${step}`;
+
+/** The single orchestrator job type of an imperative workflow. */
+export const orchestrateType = (workflowId: string): string => `${workflowId}:__orchestrate`;
+
+/** A BPMN identifier must be an NCName; validate derived ids fail fast. */
+const NCNAME = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+export function assertIdent(kind: string, value: string): void {
+  if (!NCNAME.test(value)) {
+    throw new Error(`${kind} "${value}" is not a valid BPMN identifier (expected an NCName)`);
+  }
+}
+
+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);
+  }
+}