@bpmnkit/core 0.4.0 → 0.6.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 |
@@ -0,0 +1,21 @@
1
+ import type { BpmnDefinitions } from "./bpmn-model.js";
2
+ import type { CompactDiagram } from "./compact.js";
3
+ /**
4
+ * Rejects anything that is not a {@link CompactDiagram} before it reaches code
5
+ * that assumes one.
6
+ *
7
+ * @param value - The argument as given.
8
+ * @param fn - The public function the argument was passed to, for the message.
9
+ * @throws {TypeError} When `value` cannot be walked as a compact diagram.
10
+ */
11
+ export declare function assertCompactDiagram(value: unknown, fn: string): asserts value is CompactDiagram;
12
+ /**
13
+ * Rejects anything that is not a {@link BpmnDefinitions} before it reaches code
14
+ * that assumes one.
15
+ *
16
+ * @param value - The argument as given.
17
+ * @param fn - The public function the argument was passed to, for the message.
18
+ * @throws {TypeError} When `value` cannot be walked as a parsed model.
19
+ */
20
+ export declare function assertBpmnDefinitions(value: unknown, fn: string): asserts value is BpmnDefinitions;
21
+ //# sourceMappingURL=argument-guards.d.ts.map
@@ -0,0 +1,90 @@
1
+ /**
2
+ * Runtime shape checks for the two document types the editing APIs take.
3
+ *
4
+ * Both are ordinary typed parameters, so a caller reaching for the neighbouring
5
+ * API — `Bpmn.parse()` takes raw XML, `compactify()` takes a parsed model — used
6
+ * to get an internal `TypeError` naming a private field, or, with an empty
7
+ * operation list, their own input handed straight back as if the edit had run.
8
+ * That second case is the dangerous one: it reads as a pipeline that ran and
9
+ * preserved everything.
10
+ */
11
+ function isRecord(value) {
12
+ return typeof value === "object" && value !== null && !Array.isArray(value);
13
+ }
14
+ /** A compact process is walked through `elements` and `flows`. */
15
+ function isCompactProcess(value) {
16
+ return isRecord(value) && Array.isArray(value.elements) && Array.isArray(value.flows);
17
+ }
18
+ /** A full process is walked through `flowElements` and `sequenceFlows`. */
19
+ function isFullProcess(value) {
20
+ return isRecord(value) && Array.isArray(value.flowElements) && Array.isArray(value.sequenceFlows);
21
+ }
22
+ /** Names a non-object argument the way an error message wants to read. */
23
+ function describe(value) {
24
+ if (value === null)
25
+ return "null";
26
+ if (value === undefined)
27
+ return "undefined";
28
+ if (Array.isArray(value))
29
+ return "an array";
30
+ return `a ${typeof value}`;
31
+ }
32
+ /** Every process in a non-empty list has the other document's shape. */
33
+ function allProcessesAre(processes, shape) {
34
+ return processes.length > 0 && processes.every(shape);
35
+ }
36
+ function compactProblem(value) {
37
+ if (!isRecord(value)) {
38
+ const hint = typeof value === "string" ? " Pass compactify(Bpmn.parse(xml)) if you have raw XML." : "";
39
+ return `received ${describe(value)}.${hint}`;
40
+ }
41
+ if (!Array.isArray(value.processes))
42
+ return "received an object with no processes array.";
43
+ if (allProcessesAre(value.processes, isFullProcess))
44
+ return "received a BpmnDefinitions. Pass compactify(defs).";
45
+ const bad = value.processes.findIndex((process) => !isCompactProcess(process));
46
+ if (bad >= 0)
47
+ return `received one whose processes[${bad}] has no elements and flows arrays.`;
48
+ return undefined;
49
+ }
50
+ function definitionsProblem(value) {
51
+ if (!isRecord(value)) {
52
+ const hint = typeof value === "string" ? " Pass Bpmn.parse(xml) if you have raw XML." : "";
53
+ return `received ${describe(value)}.${hint}`;
54
+ }
55
+ if (!Array.isArray(value.processes))
56
+ return "received an object with no processes array.";
57
+ if (allProcessesAre(value.processes, isCompactProcess))
58
+ return "received a CompactDiagram. Pass the parsed model, not the compact projection.";
59
+ const bad = value.processes.findIndex((process) => !isFullProcess(process));
60
+ if (bad >= 0)
61
+ return `received one whose processes[${bad}] has no flowElements and sequenceFlows arrays.`;
62
+ return undefined;
63
+ }
64
+ /**
65
+ * Rejects anything that is not a {@link CompactDiagram} before it reaches code
66
+ * that assumes one.
67
+ *
68
+ * @param value - The argument as given.
69
+ * @param fn - The public function the argument was passed to, for the message.
70
+ * @throws {TypeError} When `value` cannot be walked as a compact diagram.
71
+ */
72
+ export function assertCompactDiagram(value, fn) {
73
+ const problem = compactProblem(value);
74
+ if (problem)
75
+ throw new TypeError(`${fn} expects a CompactDiagram, ${problem}`);
76
+ }
77
+ /**
78
+ * Rejects anything that is not a {@link BpmnDefinitions} before it reaches code
79
+ * that assumes one.
80
+ *
81
+ * @param value - The argument as given.
82
+ * @param fn - The public function the argument was passed to, for the message.
83
+ * @throws {TypeError} When `value` cannot be walked as a parsed model.
84
+ */
85
+ export function assertBpmnDefinitions(value, fn) {
86
+ const problem = definitionsProblem(value);
87
+ if (problem)
88
+ throw new TypeError(`${fn} expects a BpmnDefinitions, ${problem}`);
89
+ }
90
+ //# sourceMappingURL=argument-guards.js.map
@@ -409,7 +409,7 @@ export declare class BranchBuilder {
409
409
  * subsequent elements chain from it. Use `withBoundary()` if you want the
410
410
  * cursor to return to the task afterward.
411
411
  */
412
- boundaryEvent(id: string, options: BoundaryEventOptions): this;
412
+ boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">): this;
413
413
  /**
414
414
  * Attach a boundary event to the preceding task and build its outgoing path,
415
415
  * then restore the branch cursor to the preceding task so the main branch flow continues.
@@ -423,7 +423,14 @@ export declare class BranchBuilder {
423
423
  subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
424
424
  /** Add a transaction sub-process (mirrors `ProcessBuilder.transaction`). */
425
425
  transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
426
- /** Add an ad-hoc sub-process (mirrors `ProcessBuilder.adHocSubProcess`). */
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
+ */
427
434
  adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
428
435
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
429
436
  eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
@@ -453,8 +460,20 @@ export declare class SubProcessContentBuilder {
453
460
  private currentGatewayId;
454
461
  private openBranchEnds;
455
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;
456
475
  /** @internal */
457
- constructor(rootMessages?: BpmnMessage[]);
476
+ constructor(rootMessages?: BpmnMessage[], autoConnect?: boolean);
458
477
  private addElement;
459
478
  /**
460
479
  * Add an element with no sequence-flow wiring and no cursor movement.
@@ -500,7 +519,7 @@ export declare class SubProcessContentBuilder {
500
519
  * subsequent elements chain from it. Use `withBoundary()` if you want the
501
520
  * cursor to return to the task afterward.
502
521
  */
503
- boundaryEvent(id: string, options: BoundaryEventOptions): this;
522
+ boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">): this;
504
523
  /**
505
524
  * Attach a boundary event to the preceding task and build its outgoing path,
506
525
  * then restore the builder cursor to the preceding task so the main flow continues.
@@ -514,7 +533,14 @@ export declare class SubProcessContentBuilder {
514
533
  subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
515
534
  /** Add a transaction sub-process nested inside this sub-process's content. */
516
535
  transaction(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
517
- /** Add an ad-hoc sub-process nested inside this sub-process's content. */
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
+ */
518
544
  adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
519
545
  /** Add an event sub-process. Triggered by its start event — no incoming or outgoing sequence flows. */
520
546
  eventSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: ElementOptions): this;
@@ -707,7 +733,7 @@ export declare class ProcessBuilder {
707
733
  * Boundary events do not auto-connect from the previous element.
708
734
  * They start a new outgoing chain from the boundary event itself.
709
735
  */
710
- boundaryEvent(id: string, options: BoundaryEventOptions): this;
736
+ boundaryEvent(id: string, attachedToOrOptions: string | BoundaryEventOptions, maybeOptions?: Omit<BoundaryEventOptions, "attachedTo">): this;
711
737
  /**
712
738
  * Attach a boundary event to the preceding task and build its outgoing path,
713
739
  * then restore the builder cursor to the preceding task so the main flow continues.
@@ -774,7 +800,14 @@ export declare class ProcessBuilder {
774
800
  * @throws If no element with the given ID exists.
775
801
  */
776
802
  element(elementId: string): this;
777
- /** 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
+ */
778
811
  adHocSubProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: AdHocSubProcessOptions): this;
779
812
  /** Add a sub-process (aspirational). */
780
813
  subProcess(id: string, content: (b: SubProcessContentBuilder) => void, options?: SubProcessOptions): this;
@@ -1,3 +1,4 @@
1
+ import { ValidationError } from "../errors.js";
1
2
  import { generateId } from "../types/id-generator.js";
2
3
  import { applyAutoLayout } from "./auto-layout.js";
3
4
  import { createFlowElement } from "./element-shape.js";
@@ -441,6 +442,26 @@ function resolveSubProcessArgs(content, options) {
441
442
  }
442
443
  throw new TypeError("subProcess() requires a content callback function");
443
444
  }
445
+ /**
446
+ * `boundaryEvent` takes its host activity in `options.attachedTo`, but the
447
+ * positional shape `boundaryEvent(id, hostId, options)` reads just as naturally
448
+ * and is what callers reach for when they have only seen the parameter names.
449
+ * Accept both, for the same reason `resolveSubProcessArgs` accepts a reversed
450
+ * pair: the alternative was emitting a boundary event with no `attachedToRef`,
451
+ * which is invalid BPMN that this library's own parser then refuses to read.
452
+ *
453
+ * A missing host is a genuine error rather than a shape to guess at, so it
454
+ * throws here — at the call that caused it — instead of at export time.
455
+ */
456
+ function resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions) {
457
+ const options = typeof attachedToOrOptions === "string"
458
+ ? { ...maybeOptions, attachedTo: attachedToOrOptions }
459
+ : attachedToOrOptions;
460
+ if (typeof options?.attachedTo !== "string" || options.attachedTo === "") {
461
+ throw new ValidationError(`boundaryEvent("${id}") requires the id of the activity it attaches to. Pass it as options.attachedTo, as boundaryEvent("${id}", hostId, options), or use withBoundary() to attach to the preceding activity.`);
462
+ }
463
+ return options;
464
+ }
444
465
  /**
445
466
  * Build a transaction element from a content callback.
446
467
  *
@@ -828,7 +849,8 @@ export class BranchBuilder {
828
849
  * subsequent elements chain from it. Use `withBoundary()` if you want the
829
850
  * cursor to return to the task afterward.
830
851
  */
831
- boundaryEvent(id, options) {
852
+ boundaryEvent(id, attachedToOrOptions, maybeOptions) {
853
+ const options = resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions);
832
854
  const element = makeFlowElement(id, "boundaryEvent", {
833
855
  ...options,
834
856
  extensionElements: buildMessageSubscriptionExt(options.correlationKey),
@@ -901,10 +923,18 @@ export class BranchBuilder {
901
923
  transaction(id, content, options) {
902
924
  return this.addElement(makeTransactionEl(id, content, options, this.rootMessages));
903
925
  }
904
- /** Add an ad-hoc sub-process (mirrors `ProcessBuilder.adHocSubProcess`). */
926
+ /**
927
+ * Add an ad-hoc sub-process (mirrors `ProcessBuilder.adHocSubProcess`).
928
+ *
929
+ * Its children are **not** auto-chained: BPMN defines them as an unordered set
930
+ * of independently-invocable activities, and Camunda 8 reads a child with an
931
+ * incoming flow as part of an internal sub-flow rather than an LLM-invocable
932
+ * tool. Use `connectTo()` inside the callback to state ordering you do want.
933
+ */
905
934
  adHocSubProcess(id, content, options) {
906
935
  const resolved = resolveSubProcessArgs(content, options);
907
- const sub = new SubProcessContentBuilder(this.rootMessages);
936
+ // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
937
+ const sub = new SubProcessContentBuilder(this.rootMessages, false);
908
938
  resolved.content(sub);
909
939
  finalizeScope(sub._elements, sub._flows);
910
940
  const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
@@ -1007,9 +1037,22 @@ export class SubProcessContentBuilder {
1007
1037
  currentGatewayId;
1008
1038
  openBranchEnds = [];
1009
1039
  rootMessages;
1040
+ /**
1041
+ * Whether sequential calls chain themselves with sequence flows.
1042
+ *
1043
+ * False inside an ad-hoc sub-process, whose children BPMN defines as an
1044
+ * unordered set of independently-invocable activities. Chaining them there is
1045
+ * not merely redundant: Camunda 8 reads a child *with* an incoming flow as
1046
+ * part of an internal sub-flow rather than an LLM-invocable tool, so the
1047
+ * fabricated flows silently turned a three-tool agent into one tool and a
1048
+ * two-step sub-flow. Ordering inside such a container is stated explicitly
1049
+ * with `connectTo()`.
1050
+ */
1051
+ autoConnect;
1010
1052
  /** @internal */
1011
- constructor(rootMessages = []) {
1053
+ constructor(rootMessages = [], autoConnect = true) {
1012
1054
  this.rootMessages = rootMessages;
1055
+ this.autoConnect = autoConnect;
1013
1056
  }
1014
1057
  addElement(element) {
1015
1058
  if (this._ids.has(element.id)) {
@@ -1017,25 +1060,29 @@ export class SubProcessContentBuilder {
1017
1060
  }
1018
1061
  this._elements.push(element);
1019
1062
  this._ids.add(element.id);
1020
- if (this.lastNodeId) {
1021
- this._flows.push({
1022
- id: generateId("Flow"),
1023
- sourceRef: this.lastNodeId,
1024
- targetRef: element.id,
1025
- extensionElements: [],
1026
- unknownAttributes: {},
1027
- });
1028
- }
1029
- for (const branchEnd of this.openBranchEnds) {
1030
- this._flows.push({
1031
- id: generateId("Flow"),
1032
- sourceRef: branchEnd,
1033
- targetRef: element.id,
1034
- extensionElements: [],
1035
- unknownAttributes: {},
1036
- });
1063
+ if (this.autoConnect) {
1064
+ if (this.lastNodeId) {
1065
+ this._flows.push({
1066
+ id: generateId("Flow"),
1067
+ sourceRef: this.lastNodeId,
1068
+ targetRef: element.id,
1069
+ extensionElements: [],
1070
+ unknownAttributes: {},
1071
+ });
1072
+ }
1073
+ for (const branchEnd of this.openBranchEnds) {
1074
+ this._flows.push({
1075
+ id: generateId("Flow"),
1076
+ sourceRef: branchEnd,
1077
+ targetRef: element.id,
1078
+ extensionElements: [],
1079
+ unknownAttributes: {},
1080
+ });
1081
+ }
1082
+ this.openBranchEnds = [];
1037
1083
  }
1038
- this.openBranchEnds = [];
1084
+ // The cursor still moves even when nothing is wired, so `connectTo()` after
1085
+ // an activity keeps naming that activity as the flow's source.
1039
1086
  this.lastNodeId = element.id;
1040
1087
  return this;
1041
1088
  }
@@ -1247,7 +1294,8 @@ export class SubProcessContentBuilder {
1247
1294
  * subsequent elements chain from it. Use `withBoundary()` if you want the
1248
1295
  * cursor to return to the task afterward.
1249
1296
  */
1250
- boundaryEvent(id, options) {
1297
+ boundaryEvent(id, attachedToOrOptions, maybeOptions) {
1298
+ const options = resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions);
1251
1299
  const element = makeFlowElement(id, "boundaryEvent", {
1252
1300
  ...options,
1253
1301
  extensionElements: buildMessageSubscriptionExt(options.correlationKey),
@@ -1317,10 +1365,18 @@ export class SubProcessContentBuilder {
1317
1365
  transaction(id, content, options) {
1318
1366
  return this.addElement(makeTransactionEl(id, content, options, this.rootMessages));
1319
1367
  }
1320
- /** Add an ad-hoc sub-process nested inside this sub-process's content. */
1368
+ /**
1369
+ * Add an ad-hoc sub-process nested inside this sub-process's content.
1370
+ *
1371
+ * Its children are **not** auto-chained: BPMN defines them as an unordered set
1372
+ * of independently-invocable activities, and Camunda 8 reads a child with an
1373
+ * incoming flow as part of an internal sub-flow rather than an LLM-invocable
1374
+ * tool. Use `connectTo()` inside the callback to state ordering you do want.
1375
+ */
1321
1376
  adHocSubProcess(id, content, options) {
1322
1377
  const resolved = resolveSubProcessArgs(content, options);
1323
- const sub = new SubProcessContentBuilder(this.rootMessages);
1378
+ // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
1379
+ const sub = new SubProcessContentBuilder(this.rootMessages, false);
1324
1380
  resolved.content(sub);
1325
1381
  finalizeScope(sub._elements, sub._flows);
1326
1382
  const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
@@ -1637,6 +1693,7 @@ export class ProcessBuilder {
1637
1693
  }
1638
1694
  const element = makeFlowElement(nodeId, "startEvent", {
1639
1695
  name: options?.name,
1696
+ documentation: options?.documentation,
1640
1697
  extensionElements: extElements,
1641
1698
  });
1642
1699
  if (element.type === "startEvent" && options) {
@@ -1715,7 +1772,8 @@ export class ProcessBuilder {
1715
1772
  * Boundary events do not auto-connect from the previous element.
1716
1773
  * They start a new outgoing chain from the boundary event itself.
1717
1774
  */
1718
- boundaryEvent(id, options) {
1775
+ boundaryEvent(id, attachedToOrOptions, maybeOptions) {
1776
+ const options = resolveBoundaryEventArgs(id, attachedToOrOptions, maybeOptions);
1719
1777
  const element = makeFlowElement(id, "boundaryEvent", {
1720
1778
  ...options,
1721
1779
  extensionElements: buildMessageSubscriptionExt(options.correlationKey),
@@ -1982,10 +2040,18 @@ export class ProcessBuilder {
1982
2040
  return this;
1983
2041
  }
1984
2042
  // ---- Sub-processes ----
1985
- /** Add an ad-hoc sub-process with optional AI agent or multi-instance configuration. */
2043
+ /**
2044
+ * Add an ad-hoc sub-process with optional AI agent or multi-instance configuration.
2045
+ *
2046
+ * Its children are **not** auto-chained: BPMN defines them as an unordered set
2047
+ * of independently-invocable activities, and Camunda 8 reads a child with an
2048
+ * incoming flow as part of an internal sub-flow rather than an LLM-invocable
2049
+ * tool. Use `connectTo()` inside the callback to state ordering you do want.
2050
+ */
1986
2051
  adHocSubProcess(id, content, options) {
1987
2052
  const resolved = resolveSubProcessArgs(content, options);
1988
- const sub = new SubProcessContentBuilder(this.rootMessages);
2053
+ // Ad-hoc sub-process children are unordered — see SubProcessContentBuilder.autoConnect.
2054
+ const sub = new SubProcessContentBuilder(this.rootMessages, false);
1989
2055
  resolved.content(sub);
1990
2056
  finalizeScope(sub._elements, sub._flows);
1991
2057
  const { extensionElements, completionCondition } = buildAdHocSubProcessExtensions(resolved.options);
@@ -5,6 +5,12 @@ export interface CompactElement {
5
5
  id: string;
6
6
  type: BpmnElementType;
7
7
  name?: string;
8
+ /**
9
+ * Free-text `<bpmn:documentation>`. Not decoration: on an ad-hoc sub-process
10
+ * child it is the tool description the AI Agent connector hands the LLM, and
11
+ * on a start event it is where the process input contract is written.
12
+ */
13
+ documentation?: string;
8
14
  /** Zeebe job type (serviceTask: zeebe:taskDefinition.type) */
9
15
  jobType?: string;
10
16
  /** dataObjectReference: id of the dataObject it points at. */
@@ -56,6 +62,8 @@ export interface CompactFlow {
56
62
  export interface CompactProcess {
57
63
  id: string;
58
64
  name?: string;
65
+ /** Free-text `<bpmn:documentation>` on the process itself. */
66
+ documentation?: string;
59
67
  elements: CompactElement[];
60
68
  flows: CompactFlow[];
61
69
  }
@@ -1,4 +1,5 @@
1
1
  import { layoutProcess } from "../layout/index.js";
2
+ import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
2
3
  // ── Compactify ───────────────────────────────────────────────────────────────
3
4
  function findAttr(ext, name, attr) {
4
5
  return ext.find((e) => e.name === name)?.attributes[attr];
@@ -8,6 +9,8 @@ function compactifyElement(el) {
8
9
  const result = { id: el.id, type: el.type };
9
10
  if (el.name)
10
11
  result.name = el.name;
12
+ if (el.documentation)
13
+ result.documentation = el.documentation;
11
14
  const jobType = findAttr(ext, "zeebe:taskDefinition", "type");
12
15
  if (jobType)
13
16
  result.jobType = jobType;
@@ -103,11 +106,13 @@ function compactifyElement(el) {
103
106
  * ```
104
107
  */
105
108
  export function compactify(defs) {
109
+ assertBpmnDefinitions(defs, "compactify");
106
110
  return {
107
111
  id: defs.id,
108
112
  processes: defs.processes.map((process) => ({
109
113
  id: process.id,
110
114
  name: process.name,
115
+ documentation: process.documentation,
111
116
  elements: process.flowElements.map(compactifyElement),
112
117
  flows: process.sequenceFlows.map((sf) => {
113
118
  const f = { id: sf.id, from: sf.sourceRef, to: sf.targetRef };
@@ -239,6 +244,7 @@ export function buildFlowElement(el, incoming, outgoing) {
239
244
  const base = {
240
245
  id: el.id,
241
246
  name: el.name,
247
+ documentation: el.documentation,
242
248
  incoming,
243
249
  outgoing,
244
250
  extensionElements: makeExtensions(el),
@@ -380,6 +386,7 @@ function expandProcess(compact) {
380
386
  const process = {
381
387
  id: compact.id,
382
388
  name: compact.name,
389
+ documentation: compact.documentation,
383
390
  isExecutable: true,
384
391
  extensionElements: [],
385
392
  flowElements,
@@ -404,6 +411,7 @@ function expandProcess(compact) {
404
411
  * ```
405
412
  */
406
413
  export function expand(compact) {
414
+ assertCompactDiagram(compact, "expand");
407
415
  const processes = [];
408
416
  const diagrams = [];
409
417
  for (const cp of compact.processes) {
@@ -1,3 +1,4 @@
1
+ import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
1
2
  import { buildFlowElement, makeEventDef, } from "./compact.js";
2
3
  import { bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, } from "./zeebe-extensions.js";
3
4
  /** Thrown by {@link applyBpmnOperations} in strict mode. */
@@ -178,6 +179,8 @@ function patchElement(element, patch) {
178
179
  return misplaced;
179
180
  if (patch.name !== undefined)
180
181
  element.name = patch.name;
182
+ if (patch.documentation !== undefined)
183
+ element.documentation = patch.documentation;
181
184
  if (patch.attachedTo !== undefined && "attachedToRef" in element) {
182
185
  element.attachedToRef = patch.attachedTo;
183
186
  }
@@ -229,6 +232,7 @@ function patchElement(element, patch) {
229
232
  * ```
230
233
  */
231
234
  export function applyBpmnOperations(definitions, operations, options = {}) {
235
+ assertBpmnDefinitions(definitions, "applyBpmnOperations");
232
236
  const draft = structuredClone(definitions);
233
237
  const problems = [];
234
238
  let applied = 0;
@@ -383,6 +387,8 @@ function recomputeRefs(container) {
383
387
  * @returns The updated model, plus what applied and what did not.
384
388
  */
385
389
  export function reconcileCompact(definitions, compact, options = {}) {
390
+ assertBpmnDefinitions(definitions, "reconcileCompact");
391
+ assertCompactDiagram(compact, "reconcileCompact");
386
392
  const draft = structuredClone(definitions);
387
393
  for (const compactProcess of compact.processes) {
388
394
  if (!draft.processes.some((process) => process.id === compactProcess.id)) {
@@ -77,6 +77,9 @@ export type BpmnOperation =
77
77
  * ])
78
78
  * const xml = Bpmn.export(expand(updated))
79
79
  * ```
80
+ *
81
+ * @throws {TypeError} When `diagram` is not a CompactDiagram. Raw XML is the
82
+ * easy mistake — `compactify(Bpmn.parse(xml))` is the way in.
80
83
  */
81
84
  export declare function applyOperations(diagram: CompactDiagram, ops: BpmnOperation[]): CompactDiagram;
82
85
  //# sourceMappingURL=operations.d.ts.map
@@ -1,3 +1,4 @@
1
+ import { assertCompactDiagram } from "./argument-guards.js";
1
2
  function findElementIn(container, id) {
2
3
  for (let i = 0; i < container.elements.length; i++) {
3
4
  const el = container.elements[i];
@@ -141,8 +142,12 @@ function applyOne(diagram, op) {
141
142
  * ])
142
143
  * const xml = Bpmn.export(expand(updated))
143
144
  * ```
145
+ *
146
+ * @throws {TypeError} When `diagram` is not a CompactDiagram. Raw XML is the
147
+ * easy mistake — `compactify(Bpmn.parse(xml))` is the way in.
144
148
  */
145
149
  export function applyOperations(diagram, ops) {
150
+ assertCompactDiagram(diagram, "applyOperations");
146
151
  const result = structuredClone(diagram);
147
152
  for (const op of ops) {
148
153
  applyOne(result, op);
@@ -1,4 +1,15 @@
1
1
  import { generateId } from "../types/id-generator.js";
2
+ /**
3
+ * Every generated component carries a layout. Camunda Modeler and the form-js importer
4
+ * treat a missing `layout` as a legacy schema and backfill a row/columns pair on open,
5
+ * which would show up as a spurious diff on a form this builder just produced.
6
+ */
7
+ function resolveLayout(layout) {
8
+ return {
9
+ row: layout?.row ?? generateId("Row"),
10
+ columns: layout?.columns ?? null,
11
+ };
12
+ }
2
13
  /** Builder for constructing Camunda Forms programmatically. */
3
14
  export class FormBuilder {
4
15
  _id;
@@ -51,8 +62,7 @@ export class FormBuilder {
51
62
  };
52
63
  if (options?.label !== undefined)
53
64
  component.label = options.label;
54
- if (options?.layout !== undefined)
55
- component.layout = options.layout;
65
+ component.layout = resolveLayout(options?.layout);
56
66
  this._components.push(component);
57
67
  return this;
58
68
  }
@@ -68,8 +78,7 @@ export class FormBuilder {
68
78
  component.validate = options.validate;
69
79
  if (options?.defaultValue !== undefined)
70
80
  component.defaultValue = options.defaultValue;
71
- if (options?.layout !== undefined)
72
- component.layout = options.layout;
81
+ component.layout = resolveLayout(options?.layout);
73
82
  this._components.push(component);
74
83
  return this;
75
84
  }
@@ -85,8 +94,7 @@ export class FormBuilder {
85
94
  component.validate = options.validate;
86
95
  if (options?.defaultValue !== undefined)
87
96
  component.defaultValue = options.defaultValue;
88
- if (options?.layout !== undefined)
89
- component.layout = options.layout;
97
+ component.layout = resolveLayout(options?.layout);
90
98
  this._components.push(component);
91
99
  return this;
92
100
  }
@@ -108,8 +116,7 @@ export class FormBuilder {
108
116
  component.searchable = options.searchable;
109
117
  if (options?.defaultValue !== undefined)
110
118
  component.defaultValue = options.defaultValue;
111
- if (options?.layout !== undefined)
112
- component.layout = options.layout;
119
+ component.layout = resolveLayout(options?.layout);
113
120
  this._components.push(component);
114
121
  return this;
115
122
  }
@@ -126,8 +133,7 @@ export class FormBuilder {
126
133
  component.validate = options.validate;
127
134
  if (options?.defaultValue !== undefined)
128
135
  component.defaultValue = options.defaultValue;
129
- if (options?.layout !== undefined)
130
- component.layout = options.layout;
136
+ component.layout = resolveLayout(options?.layout);
131
137
  this._components.push(component);
132
138
  return this;
133
139
  }
@@ -143,8 +149,7 @@ export class FormBuilder {
143
149
  component.validate = options.validate;
144
150
  if (options?.defaultValue !== undefined)
145
151
  component.defaultValue = options.defaultValue;
146
- if (options?.layout !== undefined)
147
- component.layout = options.layout;
152
+ component.layout = resolveLayout(options?.layout);
148
153
  this._components.push(component);
149
154
  return this;
150
155
  }
@@ -159,8 +164,7 @@ export class FormBuilder {
159
164
  };
160
165
  if (options?.validate !== undefined)
161
166
  component.validate = options.validate;
162
- if (options?.layout !== undefined)
163
- component.layout = options.layout;
167
+ component.layout = resolveLayout(options?.layout);
164
168
  this._components.push(component);
165
169
  return this;
166
170
  }
@@ -176,8 +180,7 @@ export class FormBuilder {
176
180
  };
177
181
  if (options?.showOutline !== undefined)
178
182
  component.showOutline = options.showOutline;
179
- if (options?.layout !== undefined)
180
- component.layout = options.layout;
183
+ component.layout = resolveLayout(options?.layout);
181
184
  this._components.push(component);
182
185
  return this;
183
186
  }
@@ -220,8 +223,7 @@ export class GroupBuilder {
220
223
  };
221
224
  if (options?.label !== undefined)
222
225
  component.label = options.label;
223
- if (options?.layout !== undefined)
224
- component.layout = options.layout;
226
+ component.layout = resolveLayout(options?.layout);
225
227
  this._components.push(component);
226
228
  return this;
227
229
  }
@@ -236,8 +238,7 @@ export class GroupBuilder {
236
238
  component.validate = options.validate;
237
239
  if (options?.defaultValue !== undefined)
238
240
  component.defaultValue = options.defaultValue;
239
- if (options?.layout !== undefined)
240
- component.layout = options.layout;
241
+ component.layout = resolveLayout(options?.layout);
241
242
  this._components.push(component);
242
243
  return this;
243
244
  }
@@ -252,8 +253,7 @@ export class GroupBuilder {
252
253
  component.validate = options.validate;
253
254
  if (options?.defaultValue !== undefined)
254
255
  component.defaultValue = options.defaultValue;
255
- if (options?.layout !== undefined)
256
- component.layout = options.layout;
256
+ component.layout = resolveLayout(options?.layout);
257
257
  this._components.push(component);
258
258
  return this;
259
259
  }
@@ -274,8 +274,7 @@ export class GroupBuilder {
274
274
  component.searchable = options.searchable;
275
275
  if (options?.defaultValue !== undefined)
276
276
  component.defaultValue = options.defaultValue;
277
- if (options?.layout !== undefined)
278
- component.layout = options.layout;
277
+ component.layout = resolveLayout(options?.layout);
279
278
  this._components.push(component);
280
279
  return this;
281
280
  }
@@ -291,8 +290,7 @@ export class GroupBuilder {
291
290
  component.validate = options.validate;
292
291
  if (options?.defaultValue !== undefined)
293
292
  component.defaultValue = options.defaultValue;
294
- if (options?.layout !== undefined)
295
- component.layout = options.layout;
293
+ component.layout = resolveLayout(options?.layout);
296
294
  this._components.push(component);
297
295
  return this;
298
296
  }
@@ -307,8 +305,7 @@ export class GroupBuilder {
307
305
  component.validate = options.validate;
308
306
  if (options?.defaultValue !== undefined)
309
307
  component.defaultValue = options.defaultValue;
310
- if (options?.layout !== undefined)
311
- component.layout = options.layout;
308
+ component.layout = resolveLayout(options?.layout);
312
309
  this._components.push(component);
313
310
  return this;
314
311
  }
@@ -322,8 +319,7 @@ export class GroupBuilder {
322
319
  };
323
320
  if (options?.validate !== undefined)
324
321
  component.validate = options.validate;
325
- if (options?.layout !== undefined)
326
- component.layout = options.layout;
322
+ component.layout = resolveLayout(options?.layout);
327
323
  this._components.push(component);
328
324
  return this;
329
325
  }
@@ -338,8 +334,7 @@ export class GroupBuilder {
338
334
  };
339
335
  if (options?.showOutline !== undefined)
340
336
  component.showOutline = options.showOutline;
341
- if (options?.layout !== undefined)
342
- component.layout = options.layout;
337
+ component.layout = resolveLayout(options?.layout);
343
338
  this._components.push(component);
344
339
  return this;
345
340
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -21,7 +21,7 @@
21
21
  "dist/**/*.d.ts"
22
22
  ],
23
23
  "dependencies": {
24
- "@bpmnkit/feel": "0.0.20"
24
+ "@bpmnkit/feel": "0.0.21"
25
25
  },
26
26
  "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
27
27
  "keywords": [