@bpmnkit/core 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -44,27 +44,107 @@ pnpm add @bpmnkit/core
44
44
 
45
45
  ### Build a process from code
46
46
 
47
+ Every element takes `(id, options)`. Branches off a gateway are declared with
48
+ `.branch()`, not by wiring flows by hand — the builder creates the sequence flows.
49
+
47
50
  ```typescript
48
51
  import { Bpmn } from "@bpmnkit/core"
49
52
 
50
- const process = Bpmn.createProcess("order-flow", "Order Flow")
51
- .startEvent("start", "Order Received")
52
- .serviceTask("validate", "Validate Order", {
53
- type: "order-validator",
54
- inputs: [{ source: "=order", target: "order" }],
55
- outputs: [{ source: "=valid", target: "isValid" }],
53
+ const defs = Bpmn.createProcess("order-flow")
54
+ .name("Order Flow")
55
+ .startEvent("start", { name: "Order Received" })
56
+ .serviceTask("validate", {
57
+ name: "Validate Order",
58
+ taskType: "order-validator",
59
+ ioMapping: {
60
+ inputs: [{ source: "=order", target: "order" }],
61
+ outputs: [{ source: "=valid", target: "isValid" }],
62
+ },
56
63
  })
57
- .exclusiveGateway("check", "Order Valid?")
58
- .sequenceFlow("check", "fulfill", "=isValid = true")
59
- .serviceTask("fulfill", "Fulfill Order", { type: "fulfillment-service" })
60
- .endEvent("end", "Order Complete")
61
- .sequenceFlow("check", "reject", "=isValid = false")
62
- .endEvent("reject-end", "Order Rejected")
64
+ .exclusiveGateway("check", { name: "Order Valid?" })
65
+ .branch("valid", (b) =>
66
+ b
67
+ .condition("=isValid = true")
68
+ .serviceTask("fulfill", { name: "Fulfill Order", taskType: "fulfillment-service" })
69
+ .endEvent("end", { name: "Order Complete" }),
70
+ )
71
+ .branch("invalid", (b) =>
72
+ b.defaultFlow().endEvent("reject-end", { name: "Order Rejected" }),
73
+ )
74
+ .withAutoLayout()
63
75
  .build()
64
76
 
65
- const xml = Bpmn.export(process)
77
+ const xml = Bpmn.export(defs)
78
+ ```
79
+
80
+ ### Sub-processes, boundary events and multi-instance
81
+
82
+ These are the constructs most often reached for and most often guessed at, so the
83
+ exact shapes are worth stating. `subProcess` takes its body as a **callback**
84
+ (second argument) and options third. A boundary event needs the id of the activity
85
+ it attaches to; `withBoundary` supplies it from the preceding activity for you.
86
+
87
+ ```typescript
88
+ import { Bpmn } from "@bpmnkit/core"
89
+
90
+ const defs = Bpmn.createProcess("fulfilment")
91
+ .name("Fulfilment")
92
+ .startEvent("start")
93
+
94
+ // Sub-process: id, content callback, then options.
95
+ // multiInstance runs the body once per item in the collection.
96
+ .subProcess(
97
+ "provision",
98
+ (sub) => {
99
+ sub
100
+ .startEvent("p-start")
101
+ .serviceTask("provision-line", { name: "Provision Line", taskType: "provision" })
102
+ .endEvent("p-end")
103
+ },
104
+ {
105
+ name: "Provision Each Line",
106
+ multiInstance: { collection: "=order.lines", elementVariable: "line", isSequential: false },
107
+ },
108
+ )
109
+
110
+ // withBoundary attaches to the activity just added — no id repeated.
111
+ .serviceTask("charge", { name: "Charge Payment", taskType: "payment" })
112
+ .withBoundary("charge-failed", { errorCode: "PAYMENT_FAILED" }, (b) => {
113
+ b.serviceTask("retry-charge", { name: "Retry Charge", taskType: "payment" }).endEvent("gave-up")
114
+ })
115
+
116
+ // Wait for whichever event arrives first.
117
+ .eventBasedGateway("await-payment", { name: "Paid?" })
118
+ .branch("paid", (b) =>
119
+ b
120
+ .intermediateCatchEvent("payment-confirmed", {
121
+ messageName: "PaymentConfirmed",
122
+ correlationKey: "=orderId",
123
+ })
124
+ .endEvent("done"),
125
+ )
126
+ .branch("timeout", (b) =>
127
+ b.intermediateCatchEvent("payment-timeout", { timerDuration: "P14D" }).endEvent("written-off"),
128
+ )
129
+ .withAutoLayout()
130
+ .build()
66
131
  ```
67
132
 
133
+ Attach a boundary event explicitly when it is not the preceding activity — both
134
+ forms below are accepted, and a boundary event with no host throws rather than
135
+ exporting BPMN that cannot be read back:
136
+
137
+ ```typescript
138
+ .boundaryEvent("timeout", { attachedTo: "charge", timerDuration: "PT30M" })
139
+ .boundaryEvent("timeout", "charge", { timerDuration: "PT30M" })
140
+ ```
141
+
142
+ Event definitions are named options, not nested objects — `timerDuration`,
143
+ `timerDate`, `timerCycle`, `messageName` (with `correlationKey`),
144
+ `errorCode`, `signalName`, `compensation`. An option the builder does not
145
+ know is dropped silently, so `timer: { duration: "P7D" }` produces a boundary
146
+ event with no timer on it.
147
+
68
148
  ### Parse and modify existing BPMN
69
149
 
70
150
  ```typescript
@@ -85,12 +165,10 @@ const updated = Bpmn.export(defs)
85
165
  ### Auto-layout a process
86
166
 
87
167
  ```typescript
88
- import { Bpmn, layoutProcess } from "@bpmnkit/core"
168
+ import { applyAutoLayout, Bpmn } from "@bpmnkit/core"
89
169
 
90
- const defs = Bpmn.parse(xml)
91
- const result = layoutProcess(defs.processes[0])
92
- // result.defs now has updated DI coordinates
93
- const laid = Bpmn.export(result.defs)
170
+ // Lays out every process and writes the diagram interchange back onto the model.
171
+ const laid = Bpmn.export(applyAutoLayout(Bpmn.parse(xml)))
94
172
  ```
95
173
 
96
174
  ### Optimize a diagram
@@ -135,10 +213,40 @@ const outXml = Bpmn.export(restored)
135
213
  |--------|-------------|
136
214
  | `Bpmn.parse(xml)` | Parse BPMN XML → `BpmnDefinitions` |
137
215
  | `Bpmn.export(defs)` | Serialize `BpmnDefinitions` → XML |
138
- | `Bpmn.createProcess(id, name?)` | Start a `ProcessBuilder` |
216
+ | `Bpmn.createProcess(id)` | Start a `ProcessBuilder`; set the name with `.name(…)` |
139
217
  | `Bpmn.makeEmpty(processId?, name?)` | Minimal BPMN XML with one start event |
140
218
  | `Bpmn.SAMPLE_XML` | 3-node sample diagram string |
141
219
 
220
+ ### Process builder
221
+
222
+ Every element method is `(id, options)` and returns the builder. The same methods
223
+ exist inside `.branch()` and inside a sub-process body.
224
+
225
+ | Method | Description |
226
+ |--------|-------------|
227
+ | `.name(name)` / `.versionTag(v)` | Process-level metadata |
228
+ | `.startEvent(id?, options?)` / `.endEvent(id?, options?)` | Events; `options.name` labels them |
229
+ | `.serviceTask(id, { taskType, ioMapping?, taskHeaders? })` | Zeebe job worker task |
230
+ | `.userTask(id, opts)` / `.businessRuleTask(id, { decisionRef })` / `.scriptTask(id, opts)` | Other task types |
231
+ | `.receiveTask(id, { message })` / `.sendTask(id, opts)` / `.callActivity(id, opts)` | Message and call activities |
232
+ | `.restConnector(id, { method, url, … })` | Camunda 8 HTTP connector task |
233
+ | `.exclusiveGateway(id, opts)` / `.parallelGateway` / `.inclusiveGateway` / `.eventBasedGateway` | Gateways |
234
+ | `.branch(name, b => …)` | One path off the preceding gateway |
235
+ | `b.condition(feel)` / `b.defaultFlow()` | Mark a branch's condition, or make it the default |
236
+ | `.connectTo(id)` | Flow to an existing or later element — merges and loops |
237
+ | `.subProcess(id, content, options?)` | Embedded sub-process; `content` is a callback |
238
+ | `.transaction(id, content, options?)` / `.eventSubProcess` / `.adHocSubProcess` | Other containers |
239
+ | `.withBoundary(id, options, handler)` | Boundary event on the preceding activity, plus its path |
240
+ | `.boundaryEvent(id, options)` | Boundary event naming its host in `options.attachedTo` |
241
+ | `.intermediateCatchEvent(id, opts)` / `.intermediateThrowEvent(id, opts)` | Intermediate events |
242
+ | `.withAutoLayout()` | Compute coordinates on `build()` — no x/y by hand |
243
+ | `.build()` | Produce `BpmnDefinitions`; pass to `Bpmn.export` |
244
+
245
+ Event definitions are options on the element: `timerDuration`, `timerDate`,
246
+ `timerCycle`, `messageName` + `correlationKey`, `errorCode`, `signalName`,
247
+ `compensation`. Multi-instance is `options.multiInstance =
248
+ { collection, elementVariable, isSequential? }`.
249
+
142
250
  ### Semantics
143
251
 
144
252
  | Export | Description |
@@ -219,6 +327,7 @@ const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
219
327
  | [`@bpmnkit/patterns`](https://www.npmjs.com/package/@bpmnkit/patterns) | Domain process patterns for BPMNKit AIKit |
220
328
  | [`@bpmnkit/reebe-wasm`](https://www.npmjs.com/package/@bpmnkit/reebe-wasm) | WebAssembly BPMN engine for browser simulation |
221
329
  | [`@bpmnkit/worker-client`](https://www.npmjs.com/package/@bpmnkit/worker-client) | Thin Zeebe REST client for standalone workers |
330
+ | [`@bpmnkit/user-tasks`](https://www.npmjs.com/package/@bpmnkit/user-tasks) | Embeddable user task widget for Camunda 8 |
222
331
  | [`@bpmnkit/cli-sdk`](https://www.npmjs.com/package/@bpmnkit/cli-sdk) | Plugin authoring SDK for the casen CLI |
223
332
  | [`@bpmnkit/create-casen-plugin`](https://www.npmjs.com/package/@bpmnkit/create-casen-plugin) | Scaffold a new casen CLI plugin in seconds |
224
333
  | [`@bpmnkit/casen-report`](https://www.npmjs.com/package/@bpmnkit/casen-report) | HTML reports from Camunda 8 incident and SLA data |
@@ -388,6 +388,8 @@ export declare class BranchBuilder {
388
388
  receiveTask(id: string, options?: MessageTaskOptions): this;
389
389
  businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
390
390
  callActivity(id: string, options: CallActivityOptions): this;
391
+ /** Add a manual task — work performed outside the engine, with no job worker. */
392
+ manualTask(id: string, options?: ElementOptions): this;
391
393
  /** Add an abstract task with no Zeebe extensions. */
392
394
  task(id: string, options?: ElementOptions): this;
393
395
  startEvent(id?: string, options?: StartEventOptions): this;
@@ -398,6 +400,7 @@ export declare class BranchBuilder {
398
400
  parallelGateway(id: string, options?: ElementOptions): this;
399
401
  inclusiveGateway(id: string, options?: GatewayOptions): this;
400
402
  eventBasedGateway(id: string, options?: ElementOptions): this;
403
+ complexGateway(id: string, options?: GatewayOptions): this;
401
404
  /**
402
405
  * Add a boundary event attached to an existing activity in this branch.
403
406
  *
@@ -406,7 +409,7 @@ export declare class BranchBuilder {
406
409
  * subsequent elements chain from it. Use `withBoundary()` if you want the
407
410
  * cursor to return to the task afterward.
408
411
  */
409
- boundaryEvent(id: string, options: BoundaryEventOptions): this;
412
+ boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">): this;
410
413
  /**
411
414
  * Attach a boundary event to the preceding task and build its outgoing path,
412
415
  * then restore the branch cursor to the preceding task so the main branch flow continues.
@@ -418,7 +421,16 @@ export declare class BranchBuilder {
418
421
  withBoundary(id: string, options: Omit<BoundaryEventOptions, "attachedTo">, handler: (b: BranchBuilder) => void): this;
419
422
  /** Add a sub-process (mirrors `ProcessBuilder.subProcess`). */
420
423
  subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
421
- /** Add an ad-hoc sub-process (mirrors `ProcessBuilder.adHocSubProcess`). */
424
+ /** Add a transaction sub-process (mirrors `ProcessBuilder.transaction`). */
425
+ transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
426
+ /**
427
+ * Add an ad-hoc sub-process (mirrors `ProcessBuilder.adHocSubProcess`).
428
+ *
429
+ * Its children are **not** auto-chained: BPMN defines them as an unordered set
430
+ * of independently-invocable activities, and Camunda 8 reads a child with an
431
+ * incoming flow as part of an internal sub-flow rather than an LLM-invocable
432
+ * tool. Use `connectTo()` inside the callback to state ordering you do want.
433
+ */
422
434
  adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
423
435
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
424
436
  eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
@@ -448,8 +460,20 @@ export declare class SubProcessContentBuilder {
448
460
  private currentGatewayId;
449
461
  private openBranchEnds;
450
462
  private readonly rootMessages;
463
+ /**
464
+ * Whether sequential calls chain themselves with sequence flows.
465
+ *
466
+ * False inside an ad-hoc sub-process, whose children BPMN defines as an
467
+ * unordered set of independently-invocable activities. Chaining them there is
468
+ * not merely redundant: Camunda 8 reads a child *with* an incoming flow as
469
+ * part of an internal sub-flow rather than an LLM-invocable tool, so the
470
+ * fabricated flows silently turned a three-tool agent into one tool and a
471
+ * two-step sub-flow. Ordering inside such a container is stated explicitly
472
+ * with `connectTo()`.
473
+ */
474
+ private readonly autoConnect;
451
475
  /** @internal */
452
- constructor(rootMessages?: BpmnMessage[]);
476
+ constructor(rootMessages?: BpmnMessage[], autoConnect?: boolean);
453
477
  private addElement;
454
478
  /**
455
479
  * Add an element with no sequence-flow wiring and no cursor movement.
@@ -471,12 +495,15 @@ export declare class SubProcessContentBuilder {
471
495
  callActivity(id: string, options: CallActivityOptions): this;
472
496
  sendTask(id: string, options?: MessageTaskOptions): this;
473
497
  receiveTask(id: string, options?: MessageTaskOptions): this;
498
+ /** Add a manual task — work performed outside the engine, with no job worker. */
499
+ manualTask(id: string, options?: ElementOptions): this;
474
500
  /** Add an abstract task with no Zeebe extensions. */
475
501
  task(id: string, options?: ElementOptions): this;
476
502
  exclusiveGateway(id: string, options?: GatewayOptions): this;
477
503
  parallelGateway(id: string, options?: ElementOptions): this;
478
504
  inclusiveGateway(id: string, options?: GatewayOptions): this;
479
505
  eventBasedGateway(id: string, options?: ElementOptions): this;
506
+ complexGateway(id: string, options?: GatewayOptions): this;
480
507
  /** Attach a text annotation to the element at the current cursor position. */
481
508
  textAnnotation(text: string): this;
482
509
  /** Attach a text annotation to an element by explicit ID. */
@@ -492,7 +519,7 @@ export declare class SubProcessContentBuilder {
492
519
  * subsequent elements chain from it. Use `withBoundary()` if you want the
493
520
  * cursor to return to the task afterward.
494
521
  */
495
- boundaryEvent(id: string, options: BoundaryEventOptions): this;
522
+ boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">): this;
496
523
  /**
497
524
  * Attach a boundary event to the preceding task and build its outgoing path,
498
525
  * then restore the builder cursor to the preceding task so the main flow continues.
@@ -504,7 +531,16 @@ export declare class SubProcessContentBuilder {
504
531
  withBoundary(id: string, options: Omit<BoundaryEventOptions, "attachedTo">, handler: (b: SubProcessContentBuilder) => void): this;
505
532
  /** Add a sub-process nested inside this sub-process's content. */
506
533
  subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
507
- /** Add an ad-hoc sub-process nested inside this sub-process's content. */
534
+ /** Add a transaction sub-process nested inside this sub-process's content. */
535
+ transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
536
+ /**
537
+ * Add an ad-hoc sub-process nested inside this sub-process's content.
538
+ *
539
+ * Its children are **not** auto-chained: BPMN defines them as an unordered set
540
+ * of independently-invocable activities, and Camunda 8 reads a child with an
541
+ * incoming flow as part of an internal sub-flow rather than an LLM-invocable
542
+ * tool. Use `connectTo()` inside the callback to state ordering you do want.
543
+ */
508
544
  adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
509
545
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
510
546
  eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
@@ -614,6 +650,61 @@ export declare class ProcessBuilder {
614
650
  executable(value: boolean): this;
615
651
  /** Set the process version tag. */
616
652
  versionTag(tag: string): this;
653
+ /**
654
+ * Declares the root `bpmn:message` for a message name, with the id you choose.
655
+ *
656
+ * Events name messages by name — `{ messageName: "Order Received" }` — and the
657
+ * builder declares one on first use, deriving its id from that name. Call this
658
+ * first when the id itself matters, typically because something outside this
659
+ * process already refers to it.
660
+ *
661
+ * @param id - The message's element id, used verbatim.
662
+ * @throws If a message with this name is already declared under another id,
663
+ * which the events built before this call already point at.
664
+ * @example
665
+ * ```typescript
666
+ * Bpmn.createProcess("orders")
667
+ * .message("Msg_OrderReceived", { name: "Order Received" })
668
+ * .startEvent("start", { messageName: "Order Received" })
669
+ * ```
670
+ */
671
+ message(id: string, options: {
672
+ name: string;
673
+ }): this;
674
+ /**
675
+ * Declares the root `bpmn:error` for an error code, with the id you choose.
676
+ *
677
+ * @param id - The error's element id, used verbatim.
678
+ * @param options - The `code` events match on, and the display `name`, which
679
+ * defaults to the code.
680
+ * @throws If this code is already declared under another id.
681
+ */
682
+ error(id: string, options: {
683
+ code: string;
684
+ name?: string;
685
+ }): this;
686
+ /**
687
+ * Declares the root `bpmn:signal` for a signal name, with the id you choose.
688
+ *
689
+ * @param id - The signal's element id, used verbatim.
690
+ * @throws If this name is already declared under another id.
691
+ */
692
+ signal(id: string, options: {
693
+ name: string;
694
+ }): this;
695
+ /**
696
+ * Declares the root `bpmn:escalation` for an escalation code, with the id you
697
+ * choose.
698
+ *
699
+ * @param id - The escalation's element id, used verbatim.
700
+ * @param options - The `code` events match on, and the display `name`, which
701
+ * defaults to the code.
702
+ * @throws If this code is already declared under another id.
703
+ */
704
+ escalation(id: string, options: {
705
+ code: string;
706
+ name?: string;
707
+ }): this;
617
708
  /** Add a start event. Start events never auto-connect from the previous element. */
618
709
  startEvent(id?: string, options?: StartEventOptions): this;
619
710
  /**
@@ -642,7 +733,7 @@ export declare class ProcessBuilder {
642
733
  * Boundary events do not auto-connect from the previous element.
643
734
  * They start a new outgoing chain from the boundary event itself.
644
735
  */
645
- boundaryEvent(id: string, options: BoundaryEventOptions): this;
736
+ boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">): this;
646
737
  /**
647
738
  * Attach a boundary event to the preceding task and build its outgoing path,
648
739
  * then restore the builder cursor to the preceding task so the main flow continues.
@@ -668,6 +759,8 @@ export declare class ProcessBuilder {
668
759
  businessRuleTask(id: string, options?: BusinessRuleTaskOptions): this;
669
760
  /** Add a call activity referencing another process. */
670
761
  callActivity(id: string, options: CallActivityOptions): this;
762
+ /** Add a manual task — work performed outside the engine, with no job worker. */
763
+ manualTask(id: string, options?: ElementOptions): this;
671
764
  /** Add an abstract task with no Zeebe extensions. */
672
765
  task(id: string, options?: ElementOptions): this;
673
766
  /** Add an exclusive gateway (XOR split/join). */
@@ -678,6 +771,8 @@ export declare class ProcessBuilder {
678
771
  inclusiveGateway(id: string, options?: GatewayOptions): this;
679
772
  /** Add an event-based gateway. Aspirational. */
680
773
  eventBasedGateway(id: string, options?: ElementOptions): this;
774
+ /** Add a complex gateway. Aspirational — Zeebe does not execute these. */
775
+ complexGateway(id: string, options?: GatewayOptions): this;
681
776
  /**
682
777
  * Create a named branch from the current gateway.
683
778
  *
@@ -705,10 +800,19 @@ export declare class ProcessBuilder {
705
800
  * @throws If no element with the given ID exists.
706
801
  */
707
802
  element(elementId: string): this;
708
- /** Add an ad-hoc sub-process with optional AI agent or multi-instance configuration. */
803
+ /**
804
+ * Add an ad-hoc sub-process with optional AI agent or multi-instance configuration.
805
+ *
806
+ * Its children are **not** auto-chained: BPMN defines them as an unordered set
807
+ * of independently-invocable activities, and Camunda 8 reads a child with an
808
+ * incoming flow as part of an internal sub-flow rather than an LLM-invocable
809
+ * tool. Use `connectTo()` inside the callback to state ordering you do want.
810
+ */
709
811
  adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
710
812
  /** Add a sub-process (aspirational). */
711
813
  subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
814
+ /** Add a transaction sub-process — a sub-process with atomic semantics. */
815
+ transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
712
816
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
713
817
  eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
714
818
  /** Attach a text annotation to the element at the current cursor position. */