@bpmnkit/core 0.5.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.
@@ -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
@@ -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];
@@ -105,6 +106,7 @@ function compactifyElement(el) {
105
106
  * ```
106
107
  */
107
108
  export function compactify(defs) {
109
+ assertBpmnDefinitions(defs, "compactify");
108
110
  return {
109
111
  id: defs.id,
110
112
  processes: defs.processes.map((process) => ({
@@ -409,6 +411,7 @@ function expandProcess(compact) {
409
411
  * ```
410
412
  */
411
413
  export function expand(compact) {
414
+ assertCompactDiagram(compact, "expand");
412
415
  const processes = [];
413
416
  const diagrams = [];
414
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. */
@@ -231,6 +232,7 @@ function patchElement(element, patch) {
231
232
  * ```
232
233
  */
233
234
  export function applyBpmnOperations(definitions, operations, options = {}) {
235
+ assertBpmnDefinitions(definitions, "applyBpmnOperations");
234
236
  const draft = structuredClone(definitions);
235
237
  const problems = [];
236
238
  let applied = 0;
@@ -385,6 +387,8 @@ function recomputeRefs(container) {
385
387
  * @returns The updated model, plus what applied and what did not.
386
388
  */
387
389
  export function reconcileCompact(definitions, compact, options = {}) {
390
+ assertBpmnDefinitions(definitions, "reconcileCompact");
391
+ assertCompactDiagram(compact, "reconcileCompact");
388
392
  const draft = structuredClone(definitions);
389
393
  for (const compactProcess of compact.processes) {
390
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);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",