@bpmnkit/core 0.0.8

package/dist/bpmn/bpmn-builder.d.ts

@@ -0,0 +1,381 @@
+import type { BpmnDefinitions, BpmnFlowElement, BpmnSequenceFlow } from "./bpmn-model.js";
+import type { RestConnectorConfig } from "./rest-connector.js";
+/** Options shared by all element methods. */
+export interface ElementOptions {
+    name?: string;
+}
+/** Options for creating a start event. */
+export interface StartEventOptions extends ElementOptions {
+    /** Timer duration (ISO 8601) — creates a timer start event. */
+    timerDuration?: string;
+    /** Timer date (ISO 8601) — creates a timer start event. */
+    timerDate?: string;
+    /** Timer cycle (ISO 8601) — creates a timer start event. */
+    timerCycle?: string;
+    /** Message name — creates a message start event. */
+    messageName?: string;
+    /** Zeebe properties (e.g. webhook connector config). */
+    zeebeProperties?: Array<{
+        name: string;
+        value: string;
+    }>;
+    /** Zeebe modeler template ID. */
+    modelerTemplate?: string;
+    /** Zeebe modeler template version. */
+    modelerTemplateVersion?: string;
+    /** Zeebe modeler template icon (data URI). */
+    modelerTemplateIcon?: string;
+}
+/** Options for creating a service task. */
+export interface ServiceTaskOptions {
+    /** Display name (required for BPMN canvas visibility). */
+    name: string;
+    /** Zeebe job type for this task. */
+    taskType: string;
+    /** Number of retries (defaults to "3"). */
+    retries?: string;
+    /** Input/output variable mappings. */
+    ioMapping?: {
+        inputs?: Array<{
+            source: string;
+            target: string;
+        }>;
+        outputs?: Array<{
+            source: string;
+            target: string;
+        }>;
+    };
+    /** Task header key-value pairs. */
+    taskHeaders?: Record<string, string>;
+    /** Zeebe modeler template ID. */
+    modelerTemplate?: string;
+    /** Zeebe modeler template version. */
+    modelerTemplateVersion?: string;
+    /** Zeebe modeler template icon (data URI). */
+    modelerTemplateIcon?: string;
+}
+/** Options for creating a script task. */
+export interface ScriptTaskOptions {
+    /** Display name. */
+    name?: string;
+    /** FEEL expression for the script. */
+    expression: string;
+    /** Variable name to store the result. */
+    resultVariable: string;
+}
+/** Options for creating a user task. */
+export interface UserTaskOptions {
+    /** Display name. */
+    name?: string;
+    /** Form key or form reference. */
+    formId?: string;
+}
+/** Options for creating a call activity. */
+export interface CallActivityOptions {
+    /** Display name. */
+    name?: string;
+    /** Process ID to call. */
+    processId: string;
+    /** Whether to propagate all child variables. */
+    propagateAllChildVariables?: boolean;
+}
+/** Options for creating a business rule task. */
+export interface BusinessRuleTaskOptions {
+    /** Display name. */
+    name?: string;
+    /** Zeebe job type. */
+    taskType?: string;
+    /** DMN decision ID to evaluate. */
+    decisionId?: string;
+    /** Variable to store the result. */
+    resultVariable?: string;
+}
+/** Options for gateway elements. */
+export interface GatewayOptions extends ElementOptions {
+    /** ID of the default sequence flow (set manually; prefer branch().defaultFlow()). */
+    defaultFlow?: string;
+}
+/** Options for an intermediate catch event. */
+export interface IntermediateCatchEventOptions extends ElementOptions {
+    /** Timer duration (ISO 8601) — creates a timer catch event. */
+    timerDuration?: string;
+    /** Timer date (ISO 8601) — creates a timer catch event that fires at a specific date/time. */
+    timerDate?: string;
+    /** Timer cycle (ISO 8601) — creates a recurring timer catch event. */
+    timerCycle?: string;
+    /** Message name — creates a message catch event (aspirational). */
+    messageName?: string;
+    /** Signal name — creates a signal catch event (aspirational). */
+    signalName?: string;
+}
+/** Options for an intermediate throw event. */
+export interface IntermediateThrowEventOptions extends ElementOptions {
+    /** Message name — creates a message throw event (aspirational). */
+    messageName?: string;
+    /** Signal name — creates a signal throw event (aspirational). */
+    signalName?: string;
+    /** Escalation code — creates an escalation throw event (aspirational). */
+    escalationCode?: string;
+}
+/** Options for a boundary event. */
+export interface BoundaryEventOptions extends ElementOptions {
+    /** ID of the activity this boundary event is attached to. */
+    attachedTo: string;
+    /** Whether the host activity is cancelled when the event triggers (default true). */
+    cancelActivity?: boolean;
+    /** Error code — creates an error boundary event. */
+    errorCode?: string;
+    /** Error reference ID. */
+    errorRef?: string;
+    /** Timer duration — creates a timer boundary event (aspirational). */
+    timerDuration?: string;
+    /** Timer date (ISO 8601) — creates a timer boundary event that fires at a specific date/time. */
+    timerDate?: string;
+    /** Timer cycle (ISO 8601) — creates a recurring timer boundary event. */
+    timerCycle?: string;
+    /** Message name — creates a message boundary event (aspirational). */
+    messageName?: string;
+    /** Signal name — creates a signal boundary event (aspirational). */
+    signalName?: string;
+}
+/** Multi-instance loop configuration. */
+export interface MultiInstanceOptions {
+    isSequential?: boolean;
+    collection?: string;
+    elementVariable?: string;
+    completionCondition?: string;
+}
+/** Options for sub-process elements. */
+export interface SubProcessOptions extends ElementOptions {
+    multiInstance?: MultiInstanceOptions;
+}
+/** Options for ad-hoc sub-process elements. */
+export interface AdHocSubProcessOptions extends ElementOptions {
+    /** FEEL expression for determining active elements. */
+    activeElementsCollection?: string;
+    /** Output collection for tool call results (agentic AI pattern). */
+    outputCollection?: string;
+    /** Output element FEEL expression (agentic AI pattern). */
+    outputElement?: string;
+    /** Zeebe task definition (agentic AI agent job worker). */
+    taskDefinition?: {
+        type: string;
+        retries?: string;
+    };
+    /** IO mapping for the ad-hoc sub-process. */
+    ioMapping?: {
+        inputs?: Array<{
+            source: string;
+            target: string;
+        }>;
+        outputs?: Array<{
+            source: string;
+            target: string;
+        }>;
+    };
+    /** Task header key-value pairs. */
+    taskHeaders?: Record<string, string>;
+    /** Multi-instance loop configuration. */
+    loopCharacteristics?: {
+        inputCollection: string;
+        inputElement?: string;
+        outputCollection?: string;
+        outputElement?: string;
+    };
+    multiInstance?: MultiInstanceOptions;
+    /** Zeebe modeler template ID. */
+    modelerTemplate?: string;
+    /** Zeebe modeler template version. */
+    modelerTemplateVersion?: string;
+    /** Zeebe modeler template icon (data URI). */
+    modelerTemplateIcon?: string;
+}
+/**
+ * Builder for a single named branch path from a gateway.
+ *
+ * Use `.condition(expr)` to set a FEEL condition on the outgoing sequence
+ * flow from the gateway, or `.defaultFlow()` to mark it as the default path.
+ */
+export declare class BranchBuilder {
+    /** @internal */
+    readonly _elements: BpmnFlowElement[];
+    /** @internal */
+    readonly _flows: BpmnSequenceFlow[];
+    /** @internal */
+    _defaultFlowId: string | undefined;
+    private lastNodeId;
+    private readonly gatewayId;
+    private readonly branchName;
+    private isFirstElement;
+    private pendingCondition;
+    private pendingDefault;
+    /** @internal – true once connectTo() has been called, meaning the branch end is already wired */
+    _connected: boolean;
+    /** @internal */
+    constructor(gatewayId: string, branchName: string);
+    /** Set a FEEL condition expression on this branch's outgoing sequence flow. */
+    condition(expression: string): this;
+    /** Mark this branch as the gateway's default (no-condition) flow. */
+    defaultFlow(): this;
+    private addElement;
+    /**
+     * Connect the current position to an existing or future element by ID.
+     * Supports forward references (element created later) and backward references (loops).
+     */
+    connectTo(targetId: string): this;
+    /** @internal – ID of the last element added (or the gateway if branch is empty) */
+    get _lastNodeId(): string;
+    serviceTask(id: string, options: ServiceTaskOptions): this;
+    userTask(id: string, options?: UserTaskOptions): this;
+    scriptTask(id: string, options: ScriptTaskOptions): this;
+    sendTask(id: string, options?: ElementOptions): this;
+    receiveTask(id: string, options?: ElementOptions): this;
+    businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
+    callActivity(id: string, options: CallActivityOptions): this;
+    startEvent(id?: string, options?: StartEventOptions): this;
+    endEvent(id?: string, options?: ElementOptions): this;
+    intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
+    intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions): this;
+    exclusiveGateway(id: string, options?: GatewayOptions): this;
+    parallelGateway(id: string, options?: ElementOptions): this;
+    inclusiveGateway(id: string, options?: GatewayOptions): this;
+    eventBasedGateway(id: string, options?: ElementOptions): this;
+}
+/** Builder for the contents of a sub-process or ad-hoc sub-process. */
+export declare class SubProcessContentBuilder {
+    /** @internal */
+    readonly _elements: BpmnFlowElement[];
+    /** @internal */
+    readonly _flows: BpmnSequenceFlow[];
+    private lastNodeId;
+    private addElement;
+    startEvent(id?: string, options?: StartEventOptions): this;
+    endEvent(id?: string, options?: ElementOptions): this;
+    serviceTask(id: string, options: ServiceTaskOptions): this;
+    userTask(id: string, options?: UserTaskOptions): this;
+    scriptTask(id: string, options: ScriptTaskOptions): this;
+    callActivity(id: string, options: CallActivityOptions): this;
+    intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
+    intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions): this;
+}
+/** Fluent builder for constructing BPMN processes. */
+export declare class ProcessBuilder {
+    private readonly processId;
+    private processName?;
+    private _isExecutable;
+    private _versionTag?;
+    private readonly flowElements;
+    private readonly sequenceFlows;
+    private readonly rootErrors;
+    private readonly rootMessages;
+    private lastNodeId;
+    private currentGatewayId;
+    private openBranchEnds;
+    private _autoLayout;
+    constructor(processId: string);
+    /** Enable auto-layout: `build()` will run the layout engine and populate diagram interchange data. */
+    withAutoLayout(): this;
+    /** Set the display name for this process. */
+    name(name: string): this;
+    /** Set whether this process is executable. */
+    executable(value: boolean): this;
+    /** Set the process version tag. */
+    versionTag(tag: string): this;
+    /** Add a start event. Start events never auto-connect from the previous element. */
+    startEvent(id?: string, options?: StartEventOptions): this;
+    /**
+     * Add a disconnected start event — begins a new parallel path in the process.
+     *
+     * Unlike `startEvent()` which continues from the current position,
+     * `addStartEvent()` clears the current position first so the start event
+     * is completely disconnected.
+     */
+    addStartEvent(id?: string, options?: StartEventOptions): this;
+    /** Add an end event. */
+    endEvent(id?: string, options?: ElementOptions): this;
+    /** Add an intermediate throw event (none, message, signal, escalation). */
+    intermediateThrowEvent(id?: string, options?: IntermediateThrowEventOptions): this;
+    /** Add an intermediate catch event (timer, message, signal). */
+    intermediateCatchEvent(id?: string, options?: IntermediateCatchEventOptions): this;
+    /**
+     * Add a boundary event attached to an existing activity.
+     *
+     * Boundary events do not auto-connect from the previous element.
+     * They start a new outgoing chain from the boundary event itself.
+     */
+    boundaryEvent(id: string, options: BoundaryEventOptions): this;
+    /** Add a service task with Zeebe task definition and optional IO mappings. */
+    serviceTask(id: string, options: ServiceTaskOptions): this;
+    /** Add a REST connector task — syntactic sugar over `serviceTask()`. */
+    restConnector(id: string, config: RestConnectorConfig): this;
+    /** Add a script task with a FEEL expression. */
+    scriptTask(id: string, options: ScriptTaskOptions): this;
+    /** Add a user task with optional form reference. */
+    userTask(id: string, options?: UserTaskOptions): this;
+    /** Add a send task (aspirational). */
+    sendTask(id: string, options?: ElementOptions): this;
+    /** Add a receive task (aspirational). */
+    receiveTask(id: string, options?: ElementOptions): this;
+    /** Add a business rule task. */
+    businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
+    /** Add a call activity referencing another process. */
+    callActivity(id: string, options: CallActivityOptions): this;
+    /** Add an exclusive gateway (XOR split/join). */
+    exclusiveGateway(id: string, options?: GatewayOptions): this;
+    /** Add a parallel gateway (AND split/join). */
+    parallelGateway(id: string, options?: ElementOptions): this;
+    /** Add an inclusive gateway (OR split/join). Aspirational. */
+    inclusiveGateway(id: string, options?: GatewayOptions): this;
+    /** Add an event-based gateway. Aspirational. */
+    eventBasedGateway(id: string, options?: ElementOptions): this;
+    /**
+     * Create a named branch from the current gateway.
+     *
+     * Each branch receives a {@link BranchBuilder} whose chain starts from
+     * the gateway. Use `.condition(expr)` or `.defaultFlow()` to configure
+     * the outgoing sequence flow, then chain flow-node methods, and finish
+     * with `.connectTo(targetId)` to merge into another element.
+     *
+     * @example
+     * ```ts
+     * .exclusiveGateway("check")
+     * .branch("yes", b => b.condition("= ok").serviceTask("do", { taskType: "x" }).connectTo("merge"))
+     * .branch("no", b => b.defaultFlow().serviceTask("fail", { taskType: "y" }).connectTo("merge"))
+     * .exclusiveGateway("merge")
+     * .endEvent("end")
+     * ```
+     */
+    branch(name: string, callback: (b: BranchBuilder) => void): this;
+    /** Connect the current position to an existing or future element by ID. */
+    connectTo(targetId: string): this;
+    /**
+     * Position the builder at an existing element, allowing additional
+     * outgoing flows from any point in the graph.
+     *
+     * @throws If no element with the given ID exists.
+     */
+    element(elementId: string): this;
+    /** Add an ad-hoc sub-process with optional AI agent or multi-instance configuration. */
+    adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
+    /** Add a sub-process (aspirational). */
+    subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
+    /** Add an event sub-process (aspirational). */
+    eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
+    /**
+     * Build the complete BPMN definitions model.
+     *
+     * Resolves all forward-referenced `incoming` / `outgoing` arrays and wraps
+     * the process in a {@link BpmnDefinitions} ready for XML serialization.
+     */
+    build(): BpmnDefinitions;
+    private buildDiagram;
+    /**
+     * Insert matching join gateways where split-gateway branches converge
+     * on a non-gateway target. BPMN best practice: every split has a join.
+     */
+    private insertJoinGateways;
+    /** Trace backward from a node to find which split gateway it belongs to. */
+    private traceBackToSplit;
+    private addFlowElement;
+}
+//# sourceMappingURL=bpmn-builder.d.ts.map