@nanobpm/workflow 0.8.1 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @nanobpm/workflow
 
-Code-first durable orchestration for [nanobpmn](https://github.com/Magikcraft/nano-bpm)
+Code-first durable orchestration for [nanobpmn](https://nanobpm.io)
 (**ADR 0044**). Author durable workflows as ordinary async code; the SDK derives
 the executable BPMN model, the job types, and the message/correlation wiring, and
 hosts a generic worker. No diagram, no task-type wiring, no correlation plumbing

package/dist/declarative.d.ts

@@ -1,20 +1,21 @@
-import type { DeclarativeFlow, FlowContracts, FlowNode, JsonObject } from "./types.js";
+import type { DeclarativeFlow, FlowContracts, FlowNode, JsonObject, NodeEnvelopes, StepHandler, TimerStart } from "./types.js";
 import type { Envelope } from "./envelope.js";
+import "./nodes/index.js";
 /** The TS payload type of a contract's input envelope (untyped fallback). */
-type InPayload<Ct> = Ct extends {
+export type InPayload<Ct> = Ct extends {
     in: Envelope;
 } ? Ct["in"]["type"] & JsonObject : JsonObject;
 /** The TS payload type of a contract's output envelope (untyped fallback). */
-type OutPayload<Ct> = Ct extends {
+export type OutPayload<Ct> = Ct extends {
     out: Envelope;
 } ? Ct["out"]["type"] & JsonObject : JsonObject;
 /** The input payload type of step `K` under contracts `C`. */
-type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
+export type VarsOf<C, K extends string> = K extends keyof C ? InPayload<C[K]> : JsonObject;
 /** The output payload type of step `K` under contracts `C`. */
-type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : JsonObject;
+export type ResultOf<C, K extends string> = K extends keyof C ? OutPayload<C[K]> : JsonObject;
 /** A typed handler for a `run` step: its job variables and result are resolved
  *  from the flow contracts by the step name. */
-type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
+export type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
     jobKey: string;
     processInstanceKey: string;
     elementId: string;
@@ -22,7 +23,7 @@ type TypedHandler<V extends JsonObject, R extends JsonObject> = (job: {
     variables: V;
 }) => Promise<R | void> | R | void;
 /** A block: the callback that populates a nested body (a case, arm, or loop). */
-type Block<C extends object> = (b: FlowBuilder<C>) => void;
+export type Block<C extends object = object> = (b: FlowBuilder<C>) => void;
 /** The typed builder for a flow body.
  *
  * `C` is the flow's contracts map (step name → `{ in, out }` envelopes). The
@@ -157,6 +158,62 @@ export interface FlowBuilder<C extends object = object> {
      *  the body. Only valid inside a `loop`. */
     continue(): FlowBuilder<C>;
 }
+/** A builder method as stored on the dynamically-assembled builder. Its precise,
+ *  generic user-facing signature comes from the `FlowBuilder<C>` interface (a
+ *  built-in method declared centrally, a slice method declaration-merged from
+ *  its module); this loose shape is only what the registry stores/installs. */
+export type BuilderMethod = (...args: never[]) => unknown;
+/** The per-body authoring context a kind module's `build` factory closes over to
+ *  implement its builder method. Everything a method needs to append its node —
+ *  claim its step name, resolve contract envelopes, recurse into nested bodies,
+ *  and return the builder for chaining — without reaching into `declarative.ts`
+ *  internals or the shared `FlowNode` union. */
+export interface BuildApi {
+    /** The flow id (for error messages). */
+    readonly id: string;
+    /** Whether this is the root (top-level) builder — e.g. `startOn` is root-only. */
+    readonly isRoot: boolean;
+    /** The node list this builder appends to (`api.out.push(node)`). */
+    readonly out: FlowNode[];
+    /** The flow's typed I/O contracts, keyed by step name. */
+    readonly contracts: FlowContracts;
+    /** The flow's handler registry — a `run`-like kind registers its handler here. */
+    readonly handlers: Record<string, StepHandler>;
+    /** The current loop-nesting depth (0 outside any loop) — `break`/`continue`
+     *  guard on it. */
+    readonly loopDepth: number;
+    /** The builder itself, for chaining (`return api.self()`). */
+    self(): FlowBuilder;
+    /** Populate a nested body block, returning its node list. `inLoop` deepens the
+     *  loop nesting (a `loop` body); use it for bodies that can `break`/`continue`. */
+    child(fn: (b: FlowBuilder) => void, inLoop: boolean): FlowNode[];
+    /** Populate a nested body that runs in its OWN token scope (an embedded
+     *  sub-process): `break`/`continue` cannot cross the boundary (loop depth 0). */
+    childScoped(fn: (b: FlowBuilder) => void): FlowNode[];
+    /** Claim a step name (rejects duplicates / reserved ids), as every leaf does. */
+    claim(name: string): void;
+    /** Resolve the declared envelopes for a step name from the contracts. */
+    contractEnvelopes(name: string): {
+        in?: Envelope;
+        out?: Envelope;
+    } | undefined;
+    /** Lift a durable timer start onto the flow (used only by `startOn`). */
+    setStartTimer(t: TimerStart): void;
+}
+/** A dynamically-assembled builder satisfies `FlowBuilder<C>` once every core
+ *  built-in method is installed. The check is a runtime type guard (not an `as`
+ *  cast): each own-property must be a function, AND every built-in method in
+ *  {@link BUILTIN_BUILDER_METHODS} must be present — so a missing or
+ *  tree-shaken node-kind registration fails fast here at builder assembly (a
+ *  clear "missing registered methods" error) instead of surfacing later as an
+ *  opaque `w.run is not a function` at authoring time. */
+export declare function isFlowBuilder<C extends object = object>(x: object): x is FlowBuilder<C>;
+/** Diagnostic for a failed builder assembly. Names the missing built-in
+ *  method(s) when a registration was tree-shaken/omitted so the failure is
+ *  actionable; otherwise, when every built-in is present but some own-property
+ *  isn't a function, names that offending property instead. Exported (like
+ *  {@link isFlowBuilder}) so the assembly invariant is unit-testable. */
+export declare function assemblyFailureMessage(x: object): string;
 /**
  * Define a declarative flow. Pass a typed `contracts` map (keyed by step name)
  * to type each step's I/O and lift its data envelopes into the model; or omit it
@@ -164,8 +221,13 @@ export interface FlowBuilder<C extends object = object> {
  */
 export declare function defineFlow<C extends FlowContracts>(id: string, contracts: C, build: (w: FlowBuilder<C>) => void): DeclarativeFlow;
 export declare function defineFlow(id: string, build: (w: FlowBuilder) => void): DeclarativeFlow;
-/** Depth-first visit of every node in a flow tree (structural combinators
- *  recurse into their bodies). */
+/** Depth-first visit of every node in a flow tree. Recursion into a kind's
+ *  nested bodies is DISPATCHED through the registry (each kind's `walk` handler),
+ *  so a slice's structural combinator recurses without editing a central switch.
+ *  Fails fast (via `requireNodeKind`) on an unregistered kind — matching the
+ *  emitter — so a tree-shaken/missing registration surfaces as a clear error
+ *  rather than silently skipping recursion into that node's nested bodies. A
+ *  registered leaf kind with no `walk` handler is fine (nothing to recurse). */
 export declare function walkNodes(nodes: FlowNode[], visit: (n: FlowNode) => void): void;
 /** The job types of a flow's external `task` steps (anywhere in the tree) — the
  *  contract workers outside this program must subscribe to. Each is the derived
@@ -173,6 +235,106 @@ export declare function walkNodes(nodes: FlowNode[], visit: (n: FlowNode) => voi
  *  { jobType })`. Deduplicated (preserving first-seen order) since several steps
  *  may intentionally share one override token. */
 export declare function externalJobTypes(flow: DeclarativeFlow): string[];
+/** A renderable BPMN element the emitter has placed. A kind's `emit` handler
+ *  adds one (or more) via `api.addNode(...)` (or a typed helper like
+ *  `api.addServiceTask`). */
+export interface RenderNode {
+    id: string;
+    render(incoming: string[], outgoing: string[]): string;
+    /** For exclusive gateways: the flow id of the unconditional default edge. */
+    defaultFlow?: string;
+    /** Id of the embedded sub-process this node lives in, or undefined at the
+     *  top level (the root process). */
+    scope?: string;
+}
+/** A BPMN sequence flow being wired. A kind's `emit` handler creates danglers
+ *  with `api.newEdge(from)` and resolves them with `api.connect(edges, toId)`. */
+export interface Edge {
+    id: string;
+    from: string;
+    to?: string;
+    condition?: string;
+    name?: string;
+    /** The scope (sub-process id, or undefined = root process) this flow is
+     *  nested in — so it renders inside the right container. */
+    scope?: string;
+}
+/** The enclosing-loop context threaded through `emit`: `break`/`continue` route
+ *  to `headId`, and `break` danglers collect in `breaks`. `null` outside a loop. */
+export interface LoopCtx {
+    headId: string;
+    breaks: Edge[];
+}
+/** The emitter primitives a kind's `emit` handler uses to place its BPMN nodes
+ *  and wire its sequence flows — WITHOUT reaching into `Compiler` internals or a
+ *  central emit switch. Built-in kinds and slice-added kinds emit through this
+ *  same surface. Node-render string helpers (`incomingOutgoing`, `escapeXml`, …)
+ *  are exported alongside for building custom `RenderNode.render` closures. */
+export interface EmitApi {
+    /** The flow id (for error messages). */
+    readonly flowId: string;
+    /** Create a new (dangling) sequence flow from `from`; resolve its target with
+     *  `connect`. */
+    newEdge(from: string, opts?: {
+        condition?: string;
+        name?: string;
+    }): Edge;
+    /** Point every one of `incoming` at `toId`. */
+    connect(incoming: Edge[], toId: string): void;
+    /** Record a referenced data envelope so it is lifted to a `nano:shape`. */
+    recordEnvelope(env?: Envelope): void;
+    /** Emit a sequence of nodes, threading danglers; used to emit nested bodies. */
+    emitList(list: FlowNode[], incoming: Edge[], loop: LoopCtx | null): Edge[];
+    /** Place a fully custom BPMN element (a slice's own render closure). */
+    addNode(node: RenderNode): void;
+    /** Place a `<bpmn:serviceTask>` with the standard taskDefinition/envelope
+     *  extension elements (optionally with multi-instance characteristics). */
+    addServiceTask(node: {
+        name: string;
+        envelopes?: NodeEnvelopes;
+        jobType?: string;
+    }, mi?: string): void;
+    /** Place a `<bpmn:intermediateCatchEvent>` with a message event definition. */
+    addCatchEvent(node: {
+        name: string;
+    }): void;
+    /** Place a `<bpmn:intermediateCatchEvent>` with a timer event definition. */
+    addTimerCatchEvent(node: {
+        name: string;
+        after?: string;
+        at?: string;
+    }): void;
+    /** Place a `<bpmn:exclusiveGateway>`, returning it so `defaultFlow` can be set. */
+    addGateway(id: string, name?: string): RenderNode;
+    /** Place a `<bpmn:parallelGateway>`. */
+    addParallelGateway(id: string): RenderNode;
+    /** Place an embedded `<bpmn:subProcess>` whose body renders in its own scope. */
+    addSubProcess(id: string, mi: string): RenderNode;
+    /** Place a plain none `<bpmn:startEvent>` (for an embedded sub-process). */
+    addPlainStart(id: string): void;
+    /** Place a plain `<bpmn:endEvent>` (for an embedded sub-process). */
+    addPlainEnd(id: string): void;
+    /** A fresh monotonic counter value for generated gateway/loop/sub ids. */
+    nextGw(): number;
+    /** The current scope (enclosing sub-process id, or undefined at the top level). */
+    currentScope(): string | undefined;
+    /** Open a sub-process scope (subsequent nodes/edges nest inside it). */
+    pushScope(id: string): void;
+    /** Close the current sub-process scope. */
+    popScope(): void;
+}
 /** Derive an executable BPMN model from a declarative flow. */
 export declare function declarativeToBpmn(flow: DeclarativeFlow): string;
-export {};
+/** Wrap a raw FEEL expression as a Zeebe condition body (leading `=`). Exported
+ *  for slice-added combinators that emit conditional sequence flows. */
+export declare const feel: (expr: string) => string;
+/** A FEEL equality test `subject = "value"`, with the value as a FEEL string.
+ *  Exported for slice-added combinators that emit an XOR gateway. */
+export declare const feelEquals: (subject: string, value: string) => string;
+/** Render the `<bpmn:incoming>`/`<bpmn:outgoing>` refs of a flow node. Exported
+ *  for slice `RenderNode.render` closures. */
+export declare function incomingOutgoing(inc: string[], outg: string[]): string;
+/** Render only the `<bpmn:incoming>` refs (for end-like events). Exported. */
+export declare const incomingOnly: (inc: string[]) => string;
+/** Render only the `<bpmn:outgoing>` refs (for start-like events). Exported. */
+export declare const outgoingOnly: (outg: string[]) => string;