@bpmnkit/core 1.10.0 → 1.11.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.
@@ -8,7 +8,7 @@ Write a Camunda 8 BPMN process with `@bpmnkit/core` in one script: create, expor
8
8
 
9
9
  ```ts
10
10
  import { readFileSync, writeFileSync } from "node:fs"
11
- import { Bpmn, exportPreserving, lintDiagram } from "@bpmnkit/core"
11
+ import { Bpmn, exportPreserving, lintDiagram, placeNewShapes } from "@bpmnkit/core"
12
12
 
13
13
  // 1. Create. The process id is the deploy key: same id = new version of that process.
14
14
  const definitions = Bpmn.createProcess("order")
@@ -32,12 +32,18 @@ const definitions = Bpmn.createProcess("order")
32
32
  // 2. Export.
33
33
  writeFileSync("order.bpmn", Bpmn.export(definitions))
34
34
 
35
- // 3. Edit an existing file: parse, change, write with exportPreserving to keep layout and formatting.
35
+ // 3. Edit an existing file: change the model, draw only the new elements, write with
36
+ // exportPreserving. Existing shapes keep their positions and the file its formatting.
36
37
  const original = readFileSync("order.bpmn", "utf8")
37
- const edited = Bpmn.parse(original)
38
+ const edited = Bpmn.continueProcess(Bpmn.parse(original), "order")
39
+ .insertAfter("ship")
40
+ .serviceTask("notify", { name: "Notify customer", taskType: "notify-customer" })
41
+ .build()
38
42
  const ship = edited.processes[0]?.flowElements.find((e) => e.id === "ship")
39
43
  if (ship) ship.name = "Ship parcel"
40
- writeFileSync("order.bpmn", exportPreserving(original, edited))
44
+ const { definitions: drawn, unplaced } = placeNewShapes(edited)
45
+ if (unplaced.length > 0) console.log("not drawn:", unplaced)
46
+ writeFileSync("order.bpmn", exportPreserving(original, drawn))
41
47
 
42
48
  // 4. Validate: Camunda 8 deployability and modelling rules.
43
49
  const report = lintDiagram(Bpmn.parse(readFileSync("order.bpmn", "utf8")))
@@ -46,7 +52,7 @@ for (const d of report.diagnostics.filter((d) => d.severity !== "info"))
46
52
  if (report.counts.error > 0) process.exit(1)
47
53
  ```
48
54
 
49
- `npm i @bpmnkit/core`. The script writes `order.bpmn`, re-opens it, renames a task without moving a shape, and exits 1 on a lint error.
55
+ `npm i @bpmnkit/core`. The script writes `order.bpmn`, re-opens it, adds a task and renames one without moving a shape, and exits 1 on a lint error.
50
56
 
51
57
  ## Top builder options
52
58
 
@@ -67,7 +73,7 @@ if (report.counts.error > 0) process.exit(1)
67
73
  - **User tasks default to job-worker tasks**, which 8.10 deprecates. Pass `zeebeUserTask: true` for a Camunda user task.
68
74
  - **Deploy ids.** The engine keys a process by its process id (`createProcess("order")`), a decision by its `<decision id>`, a form by its JSON `id`. File names and display names do not count. `formId` and `decisionId` must equal those ids exactly; by default they bind to the latest deployed version, so deploy the `.dmn` and `.form` before an instance reaches the task. Redeploying the same id makes a new version.
69
75
  - **Reference a DMN decision by its decision id**, not the DMN `definitions` id, the file name or the decision name.
70
- - **Edit with the preserving writer.** For an existing file, `Bpmn.parse` it, change the model, and write `exportPreserving(original, edited)`. Rebuilding it with `withAutoLayout()`, or `Bpmn.export` alone, moves every shape and reformats the diff.
76
+ - **Edit with the preserving writer.** For an existing file, `Bpmn.parse` it (or `Bpmn.continueProcess(parsed, processId)`), change the model, run `placeNewShapes(edited)` so the new elements get shapes next to what they connect to, and write `exportPreserving(original, drawn)`. Existing shapes stay put; a pool, lane or sub-process only grows when the new shapes do not fit. Rebuilding with `withAutoLayout()`, `applyAutoLayout`, or `Bpmn.export` alone moves every shape and reformats the diff. `placeNewShapes` does not draw new lanes; it lists them in `unplaced`.
71
77
  - FEEL in the builder starts with `=` (`"=amount > 1000"`); a value without `=` is a literal string.
72
78
  - Unknown option names are silently dropped: `timer: { duration }` does nothing; use `timerDuration`.
73
79
 
@@ -1137,8 +1137,9 @@ export declare class ProcessBuilder {
1137
1137
  * continuing rather than regenerating.
1138
1138
  *
1139
1139
  * Diagram interchange is *not* regenerated: existing shapes keep their
1140
- * positions, and elements added here have none until `withAutoLayout()` or a
1141
- * later `applyAutoLayout()` gives them one.
1140
+ * positions, and elements added here have none until `placeNewShapes()` draws
1141
+ * just those (existing shapes never move), or `withAutoLayout()` /
1142
+ * `applyAutoLayout()` redraws everything.
1142
1143
  */
1143
1144
  private buildOntoSource;
1144
1145
  /**
@@ -2882,8 +2882,9 @@ export class ProcessBuilder {
2882
2882
  * continuing rather than regenerating.
2883
2883
  *
2884
2884
  * Diagram interchange is *not* regenerated: existing shapes keep their
2885
- * positions, and elements added here have none until `withAutoLayout()` or a
2886
- * later `applyAutoLayout()` gives them one.
2885
+ * positions, and elements added here have none until `placeNewShapes()` draws
2886
+ * just those (existing shapes never move), or `withAutoLayout()` /
2887
+ * `applyAutoLayout()` redraws everything.
2887
2888
  */
2888
2889
  buildOntoSource(source, elements, flows) {
2889
2890
  const definitions = structuredClone(source.definitions);
@@ -62,6 +62,8 @@ export declare const Bpmn: {
62
62
  * `build()` returns that document with the named process's contents replaced,
63
63
  * so other processes, the collaboration, lanes, diagram interchange, root
64
64
  * elements and unmodelled content all survive. The input is not mutated.
65
+ * Added elements have no shapes; call `placeNewShapes()` on the result to
66
+ * draw only those without moving existing ones.
65
67
  *
66
68
  * @param definitions - The parsed model to continue.
67
69
  * @param processId - Which process to continue, named explicitly.
@@ -73,6 +73,8 @@ export const Bpmn = {
73
73
  * `build()` returns that document with the named process's contents replaced,
74
74
  * so other processes, the collaboration, lanes, diagram interchange, root
75
75
  * elements and unmodelled content all survive. The input is not mutated.
76
+ * Added elements have no shapes; call `placeNewShapes()` on the result to
77
+ * draw only those without moving existing ones.
76
78
  *
77
79
  * @param definitions - The parsed model to continue.
78
80
  * @param processId - Which process to continue, named explicitly.
@@ -382,7 +382,7 @@ const RULES = {
382
382
  const missing = (id, processId) => {
383
383
  if (drawn.has(id))
384
384
  return;
385
- report("pattern/missing-di", `Element "${id}" has no diagram information (BPMNDI).`, "Open and save the file in a modeler, or run `casen bpmn layout`, to draw it.", processId, [id]);
385
+ report("pattern/missing-di", `Element "${id}" has no diagram information (BPMNDI).`, "In a script, call `placeNewShapes(definitions)` before `exportPreserving` to draw only the new elements; redraw everything only for a new file.", processId, [id]);
386
386
  };
387
387
  const lanes = (list, processId) => {
388
388
  for (const lane of list) {
@@ -0,0 +1,51 @@
1
+ import type { BpmnDefinitions } from "./bpmn-model.js";
2
+ export interface PlaceNewShapesOptions {
3
+ /**
4
+ * Re-route existing edges whose ends no longer touch their shapes, such as a
5
+ * flow the edit re-pointed at a new element. Default `true`.
6
+ */
7
+ rerouteStale?: boolean;
8
+ /**
9
+ * Add a new flow node to the lane it is drawn in when no lane lists it, as a
10
+ * modeller does when a shape is dropped into a lane. Default `true`.
11
+ */
12
+ assignLanes?: boolean;
13
+ }
14
+ export interface PlaceNewShapesResult {
15
+ /** A copy of the input with the new shapes and edges; the input is not changed. */
16
+ definitions: BpmnDefinitions;
17
+ /** Elements that got a shape: flow nodes, pools, annotations. */
18
+ placed: string[];
19
+ /** Connections that got an edge: sequence flows, message flows, associations. */
20
+ routed: string[];
21
+ /** Existing edges that got a new route because their ends no longer met their shapes. */
22
+ rerouted: string[];
23
+ /** Pools, lanes and sub-processes made larger so the new shapes fit. */
24
+ resized: string[];
25
+ /** Flow nodes added to a lane's `flowNodeRefs`. */
26
+ laneAssigned: string[];
27
+ /** What could not be placed, and why. */
28
+ unplaced: Array<{
29
+ id: string;
30
+ reason: string;
31
+ }>;
32
+ }
33
+ /**
34
+ * Gives every element that has no shape a place next to what it connects to,
35
+ * and every connection that has no edge a route, without moving existing shapes.
36
+ *
37
+ * Use it after editing a parsed file and before {@link exportPreserving}:
38
+ *
39
+ * ```ts
40
+ * const original = readFileSync("order.bpmn", "utf8")
41
+ * const defs = Bpmn.parse(original)
42
+ * // … add elements and flows to defs …
43
+ * const { definitions, unplaced } = placeNewShapes(defs)
44
+ * writeFileSync("order.bpmn", exportPreserving(original, definitions))
45
+ * ```
46
+ *
47
+ * New lanes are not placed: they need room inside a pool, which means moving
48
+ * the lanes below. They are reported in `unplaced`.
49
+ */
50
+ export declare function placeNewShapes(input: BpmnDefinitions, options?: PlaceNewShapesOptions): PlaceNewShapesResult;
51
+ //# sourceMappingURL=place-new-shapes.d.ts.map