@bpmnkit/core 0.7.0 → 0.8.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
@@ -317,6 +317,7 @@ const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
317
317
  | [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
318
318
  | [`@bpmnkit/ascii`](https://www.npmjs.com/package/@bpmnkit/ascii) | Render BPMN diagrams as Unicode ASCII art |
319
319
  | [`@bpmnkit/docspack`](https://www.npmjs.com/package/@bpmnkit/docspack) | BPMN Kit docs as an offline docspack package for AI agents |
320
+ | [`@bpmnkit/camunda-docspack`](https://www.npmjs.com/package/@bpmnkit/camunda-docspack) | Camunda 8 docs as an offline docspack package for AI agents |
320
321
  | [`@bpmnkit/ui`](https://www.npmjs.com/package/@bpmnkit/ui) | Shared design tokens and UI components |
321
322
  | [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
322
323
  | [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring & operations frontend for Camunda clusters |
@@ -57,6 +57,17 @@ export interface CompactFlow {
57
57
  name?: string;
58
58
  /** FEEL condition expression */
59
59
  condition?: string;
60
+ /**
61
+ * Marks this flow as its gateway's default — the path taken when no other
62
+ * condition is true. Only an exclusive, inclusive or complex gateway has one,
63
+ * and it has at most one.
64
+ *
65
+ * It sits on the flow rather than on the gateway because that is where its
66
+ * alternative, `condition`, sits: a model writing the branches of a decision
67
+ * marks one of them instead of having to point back at a flow id. `expand`
68
+ * turns it into the gateway's `bpmn:default` attribute.
69
+ */
70
+ isDefault?: boolean;
60
71
  }
61
72
  /** A single process in compact form. */
62
73
  export interface CompactProcess {
@@ -86,6 +97,14 @@ export interface CompactDiagram {
86
97
  id: string;
87
98
  processes: CompactProcess[];
88
99
  }
100
+ /**
101
+ * The flow each gateway marks as its default, keyed by the gateway's id.
102
+ *
103
+ * Both failures throw rather than being dropped: a diagram whose default went
104
+ * missing is one whose gateway deadlocks the first time every condition is
105
+ * false, and that is a runtime failure with no trace back to here.
106
+ */
107
+ export declare function defaultFlows(elements: readonly CompactElement[], flows: readonly CompactFlow[]): Map<string, string>;
89
108
  /**
90
109
  * Converts a {@link BpmnDefinitions} model into a token-efficient
91
110
  * {@link CompactDiagram} representation suitable for AI contexts (LLM prompts,
@@ -108,7 +127,9 @@ export interface CompactDiagram {
108
127
  export declare function compactify(defs: BpmnDefinitions): CompactDiagram;
109
128
  export declare function makeEventDef(eventType: string): BpmnEventDefinition | undefined;
110
129
  export declare function makeExtensions(el: CompactElement): XmlElement[];
111
- export declare function buildFlowElement(el: CompactElement, incoming: string[], outgoing: string[]): BpmnFlowElement;
130
+ export declare function buildFlowElement(el: CompactElement, incoming: string[], outgoing: string[],
131
+ /** Id of the outgoing flow marked `isDefault`, for a gateway that has one. */
132
+ defaultFlow?: string): BpmnFlowElement;
112
133
  /**
113
134
  * Restores a {@link CompactDiagram} (produced by {@link compactify} or an AI
114
135
  * model) back to a full {@link BpmnDefinitions} with auto-generated layout.
@@ -1,5 +1,40 @@
1
1
  import { layoutProcess } from "../layout/index.js";
2
2
  import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
3
+ // ── Default flows ────────────────────────────────────────────────────────────
4
+ /**
5
+ * The gateway types that carry a `bpmn:default`. No other element in this model
6
+ * has the attribute, so a flow marked default anywhere else has nowhere to go.
7
+ */
8
+ const DEFAULTABLE = new Set([
9
+ "exclusiveGateway",
10
+ "inclusiveGateway",
11
+ "complexGateway",
12
+ ]);
13
+ /**
14
+ * The flow each gateway marks as its default, keyed by the gateway's id.
15
+ *
16
+ * Both failures throw rather than being dropped: a diagram whose default went
17
+ * missing is one whose gateway deadlocks the first time every condition is
18
+ * false, and that is a runtime failure with no trace back to here.
19
+ */
20
+ export function defaultFlows(elements, flows) {
21
+ const types = new Map(elements.map((element) => [element.id, element.type]));
22
+ const defaults = new Map();
23
+ for (const flow of flows) {
24
+ if (!flow.isDefault)
25
+ continue;
26
+ const type = types.get(flow.from);
27
+ if (type === undefined || !DEFAULTABLE.has(type)) {
28
+ throw new Error(`flow "${flow.id}" is marked isDefault but leaves ${type === undefined ? `unknown element "${flow.from}"` : `a ${type}`}. Only an exclusive, inclusive or complex gateway has a default flow.`);
29
+ }
30
+ const already = defaults.get(flow.from);
31
+ if (already !== undefined) {
32
+ throw new Error(`gateway "${flow.from}" marks two flows as default, "${already}" and "${flow.id}". A gateway has at most one.`);
33
+ }
34
+ defaults.set(flow.from, flow.id);
35
+ }
36
+ return defaults;
37
+ }
3
38
  // ── Compactify ───────────────────────────────────────────────────────────────
4
39
  function findAttr(ext, name, attr) {
5
40
  return ext.find((e) => e.name === name)?.attributes[attr];
@@ -74,18 +109,29 @@ function compactifyElement(el) {
74
109
  const seqFlows = "sequenceFlows" in el && Array.isArray(el.sequenceFlows) ? el.sequenceFlows : [];
75
110
  result.children = {
76
111
  elements: el.flowElements.map(compactifyElement),
77
- flows: seqFlows.map((sf) => {
78
- const f = { id: sf.id, from: sf.sourceRef, to: sf.targetRef };
79
- if (sf.name)
80
- f.name = sf.name;
81
- if (sf.conditionExpression)
82
- f.condition = sf.conditionExpression.text;
83
- return f;
84
- }),
112
+ flows: compactifyFlows(el.flowElements, seqFlows),
85
113
  };
86
114
  }
87
115
  return result;
88
116
  }
117
+ /**
118
+ * Projects sequence flows, marking the one each gateway points at with
119
+ * `bpmn:default`. The gateways are read here rather than in
120
+ * {@link compactifyElement} because the attribute names a sibling flow.
121
+ */
122
+ function compactifyFlows(elements, sequenceFlows) {
123
+ const marked = new Set(elements.flatMap((element) => "default" in element && element.default !== undefined ? [element.default] : []));
124
+ return sequenceFlows.map((sf) => {
125
+ const flow = { id: sf.id, from: sf.sourceRef, to: sf.targetRef };
126
+ if (sf.name)
127
+ flow.name = sf.name;
128
+ if (sf.conditionExpression)
129
+ flow.condition = sf.conditionExpression.text;
130
+ if (marked.has(sf.id))
131
+ flow.isDefault = true;
132
+ return flow;
133
+ });
134
+ }
89
135
  /**
90
136
  * Converts a {@link BpmnDefinitions} model into a token-efficient
91
137
  * {@link CompactDiagram} representation suitable for AI contexts (LLM prompts,
@@ -114,14 +160,7 @@ export function compactify(defs) {
114
160
  name: process.name,
115
161
  documentation: process.documentation,
116
162
  elements: process.flowElements.map(compactifyElement),
117
- flows: process.sequenceFlows.map((sf) => {
118
- const f = { id: sf.id, from: sf.sourceRef, to: sf.targetRef };
119
- if (sf.name)
120
- f.name = sf.name;
121
- if (sf.conditionExpression)
122
- f.condition = sf.conditionExpression.text;
123
- return f;
124
- }),
163
+ flows: compactifyFlows(process.flowElements, process.sequenceFlows),
125
164
  })),
126
165
  };
127
166
  }
@@ -224,8 +263,9 @@ function buildSubContent(children) {
224
263
  i.push(f.id);
225
264
  inc.set(f.to, i);
226
265
  }
266
+ const defaults = defaultFlows(children.elements, children.flows);
227
267
  return {
228
- flowElements: children.elements.map((child) => buildFlowElement(child, inc.get(child.id) ?? [], out.get(child.id) ?? [])),
268
+ flowElements: children.elements.map((child) => buildFlowElement(child, inc.get(child.id) ?? [], out.get(child.id) ?? [], defaults.get(child.id))),
229
269
  sequenceFlows: children.flows.map((f) => ({
230
270
  id: f.id,
231
271
  name: f.name,
@@ -240,7 +280,9 @@ function buildSubContent(children) {
240
280
  groups: [],
241
281
  };
242
282
  }
243
- export function buildFlowElement(el, incoming, outgoing) {
283
+ export function buildFlowElement(el, incoming, outgoing,
284
+ /** Id of the outgoing flow marked `isDefault`, for a gateway that has one. */
285
+ defaultFlow) {
244
286
  const base = {
245
287
  id: el.id,
246
288
  name: el.name,
@@ -297,15 +339,15 @@ export function buildFlowElement(el, incoming, outgoing) {
297
339
  case "transaction":
298
340
  return { ...base, type: "transaction", ...subContent };
299
341
  case "exclusiveGateway":
300
- return { ...base, type: "exclusiveGateway" };
342
+ return { ...base, type: "exclusiveGateway", default: defaultFlow };
301
343
  case "parallelGateway":
302
344
  return { ...base, type: "parallelGateway" };
303
345
  case "inclusiveGateway":
304
- return { ...base, type: "inclusiveGateway" };
346
+ return { ...base, type: "inclusiveGateway", default: defaultFlow };
305
347
  case "eventBasedGateway":
306
348
  return { ...base, type: "eventBasedGateway" };
307
349
  case "complexGateway":
308
- return { ...base, type: "complexGateway" };
350
+ return { ...base, type: "complexGateway", default: defaultFlow };
309
351
  // Data elements are not sequence-flow participants; they carry a
310
352
  // reference instead, and dropping that reference is what made them
311
353
  // round-trip as bare tasks before.
@@ -373,7 +415,8 @@ function expandProcess(compact) {
373
415
  inc.push(f.id);
374
416
  incoming.set(f.to, inc);
375
417
  }
376
- const flowElements = compact.elements.map((el) => buildFlowElement(el, incoming.get(el.id) ?? [], outgoing.get(el.id) ?? []));
418
+ const defaults = defaultFlows(compact.elements, compact.flows);
419
+ const flowElements = compact.elements.map((el) => buildFlowElement(el, incoming.get(el.id) ?? [], outgoing.get(el.id) ?? [], defaults.get(el.id)));
377
420
  const sequenceFlows = compact.flows.map((f) => ({
378
421
  id: f.id,
379
422
  name: f.name,
@@ -1,5 +1,5 @@
1
1
  import { assertBpmnDefinitions, assertCompactDiagram } from "./argument-guards.js";
2
- import { buildFlowElement, makeEventDef, } from "./compact.js";
2
+ import { buildFlowElement, defaultFlows, makeEventDef, } from "./compact.js";
3
3
  import { bpmnElementName, ensureZeebeExtension, isZeebePlacementAllowed, } from "./zeebe-extensions.js";
4
4
  /** Thrown by {@link applyBpmnOperations} in strict mode. */
5
5
  export class OperationError extends Error {
@@ -405,7 +405,35 @@ export function reconcileCompact(definitions, compact, options = {}) {
405
405
  });
406
406
  }
407
407
  }
408
- return applyBpmnOperations(draft, operationsForCompact(draft, compact), options);
408
+ const result = applyBpmnOperations(draft, operationsForCompact(draft, compact), options);
409
+ reconcileDefaultFlows(result.definitions, compact);
410
+ return result;
411
+ }
412
+ /**
413
+ * Brings each gateway's `bpmn:default` in line with the flow the compact input
414
+ * marks, clearing one the input no longer marks.
415
+ *
416
+ * It runs after the operations rather than as one of them because the attribute
417
+ * names a flow: a default can only be set once the flow it points at exists, and
418
+ * a flow that is being replaced is deleted and re-added under the same id.
419
+ */
420
+ function reconcileDefaultFlows(definitions, compact) {
421
+ for (const compactProcess of compact.processes) {
422
+ const process = definitions.processes.find((candidate) => candidate.id === compactProcess.id);
423
+ if (!process)
424
+ continue;
425
+ const wanted = defaultFlows(compactProcess.elements, compactProcess.flows);
426
+ for (const element of process.flowElements) {
427
+ // By type, not by `"default" in element`: a gateway built without the
428
+ // attribute has no such key, and skipping it would drop a wanted default.
429
+ if (element.type !== "exclusiveGateway" &&
430
+ element.type !== "inclusiveGateway" &&
431
+ element.type !== "complexGateway") {
432
+ continue;
433
+ }
434
+ element.default = wanted.get(element.id);
435
+ }
436
+ }
409
437
  }
410
438
  /**
411
439
  * Derives the operations that would bring `definitions` in line with `compact`.
@@ -129,6 +129,11 @@ function collectNames(node, out) {
129
129
  for (const arg of node.args)
130
130
  collectNames(arg, out);
131
131
  break;
132
+ case "call-expr":
133
+ collectNames(node.target, out);
134
+ for (const arg of node.args)
135
+ collectNames(arg, out);
136
+ break;
132
137
  case "call-named":
133
138
  for (const arg of node.args)
134
139
  collectNames(arg.value, out);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "0.7.0",
3
+ "version": "0.8.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.21"
24
+ "@bpmnkit/feel": "0.1.0"
25
25
  },
26
26
  "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
27
27
  "keywords": [