@vsirotin/ts-stop 1.13.1 → 2.4.2

package/scripts/json-to-drawio.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+/**
+ * Convert SFSM compact-format FA JSON to draw.io UML state diagram
+ * Each FA is a separate container, sub-FAs are nested containers with light grey background
+ * Usage: node json-to-drawio.js <input-json> <output-drawio>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const ELK = require('elkjs').default;
+
+const elk = new ELK();
+
+// ============ MAIN ============
+async function main() {
+  const [inputJsonPath, outputDrawioPath] = process.argv.slice(2);
+  
+  if (!inputJsonPath || !outputDrawioPath) {
+    console.error('Usage: node json-to-drawio.js <input-json> <output-drawio>');
+    process.exit(1);
+  }
+
+  try {
+    const faData = JSON.parse(fs.readFileSync(inputJsonPath, 'utf-8'));
+    const drawio = await generateDrawio(faData);
+    
+    // Ensure output directory exists
+    const outputDir = path.dirname(outputDrawioPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    
+    fs.writeFileSync(outputDrawioPath, drawio);
+    console.log(`Generated: ${outputDrawioPath}`);
+  } catch (err) {
+    console.error('Error:', err.message);
+    process.exit(1);
+  }
+}
+
+// ============ CONVERSION LOGIC ============
+
+async function generateDrawio(faData) {
+  const allFaNames = Object.keys(faData);
+  const cellsMap = new Map();
+  const edgeList = [];
+  const stateNodeMap = new Map(); // `${faKey}:${state}` -> nodeId
+  
+  let containerYOffset = 20; // Track vertical position of containers
+  
+  // Process each FA and create its container with nested states
+  for (const faName of allFaNames) {
+    containerYOffset = await processFAWithContainer(faName, faData, allFaNames, cellsMap, edgeList, stateNodeMap, containerYOffset);
+  }
+  
+  // Convert to drawio
+  return buildDrawioXml(cellsMap, edgeList);
+}
+
+async function processFAWithContainer(faKey, faData, allFaNames, cellsMap, edgeList, stateNodeMap, containerYPos) {
+  const transitions = faData[faKey];
+  const states = new Set();
+  const exitStates = new Set();
+  const subFaStates = new Set();
+  
+  // Collect state information
+  for (const tr of transitions) {
+    const [from, signal, to] = tr;
+    states.add(from);
+    states.add(to);
+    
+    if (to.startsWith('E_')) {
+      exitStates.add(to);
+    }
+    if (allFaNames.includes(to)) {
+      subFaStates.add(to);
+    }
+  }
+  
+  // Build ELK graph structure for this FA's layout
+  const elkChildren = [];
+  const nodePositions = new Map(); // nodeId -> {x, y}
+  
+  // Initial state
+  const initId = `init-${faKey}`;
+  elkChildren.push({
+    id: initId,
+    width: 20,
+    height: 20
+  });
+  
+  // Other states
+  for (const state of states) {
+    if (state === 'I') continue;
+    
+    const nodeId = `state-${faKey}-${state}`;
+    let width = 120;
+    let height = 50;
+    
+    if (exitStates.has(state)) {
+      width = 70;
+      height = 70;
+    } else if (subFaStates.has(state)) {
+      // Sub-FA: much smaller size
+      width = 100;
+      height = 60;
+    }
+    
+    elkChildren.push({
+      id: nodeId,
+      width: width,
+      height: height,
+      labels: [{ text: state }]
+    });
+  }
+  
+  // Build ELK edges for this FA
+  const elkEdges = [];
+  for (const tr of transitions) {
+    const [from, signal, to] = tr;
+    const fromId = from === 'I' ? `init-${faKey}` : `state-${faKey}-${from}`;
+    const toId = `state-${faKey}-${to}`;
+    
+    elkEdges.push({
+      id: `tr-${faKey}-${from}-${to}`,
+      sources: [fromId],
+      targets: [toId],
+      labels: [{ text: signal }]
+    });
+  }
+  
+  // Layout this FA using ELK
+  const graph = {
+    id: `graph-${faKey}`,
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': 'DOWN',
+      'elk.spacing.nodeNode': '30',
+      'elk.spacing.edgeNode': '15',
+      'elk.layered.spacing.edgeNodeBetweenLayers': '20'
+    },
+    children: elkChildren,
+    edges: elkEdges
+  };
+  
+  try {
+    const layout = await elk.layout(graph);
+    
+    // Extract positions from layout
+    if (layout.children) {
+      for (const node of layout.children) {
+        nodePositions.set(node.id, { x: Math.round(node.x || 0), y: Math.round(node.y || 0) });
+      }
+    }
+  } catch (err) {
+    console.warn(`Warning: ELK layout failed for ${faKey}, using default positions`);
+  }
+  
+  // Create cells for this FA's states
+  // Initial state
+  const initPos = nodePositions.get(initId) || { x: 20, y: 20 };
+  cellsMap.set(initId, {
+    id: initId,
+    value: '',
+    style: `ellipse;whiteSpace=wrap;html=1;fillColor=#000000;strokeColor=#000000;sfsmRole=initial;sfsmFa=${faKey};`,
+    x: initPos.x,
+    y: initPos.y,
+    width: 20,
+    height: 20,
+    parent: `container-${faKey}`
+  });
+  stateNodeMap.set(`${faKey}:I`, initId);
+  
+  // Other states
+  for (const state of states) {
+    if (state === 'I') continue;
+    
+    const nodeId = `state-${faKey}-${state}`;
+    const pos = nodePositions.get(nodeId) || { x: 20, y: 80 };
+    let style = '';
+    let width = 120;
+    let height = 50;
+    
+    if (exitStates.has(state)) {
+      style = `ellipse;whiteSpace=wrap;html=1;strokeWidth=3;fillColor=#FFFFFF;sfsmRole=exit;sfsmFa=${faKey};sfsmKey=${state};`;
+      width = 70;
+      height = 70;
+    } else if (subFaStates.has(state)) {
+      // Sub-FA: light grey container, smaller size
+      style = `rounded=0;whiteSpace=wrap;html=1;fillColor=#E8E8E8;strokeColor=#999999;strokeWidth=2;sfsmRole=subfa;sfsmFa=${faKey};sfsmKey=${state};`;
+      width = 100;
+      height = 60;
+    } else {
+      style = `rounded=1;whiteSpace=wrap;html=1;arcSize=20;sfsmRole=state;sfsmFa=${faKey};sfsmKey=${state};`;
+    }
+    
+    cellsMap.set(nodeId, {
+      id: nodeId,
+      value: state,
+      style: style,
+      x: pos.x,
+      y: pos.y,
+      width: width,
+      height: height,
+      parent: `container-${faKey}`
+    });
+    stateNodeMap.set(`${faKey}:${state}`, nodeId);
+  }
+  
+  // Calculate container size based on layout
+  let maxX = 40;
+  let maxY = 40;
+  for (const [, pos] of nodePositions) {
+    maxX = Math.max(maxX, pos.x + 150);
+    maxY = Math.max(maxY, pos.y + 100);
+  }
+  
+  const containerWidth = Math.max(280, maxX + 40);
+  const containerHeight = Math.max(140, maxY + 40);
+  
+  // Create container for FA at specified Y position
+  const containerId = `container-${faKey}`;
+  cellsMap.set(containerId, {
+    id: containerId,
+    value: faKey,
+    style: `swimlane;whiteSpace=wrap;html=1;startSize=35;fontStyle=1;rounded=1;sfsmRole=facontainer;sfsmFa=${faKey};`,
+    x: 20,
+    y: containerYPos,
+    width: containerWidth,
+    height: containerHeight,
+    parent: '1'
+  });
+  
+  // Create transitions
+  let transitionCounter = 0;
+  for (const tr of transitions) {
+    const [from, signal, to, command] = tr;
+    const fromState = from === 'I' ? 'I' : from;
+    const sourceId = stateNodeMap.get(`${faKey}:${fromState}`);
+    const targetId = stateNodeMap.get(`${faKey}:${to}`);
+    
+    if (!sourceId || !targetId) continue;
+    
+    const edgeLabel = command ? `${signal} / ${to}:${command}` : signal;
+    const edgeId = `tr-${faKey}-${transitionCounter++}`;
+    const isLoop = from === to;
+    
+    let style = `edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;sfsmRole=transition;sfsmFa=${faKey};sfsmSignal=${signal};sfsmCommand=${command || ''};`;
+    if (isLoop) {
+      style += `exitX=0.25;exitY=0;exitDx=0;exitDy=0;entryX=0.75;entryY=0;entryDx=0;entryDy=0;`;
+    }
+    
+    edgeList.push({
+      id: edgeId,
+      value: edgeLabel,
+      style: style,
+      source: sourceId,
+      target: targetId,
+      parent: '1'
+    });
+  }
+  
+  // Return next Y position for next container (with some spacing)
+  return containerYPos + containerHeight + 30;
+}
+
+function buildDrawioXml(cellsMap, edgeList) {
+  let xml = `<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="Electron">
+  <diagram id="sfsm-diagram" name="Page-1">
+    <mxGraphModel dx="800" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+`;
+  
+  for (const [cellId, cell] of cellsMap) {
+    xml += `        <mxCell id="${cell.id}" value="${escapeXml(cell.value)}" style="${cell.style}" vertex="1" parent="${cell.parent}">
+          <mxGeometry x="${cell.x}" y="${cell.y}" width="${cell.width}" height="${cell.height}" as="geometry"/>
+        </mxCell>
+`;
+  }
+  
+  for (const edge of edgeList) {
+    xml += `        <mxCell id="${edge.id}" value="${escapeXml(edge.value)}" style="${edge.style}" edge="1" parent="${edge.parent}" source="${edge.source}" target="${edge.target}">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+`;
+  }
+  
+  xml += `      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>`;
+  
+  return xml;
+}
+
+function escapeXml(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+main();

package/tutorial/01-finite-state-machine.md

@@ -0,0 +1,223 @@
+# StOP Tutorial. Part 1; Finite State Machines
+
+## 1. What is a Finite Automaton?
+
+Mountains of scientific and educational books and articles have been written about finite automata (FA), which manage in an amazing way to not only confuse the reader, but also to frighten practitioners away from using them.
+
+However, the basic idea of a finite automaton is as simple as it is fundamental. 
+
+Namely. We have:
+- **A finite set of states** in which some object can exist, one of which is the initial state
+- **A finite number of signals** that can be sent to this object and possibly lead to a change in its state, i.e., a transition from the current state to another
+
+All the magic of finite automata is based on this simple idea.
+
+To define a specific finite automaton, you need to specify a list of its states (States S), signals (Signals G), and transitions (Transitions T) in the form of a list of triples:
+
+`<s0, g, s1>`, where:
+- `s0` - the state in which the automaton is currently located (initially - the starting state)
+- `g` - the signal
+- `s1` - the state to which our object will transition after receiving the signal
+
+Of course, we don't need states in S and signals in G that are not represented in T in any way. For practical use, some other constraints are also important, but we won't delve into the depths of theory for now, and will move on to a concrete programming example.
+
+Let's examine the use of a finite automaton (FA) using the example of a very simple automaton - a primitive turnstile that lets someone into the metro or a paid restroom after they drop a coin or special token into its slot.
+
+Like this:
+
+![Turnstile](./images/Turnstile-img.png)
+
+This automaton has two states: **locked** and **unlocked**, and two signals: **coin received** (coin) and **person passed through** (push).
+
+## 2. Defining the turnstile with the StOP library
+
+The [TypeScript StOP library](https://github.com/vsirotin/StOP) processes finite automata with the `Sfsm` engine (available from the `@vsirotin/ts-stop` package). 
+
+SFSM stands for "Stacked Finite State Machine" — a finite automaton that can contain other finite automata as sub-machines, and can be stacked into hierarchies of arbitrary depth. The turnstile is a simple FA with no children, so it is a good starting point for our tutorial. Because of its simple behaviour we talk about finite automata (FA) and not about finite machines.
+
+Some FA is described as a list of transitions, each one a triple (or, when a command must be sent, a quadruple — covered in a later chapter):
+
+```
+[s0, g, s1]
+```
+
+which is a direct, literal translation of the `<s0, g, s1>` triples introduced above. This representation is convenient when a FA is small — for large, dense automata you may prefer other representations, but that is out of scope here.
+
+One detail of the `Sfsm` engine is important to know from the very first example: every FA always starts in a reserved entry state named `"I"` or, by complex machines with `"*.I"`, e.g. `"BCC.I"`, that means `initial state`. This is not part of the pure theory above — it is a small, deliberate engine convention that becomes very useful once FAs are combined into hierarchies (a topic of a later chapter). For now, it simply means our turnstile needs one extra transition out of `"I"` into its real initial state, triggered by an explicit "start" signal.
+
+Here is the complete turnstile FA, written as compact JSON:
+
+```json
+{
+  "Turnstile": [
+    ["I",       "Start", "Locked"],
+    ["Locked",  "Coin",  "Unlocked"],
+    ["Unlocked","Push",  "Locked"]
+  ]
+}
+```
+
+This FA can be visually presented as a simple state diagram:
+![Turnstile](./images/TurnstileBaseFA.png)
+
+And here is how it is loaded and driven with the `Sfsm` class:
+
+```typescript
+import { Sfsm, FaDefinition } from '@vsirotin/ts-stop/sfsm';
+import turnstileFa from './turnstile-fa.json';
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileFa as FaDefinition);
+
+sfsm.getHeadState();          // 'I'  — the reserved entry state
+
+sfsm.receiveSignal('start');
+sfsm.getHeadState();          // 'locked'
+
+sfsm.receiveSignal('coin');
+sfsm.getHeadState();          // 'unlocked'
+
+sfsm.receiveSignal('push');
+sfsm.getHeadState();          // 'locked'
+```
+
+A runnable version of this exact example is available as a unit test: [01-what-is-a-finite-automaton.test.ts](../../ts-stop/test/sfsm/tutorial/01-what-is-a-finite-automaton.test.ts).
+
+### 2.1 A type-safe alternative
+
+The plain-string form above is convenient, but nothing stops a typo like `"lokced"` from silently compiling — the `Transition` type accepts any string in each slot. If you would rather have the TypeScript compiler catch such typos, declare your states and signals as string-literal union types first, and write the transition list against them with a small generic helper:
+
+```typescript
+import { Sfsm, FaDefinition, Transition } from '@vsirotin/ts-stop/sfsm';
+
+type TurnstileState = 'I' | 'locked' | 'unlocked';
+type TurnstileSignal = 'start' | 'coin' | 'push';
+
+// A transition restricted to a specific pair of state/signal literal types.
+type TypedTransition<S extends string, G extends string> = [S, G, S];
+
+// Accepts only transitions built from S/G, returns the plain runtime Transition[]
+// that Sfsm actually consumes — no change to the library's runtime format.
+function typedTransitions<S extends string, G extends string>(
+    transitions: Array<TypedTransition<S, G>>
+): Transition[] {
+    return transitions;
+}
+
+const turnstileTransitions = typedTransitions<TurnstileState, TurnstileSignal>([
+    ['I',        'start', 'locked'],
+    ['locked',   'coin',  'unlocked'],
+    ['unlocked', 'push',  'locked'],
+    // ['locked', 'coin', 'lokced'],   // ✗ compile error: 'lokced' is not TurnstileState
+]);
+
+const turnstileFa: FaDefinition = { Turnstile: turnstileTransitions };
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileFa);
+```
+
+This costs nothing at runtime — `typedTransitions()` just returns its argument — but any misspelled state or signal name is now a compile-time error instead of a silent bug. A runnable version of this example is available as a unit test: [02-type-safe-fa-definition.test.ts](../../ts-stop/test/sfsm/tutorial/02-type-safe-fa-definition.test.ts).
+
+
+## 3. Jokers: wildcard signals and states
+
+Writing out every single `<s0, g, s1>` transition by hand works well for a tidy, well-behaved automaton like our turnstile. Real devices, however, are messier: they can receive signals nobody planned for, and they can be told to do the same thing no matter what they happen to be doing at the time. Enumerating every combination by hand would make the transition list explode and, worse, would be all too easy to forget a case.
+
+For this, the `Sfsm` engine supports **jokers** — a reserved value (`"*"` by default) that can stand in for "any signal" or "any state" in a transition:
+
+- A **joker-signal** transition `[s0, "*", s1]` matches *any* signal while the automaton is in state `s0` — but only as a fallback: if a transition for the exact, literal signal already exists for `s0`, that one wins.
+- A **joker-state** transition `["*", g, s1]` matches signal `g` from *any* current state — again only as a fallback, behind any transition that names the exact, literal state.
+
+Because jokers are only a fallback, you can freely mix them with ordinary transitions without worrying about ordering: an exact match always takes priority, so the recommendation is simply to place joker transitions last in the list, purely for readability.
+
+Jokers are configured through `SfsmOptions` when constructing the engine:
+
+```typescript
+const sfsm = new Sfsm({
+  jokerSignal: '*', // default — the value that means "any signal"
+  jokerState:  '*'  // default — the value that means "any state"
+});
+```
+
+You will rarely need to change these from the default `"*"`; the option exists mainly so you can pick a different symbol if `"*"` ever needs to be a real state or signal name in your own FA.
+
+### 3.1 Joker signal: reacting to the unexpected (e.g. a power failure)
+
+Imagine our turnstile's electronics can, at any moment, receive all sorts of diagnostic signals from its sensors — most of which are irrelevant, except that *any* signal that isn't part of its normal vocabulary (`coin`, `push`) should be treated as a sign that something is wrong (power dropping out, a sensor glitching, a cable disconnected...) and the safest reaction is to shut the turnstile down into a safe `off` state.
+
+Instead of trying to list every possible malfunction signal, one joker-signal transition per operational state covers all of them at once:
+
+```json
+{
+  "Turnstile": [
+    ["I",        "start", "locked"],
+    ["locked",   "coin",  "unlocked"],
+    ["unlocked", "push",  "locked"],
+    ["locked",   "*",     "off"],
+    ["unlocked", "*",     "off"]
+  ]
+}
+```
+
+```typescript
+import { Sfsm, FaDefinition } from '@vsirotin/ts-stop/sfsm';
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileWithJokerSignalFa as FaDefinition);
+
+sfsm.receiveSignal('start');
+sfsm.getHeadState();             // 'locked'
+
+sfsm.receiveSignal('coin');
+sfsm.getHeadState();             // 'unlocked'  (exact transition still wins)
+
+sfsm.receiveSignal('powerFailure');
+sfsm.getHeadState();             // 'off'       (joker-signal fallback)
+```
+
+The turnstile keeps behaving exactly as before for `coin` and `push`; only signals it has no explicit rule for fall through to `*` and trigger the safety shutdown.
+
+A runnable version of this example is available as a unit test: [03-joker-signal.test.ts](../../ts-stop/test/sfsm/tutorial/03-joker-signal.test.ts).
+
+### 3.2 Joker state: a universal signal for technical personnel
+
+Now imagine the opposite situation: a maintenance technician needs to send a `service` signal that must always work, no matter what the turnstile happens to be doing — locked, unlocked, mid-transaction, or even already `off`. The technician should not need to know (or care) about the turnstile's current state; they just need "put this thing into maintenance mode, now."
+
+A single joker-state transition expresses exactly that, regardless of how many operational states the FA has:
+
+```json
+{
+  "Turnstile": [
+    ["I",        "start",   "locked"],
+    ["locked",   "coin",    "unlocked"],
+    ["unlocked", "push",    "locked"],
+    ["*",        "service", "maintenance"]
+  ]
+}
+```
+
+```typescript
+import { Sfsm, FaDefinition } from '@vsirotin/ts-stop/sfsm';
+
+const sfsm = new Sfsm();
+sfsm.loadFA(turnstileWithJokerStateFa as FaDefinition);
+
+sfsm.receiveSignal('start');
+sfsm.receiveSignal('service');
+sfsm.getHeadState();             // 'maintenance' — reached straight from 'locked'
+
+// ...and it works the same from any other state:
+sfsm.loadFA(turnstileWithJokerStateFa as FaDefinition);
+sfsm.receiveSignal('start');
+sfsm.receiveSignal('coin');      // now 'unlocked'
+sfsm.receiveSignal('service');
+sfsm.getHeadState();             // 'maintenance' — reached just as easily from 'unlocked'
+```
+
+One transition now covers "enter maintenance mode" from every current and future state — including states added to the FA later, with no changes needed to the `service` rule itself.
+
+A runnable version of this example is available as a unit test: [03-joker-state.test.ts](../../ts-stop/test/sfsm/tutorial/03-joker-state.test.ts).
+
+In the [next chapter](./02-stacked-finite-state-machine.md) we will see how to combine multiple FAs into a hierarchy, and how the `Sfsm` engine processes signals through that hierarchy.
+

package/tutorial/02-stacked-finite-state-machine.md

@@ -0,0 +1,32 @@
+# StOP Tutorial. Part 2: Stacked Finite State Machines
+
+## 4. What is a Stacked Finite State Machine (SFSM)?
+
+The turnstile so far is a single, flat automaton — a nice fit for the pure theory from chapter 1. Real systems, however, are rarely that simple: a "check the coin" step is itself a small process with its own states, and a "process a payment" step might contain both "check a coin" and "check a banknote" as alternatives inside it. Modelling all of that as one giant flat FA would quickly become unreadable.
+
+The **Stacked Finite State Machine (SFSM)** solves this by allowing a state to be, itself, another whole FA. This turns the picture from a single flat automaton into a **tree of FAs**: a root FA at the top, and any number of nested child FAs underneath it (each of which can itself have children, and so on). The SFSM engine (the `Sfsm` class) keeps an internal **stack** of currently-active FAs to process this tree: the bottom of the stack is always the root FA, and the top (the "head") is whichever FA is currently handling incoming signals. The stack grows (push) when a state turns out to be a sub-FA, and shrinks (pop) when a sub-FA finishes and control returns to its parent.
+
+Two small naming conventions make this hierarchy work uniformly for every FA, at any depth:
+- every FA has exactly one **entry state**, always named `"I"` or `"*.I"` (as already seen in chapters 1–3);
+- every FA has one or more **exit states**, each named starting with `"E_"` or `"*-E_"` — reaching one means "this FA is done, hand control back to whoever activated it."
+
+Here is a small, self-contained FA that only makes sense as a *child* of something bigger: it models checking a banknote offered as payment, without yet worrying about who offers it or what happens afterwards. It has one entry state, one "business" state per step, and three possible outcomes:
+
+```json
+{
+  "BPP": [
+    ["I",        "BR.bc",           "checking",  "BC.check"],
+    ["checking", "BC.pass",         "accepting", "BA.accept"],
+    ["checking", "BC.reject",       "E_rejected"],
+    ["accepting","BA.changeNeeded", "E_changeNeeded"],
+    ["accepting","BA.noChangeNeeded","E_noChangeNeeded"]
+  ]
+}
+```
+
+ Its real purpose, though, is to later become a *state* inside a bigger turnstile finite state machine (FSM), at which point reaching an exit state pops it and hands the triggering signal back to its parent instead of resetting. 
+
+A runnable version of this example is available as a unit test: [04-stacked-finite-state-machine.test.ts](../../ts-stop/test/sfsm/tutorial/04-stacked-finite-state-machine.test.ts).
+
+
+