@diagc/cli 1.9.0 → 1.10.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,77 @@
1
+ # State machine
2
+
3
+ A UML state machine: states, the transitions between them, and the events, guards and effects on those transitions. Reach for it to show how one thing moves through its modes, such as an order, a connection or an editor session.
4
+
5
+ {{starter}}
6
+
7
+ ## How it works
8
+
9
+ - `m.stateMachine(id, opts?)` draws a machine frame and returns a handle. `opts` takes `name`, `plane` and `planeName`. You can call it again for a second machine. Without `plane` the whole diagram becomes a state machine, and the call throws if it has another notation: pass `plane` to draw the machine beside other views.
10
+ - The machine, a state and a region each offer `state(id, name?, { entry?, exit?, do?, color? })`, `initial(id?)`, `final(id?)`, `choice(id?, name?)`, `junction(id?)`, `bar(id?)` and `terminate(id?)`. `entry`, `exit` and `do` are the state's `behaviors`, each an effect.
11
+ - A transition is `machine.transition(from, to, { trigger?, guard?, effect? })`, or `element.to(target, parts?)`, which returns the target so a path chains. A transition reads `trigger [guard] / effect`. Write the parts as options, never as a `label`.
12
+ - `state.on(trigger, { guard?, effect })` adds an internal transition: the state is not left. It shows in the state's behaviors.
13
+ - A state with children is composite and rests folded in a viewer; double-click unfolds it. `state.region(id?, name?)` adds a concurrent region, and a state with regions is orthogonal. `state.entryPoint(id?, name?)` and `state.exitPoint(id?, name?)` sit on its border.
14
+ - `history({ id?, deep? })` is shallow history (`H`), or deep (`H*`) with `deep: true`. `state.history()` is valid on a plain composite state, and `region.history()` in each region of an orthogonal one, where `state.history()` throws. The machine itself has no history. A transition into a history state resumes the substate that was left.
15
+
16
+ ## Node types
17
+
18
+ {{node-types}}
19
+
20
+ You never write these types yourself: the builder creates them. A state is composite when something is inside it.
21
+
22
+ ## Rules
23
+
24
+ Every rule is a warning, never an error: the diagram still compiles. Lint reports them under these codes.
25
+
26
+ - `sm-initial-count`, `sm-initial-flow`: one initial per region, with exactly one plain transition out and none in.
27
+ - `sm-final-outgoing`: a final or a terminate has no transition out.
28
+ - `sm-choice-guards`: each exit of a choice or junction has a guard, and at most one is `else`.
29
+ - `sm-bar-shape`: a bar has one transition on one side, and a fork's targets are in different regions.
30
+ - `sm-unreachable`: a state no path from an initial reaches. A machine with no initial is not checked.
31
+ - `sm-transition-ends`, `sm-transition-label`: a transition joins two state-machine nodes, and its parts carry the text.
32
+ - `sm-region-parent`, `sm-region-siblings`, `sm-machine-parent`, `sm-pseudo-children`, `sm-history-parent`, `sm-point-parent`: where each node may sit.
33
+
34
+ ## From a Quint spec
35
+
36
+ A Quint spec's mode variable becomes the states. Take this one:
37
+
38
+ ```quint
39
+ module order {
40
+ var status: str
41
+ var total: int
42
+ action init = all { status' = "draft", total' = 0 }
43
+ action refund = total' = 0
44
+ action pay = all { status == "draft", total > 0, status' = "paid", total' = total }
45
+ action ship = all { status == "paid", status' = "shipped", total' = total }
46
+ action cancel = any {
47
+ all { status == "draft", status' = "cancelled", total' = total },
48
+ all { status == "paid", refund, status' = "cancelled" },
49
+ }
50
+ }
51
+ ```
52
+
53
+ - The variable that holds the mode, a `str` or a sum type, gives one state per value, and `init` is the initial transition, to the state it assigns.
54
+ - An action that changes the mode is a transition. Its name is the trigger, the preconditions on other variables are the guard, and the other updates, or an action it calls for them (`refund`), are the effect. An update that keeps a variable as it was (`total' = total`) is no effect.
55
+ - The alternatives of an `any` from one mode are several transitions from that state.
56
+ - An action that leaves the mode unchanged is an internal transition (`state.on`), or a self-transition when re-entry matters.
57
+ - Independent mode variables that change in one step are orthogonal regions. An invariant has no diagram element yet: write it in a comment.
58
+
59
+ ```ts
60
+ import { model } from '@diagc/core';
61
+
62
+ const m = model('order-spec', { name: 'Order spec' });
63
+ const order = m.stateMachine('order', { name: 'Order' });
64
+
65
+ const draft = order.state('draft', 'draft');
66
+ const paid = order.state('paid', 'paid');
67
+ const shipped = order.state('shipped', 'shipped');
68
+ const cancelled = order.state('cancelled', 'cancelled');
69
+
70
+ order.initial().to(draft);
71
+ order.transition(draft, paid, { trigger: 'pay', guard: 'total > 0' });
72
+ order.transition(paid, shipped, { trigger: 'ship' });
73
+ order.transition(draft, cancelled, { trigger: 'cancel' });
74
+ order.transition(paid, cancelled, { trigger: 'cancel', effect: 'refund' });
75
+
76
+ export default m;
77
+ ```
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: diagc
3
- description: Write, change or fix a diagc diagram (.diagrams/src/*.diagram.ts) — architecture, C4, deployment, ER, activity, threat model, causal loop, plan and more. Use when asked to draw or update a diagram in a repository that uses diagc.
3
+ description: Write, change or fix a diagc diagram (.diagrams/src/*.diagram.ts) — architecture, C4, deployment, ER, activity, threat model, causal loop, plan, state machine and more. Use when asked to draw or update a diagram in a repository that uses diagc.
4
4
  ---
5
5
 
6
6
  <!-- diagc:begin -->
@@ -0,0 +1,42 @@
1
+ import { model } from '@diagc/core';
2
+
3
+ const m = model('order-lifecycle', { name: 'Order lifecycle' });
4
+
5
+ const order = m.stateMachine('order', { name: 'Order' });
6
+
7
+ const draft = order.state('draft', 'Draft');
8
+ const paid = order.state('paid', 'Paid', { entry: 'reserveStock', exit: 'releaseHold' });
9
+ const fulfil = order.state('fulfil', 'Fulfilment');
10
+ const held = order.state('held', 'On hold');
11
+ const inStock = order.choice('in-stock');
12
+ const done = order.final();
13
+
14
+ // Draft is a plain composite: one substate at a time.
15
+ const editing = draft.state('editing', 'Editing');
16
+ draft.initial().to(editing);
17
+ editing.to(draft.state('reviewing', 'Reviewing'), { trigger: 'submit' });
18
+
19
+ // Two regions make Fulfilment orthogonal: both run at once.
20
+ const pick = fulfil.region('pick', 'Picking');
21
+ const bill = fulfil.region('bill', 'Billing');
22
+ const picking = pick.state('picking', 'Picking');
23
+ pick.initial().to(picking);
24
+ const resumePicking = pick.history();
25
+ bill.initial().to(bill.state('invoicing', 'Invoicing'));
26
+
27
+ order.initial().to(draft);
28
+ order.transition(draft, paid, { trigger: 'pay', guard: 'total > 0', effect: 'charge' });
29
+ order.transition(paid, inStock);
30
+ order.transition(inStock, fulfil, { guard: 'in stock' });
31
+ order.transition(inStock, draft, { guard: 'else' });
32
+ order.transition(fulfil, done, { trigger: 'deliver' });
33
+
34
+ // Resuming enters Picking's history: picking goes on where it was left.
35
+ order.transition(picking, held, { trigger: 'hold' });
36
+ order.transition(held, resumePicking, { trigger: 'resume' });
37
+ order.transition(held, done, { trigger: 'cancel' });
38
+
39
+ // An internal transition: the state is not left.
40
+ paid.on('remind', { guard: 'overdue', effect: 'email' });
41
+
42
+ export default m;