@vedmalex/statemachine 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -3,7 +3,17 @@
 [![CI](https://github.com/vedmalex/statemachine/actions/workflows/ci.yml/badge.svg)](https://github.com/vedmalex/statemachine/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@vedmalex/statemachine?label=npm)](https://www.npmjs.com/package/@vedmalex/statemachine)
 
-Hierarchical state machine for TypeScript with monitoring, validation, and persistence.
+Hierarchical state machine for TypeScript with orthogonal (parallel) regions, SCXML/UML entry-exit semantics, monitoring, validation, and persistence.
+
+**Features:**
+
+- Hierarchical (nested) states addressed by dotted paths
+- Orthogonal **parallel regions** with SCXML ancestor-first entry / descendant-first exit
+- **UML all-regions-final join** via `final` states, the engine-raised `done.state.<id>` event, and the `isDone()` guard
+- Parallel-exit (LCCA) — a transition from a composite parent preempts and exits all active regions
+- Guards, before/enter/after + exit/transition actions, and timed `invoke` transitions
+- Pluggable monitoring, validation, persistence, and timer scheduling (7 extension points)
+- ESM + CJS dual bundle; DI-free lite surface
 
 The package ships only the DI-free lite surface. The legacy DI-aware factory from `@grainjs/statemachine` is intentionally not carried over.
 
@@ -28,21 +38,146 @@ const sm = createMachine({
 })
 ```
 
+## Hierarchical regions, parallel states & join
+
+A state may declare `regions` to run several orthogonal sub-machines at once. Entry/exit follow SCXML/UML ordering, and a region may complete via a `final` state that raises a `done.state.<id>` join event.
+
+```ts
+const sm = createMachine({
+  name: 'proc',
+  initialState: 'proc',
+  states: {
+    proc: {
+      initial: 'a.run|b.run',          // both regions active in parallel
+      onEnter: () => {/* parent runs BEFORE region children (ancestor-first) */},
+      regions: {
+        a: { run: {}, done: { final: true } },
+        b: { run: {}, done: { final: true } },
+      },
+    },
+    complete: {},
+  },
+  events: {
+    finishA: { transitions: [{ from: 'proc.a.run', to: 'proc.a.done' }] },
+    finishB: { transitions: [{ from: 'proc.b.run', to: 'proc.b.done' }] },
+    // Join: raised automatically once EVERY region reached a `final` state.
+    'done.state.proc': { transitions: [{ from: 'proc', to: 'complete' }] },
+  },
+})
+```
+
+- **Expansion** — entering `proc` (as initial state *or* via a transition) expands to the parallel configuration `proc.a.run|proc.b.run`.
+- **Ordering** — entry is ancestor-first (`proc` then region children); exit is descendant-first (region children then `proc`).
+- **Parallel-exit** — a plain transition `from: 'proc'` on a user event preempts and exits all active regions immediately (LCCA).
+- **Join** — when all regions are `final`, the engine raises `done.state.proc`; `sm.isDone('proc')` reflects the all-final configuration. (`done.state.*` is never matched by a `from: '*'` wildcard.)
+
+Author the join either as the `done.state.<id>` transition above, **or** as a guard on any event:
+
+```ts
+events: {
+  tryFinish: {
+    // fires only once every region of `proc` has reached a `final` state
+    transitions: [{ from: 'proc', to: 'complete', guard: () => sm.isDone('proc') }],
+  },
+}
+```
+
+Composites nest: a parent's `done.state` is raised only after every region — **including any nested composite** — is final, innermost-first. `done.state.<id>` is edge-triggered (raised once on entering the done configuration, not re-raised while the composite merely stays all-final).
+
+See [`docs/regions-and-parallel.md`](./docs/regions-and-parallel.md) for the full model, ordering rules, nesting, and validation.
+
 ## Documentation
 
 Full API documentation: [https://vedmalex.github.io/statemachine/](https://vedmalex.github.io/statemachine/)
 
 ## Extension Points
 
-This package exposes 7 extension points (`IMonitor`, `ITimerScheduler`, `IErrorHandler`, `Adapter<T>`, `ILogger`, `StatePersistenceAdapter`, `validateConfig`) for host integration. See [`docs/extension-points.md`](./docs/extension-points.md) for the full catalog.
+This package exposes 7 extension points (`IMonitor`, `ITimerScheduler`, `IErrorHandler`, `Adapter<T>`, `ILogger`, `StatePersistenceAdapter`, `validateConfig`) for host integration. Callbacks resolved from config or `setContext()` receive the underlying owner object directly, so host code does not need to unwrap `Adapter<T>` inside each callback. See [`docs/extension-points.md`](./docs/extension-points.md) for the full catalog.
+
+## Deterministic testing (DST)
+
+Machines that use `invoke` delays or a `transitionTimeout` normally depend on real wall-clock time (`Date.now` + `setTimeout`). That makes tests slow, flaky, and sensitive to scheduling jitter. The DST API swaps the clock and the timer scheduler for virtual counterparts so timer-driven behavior replays deterministically with **zero** real time elapsed.
+
+```ts
+import { StateMachine, createVirtualScheduler } from '@vedmalex/statemachine'
+
+let t = 0
+const clock = () => t
+const scheduler = createVirtualScheduler(clock)
+
+const sm = new StateMachine(config, adapter, { clock, scheduler })
+// ... arm the initial state's invoke timers
+await Promise.resolve() // flush microtasks
+
+t = 1000
+scheduler.process() // fire every timer whose deadline <= 1000
+await Promise.resolve() // flush microtasks so the transition settles
+// assert sm.currentState === 'next'
+```
+
+### How it works
+
+- `clock` replaces `Date.now` for `stateEntryTimes`, `resumeTimers`, and `getQueuedEvents` age math (and for the event-queue timestamps those ages are measured against, so age stays coherent under virtual time).
+- `createVirtualScheduler(clock)` returns an `ITimerScheduler` whose `isActive()` is always `true`, so the `StateMachine` routes **all** `invoke` timers and the `transitionTimeout` through it.
+- An **explicitly provided** scheduler is always used — the machine never falls back to real `setTimeout` while one is injected.
+- `scheduler.process(now?)` drains every timer whose deadline `<= now` (default `now` is `clock()`), advancing zero real time. It is idempotent — draining twice does not re-fire a timer.
+- `invoke` callbacks are async (they raise an event and queue the transition on a microtask), so after each `process()` you must flush microtasks (`await Promise.resolve()`, a few times for chained transitions) before asserting.
+
+### Replaying serialized state
+
+`toJSON()` / `fromJSON()` round-trips the recorded entry times as raw numbers. Restore into a fresh machine whose clock already reads the serialize time, and the remaining invoke delay is recomputed correctly:
+
+```ts
+// Original machine, invoke delay 1000ms, entered at t=0:
+let t = 0
+const clock = () => t
+const sm = new StateMachine(config, adapter, { clock, scheduler: createVirtualScheduler(clock) })
+
+t = 400
+const json = sm.toJSON()           // snapshot 400ms in
+
+const scheduler2 = createVirtualScheduler(clock)
+const sm2 = StateMachine.fromJSON(json, freshAdapter, { clock, scheduler: scheduler2 })
+// 600ms remain:
+t = 1000
+scheduler2.process()               // the invoke fires here, not at t=1400
+```
+
+### transitionTimeout under virtual time
+
+The `transitionTimeout` deadline is also routed through the injected scheduler, so it triggers on a virtual-time advance rather than a real timer:
+
+```ts
+const sm = new StateMachine(config, adapter, { clock, scheduler, transitionTimeout: 500 })
+const fired = sm.fireEvent('go')   // enters a state whose action never resolves
+await Promise.resolve()
+t = 500
+scheduler.process()                // the race rejects deterministically
+await expect(fired).rejects.toThrow(/timeout/i)
+```
+
+When the action wins the race instead, the pending timeout token is auto-cancelled so no ghost rejection fires on a later `process()`.
+
+### Back-compatibility
+
+> Omitting **both** `clock` and `scheduler` keeps runtime behavior byte-identical to prior releases: `createDefaultScheduler()` uses `Date.now`, the `isActive()`-gated `setTimer` fallback to native `setTimeout` is unchanged, and `process()`'s default argument resolves to the same value it did before. The DST machinery only engages when you opt in by injecting a scheduler.
+
+### API reference
+
+| Symbol | Kind | Purpose |
+| --- | --- | --- |
+| `createVirtualScheduler(clock)` | function | Build a deterministic, non-real-time `ITimerScheduler`. |
+| `Clock` | type | `() => number`; matches the `clock` option signature. |
+| `StateMachineOptions.clock?` | option | Inject a virtual clock (default `Date.now`). |
+| `ITimerScheduler.process?(now?)` | method | Optional manual drain; implemented by `createVirtualScheduler`. |
 
 ## Stability policy
 
-5 firm `@stable` symbols: `createMachine`, `StateMachine`, `StateMachineConfig`, `Transition`, `State`. Other exports are `@unstable` and may evolve between minor versions. See [`STABILITY.md`](./STABILITY.md) for the full policy.
+5 firm `@stable` symbols: `createMachine`, `StateMachine`, `StateMachineConfig`, `Transition`, `State`. The all-regions-final join API lives on these stable symbols — `State.final?: boolean`, `StateMachine.isDone(compositeId)`, and the engine-raised `done.state.<id>` event (all reflected in `etc/statemachine.api.md`). Other exports are `@unstable` and may evolve between minor versions. See [`STABILITY.md`](./STABILITY.md) for the full policy.
 
 ## Status & module format
 
-`1.0.0-beta.x`. Stability: experimental. The full API surface is currently `@unstable` per the package's STABILITY policy; per-symbol stability tagging arrives before `1.0.0` stable.
+`1.0.0-beta.x` (current published version: see the npm badge above; both the `latest` and `beta` dist-tags track the newest release). Stability: experimental. SCXML/UML parallel regions, ancestor-first / descendant-first ordering, and the all-regions-final join landed in **`1.0.0-beta.2`**. The full API surface is `@unstable` per the package's STABILITY policy except the 5 firm `@stable` symbols; per-symbol stability tagging completes before `1.0.0` stable.
 
 **Module format**: ESM + CJS dual bundle (TASK-005). `require('@vedmalex/statemachine')` works in CommonJS runtimes via `dist/index.cjs`. `import` works via `dist/index.js`. The `exports` map resolves automatically.