@vedmalex/statemachine 1.0.0-beta.2 → 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.
 
@@ -61,7 +71,20 @@ const sm = createMachine({
 - **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.)
 
-See [`docs/regions-and-parallel.md`](./docs/regions-and-parallel.md) for the full model, ordering rules, and validation.
+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
 
@@ -71,13 +94,90 @@ Full API documentation: [https://vedmalex.github.io/statemachine/](https://vedma
 
 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.
 

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   StateMachineError: () => StateMachineError,
   createEnhancedError: () => createEnhancedError,
   createMachine: () => createMachine,
+  createVirtualScheduler: () => createVirtualScheduler,
   isAdapter: () => isAdapter,
   isRecoverableError: () => isRecoverableError,
   isValidConfig: () => isValidConfig,
@@ -53,7 +54,9 @@ var TimerScheduler = class {
   intervalId = null;
   pollingInterval = 100;
   // ms
-  constructor() {
+  clock;
+  constructor(clock = Date.now) {
+    this.clock = clock;
   }
   /**
    * Настройка режима опроса
@@ -77,7 +80,7 @@ var TimerScheduler = class {
    */
   start() {
     if (this.intervalId) return;
-    this.intervalId = setInterval(() => this.process(), this.pollingInterval);
+    this.intervalId = setInterval(() => this.process(this.clock()), this.pollingInterval);
   }
   /**
    * Остановка единого таймера
@@ -96,7 +99,7 @@ var TimerScheduler = class {
    */
   schedule(delay, callback) {
     const token = {};
-    const executeAt = Date.now() + delay;
+    const executeAt = this.clock() + delay;
     const task = { token, executeAt, callback };
     this.activeTokens.add(token);
     this.insert(task);
@@ -112,7 +115,7 @@ var TimerScheduler = class {
   /**
    * Обработать очередь (вызывается таймером или вручную)
    */
-  process(now = Date.now()) {
+  process(now = this.clock()) {
     while (this.heap.length > 0) {
       const task = this.heap[0];
       if (task === void 0) break;
@@ -203,6 +206,23 @@ var TimerScheduler = class {
 function createDefaultScheduler() {
   return new TimerScheduler();
 }
+function createVirtualScheduler(clock) {
+  const inner = new TimerScheduler(clock);
+  return {
+    isActive() {
+      return true;
+    },
+    schedule(delay, callback) {
+      return inner.schedule(delay, callback);
+    },
+    cancel(token) {
+      inner.cancel(token);
+    },
+    process(now) {
+      inner.process(now ?? clock());
+    }
+  };
+}
 
 // src/logger.ts
 var LogLevel = {
@@ -1749,6 +1769,8 @@ var StateMachine = class _StateMachine {
   monitor;
   scheduler;
   errorHandler;
+  clock;
+  schedulerProvided;
   // Свойства
   states;
   events;
@@ -1799,7 +1821,9 @@ var StateMachine = class _StateMachine {
     this.initialState = config.initialState;
     this.logger = options?.logger ?? ConsoleLogger;
     this.monitor = options?.monitor ?? createDefaultMonitor();
+    this.schedulerProvided = options?.scheduler !== void 0;
     this.scheduler = options?.scheduler ?? createDefaultScheduler();
+    this.clock = options?.clock ?? Date.now;
     this.errorHandler = options?.errorHandler ?? createDefaultErrorHandler();
     if (adaptee) {
       if (!isAdapter(adaptee)) {
@@ -1873,7 +1897,7 @@ var StateMachine = class _StateMachine {
           args,
           resolve,
           reject,
-          timestamp: Date.now(),
+          timestamp: this.clock(),
           type: "external"
         });
         this.scheduleProcessing();
@@ -1884,7 +1908,7 @@ var StateMachine = class _StateMachine {
       eventName,
       obj,
       args,
-      timestamp: Date.now(),
+      timestamp: this.clock(),
       type: "internal"
     });
     return Promise.resolve(true);
@@ -1895,7 +1919,7 @@ var StateMachine = class _StateMachine {
       eventName,
       obj,
       args,
-      timestamp: Date.now(),
+      timestamp: this.clock(),
       type: "internal"
     });
   }
@@ -2056,7 +2080,7 @@ var StateMachine = class _StateMachine {
     };
   }
   getQueuedEvents() {
-    const now = Date.now();
+    const now = this.clock();
     const mapEvent = (evt) => ({
       id: evt.id,
       event: evt.eventName,
@@ -2175,53 +2199,51 @@ var StateMachine = class _StateMachine {
     return currentParts.every((part, index) => part === expectedParts[index]);
   }
   attachToObject(object, eventMap) {
-    for (const objectEventName in eventMap) {
-      if (eventMap.hasOwnProperty(objectEventName)) {
-        const stateMachineEventName = eventMap[objectEventName];
-        if (stateMachineEventName === void 0) continue;
-        if (typeof object.addEventListener === "function") {
-          object.addEventListener(objectEventName, (...args) => {
-            this.fireEvent(stateMachineEventName, object, ...args).catch(
-              (e) => this.logger.error(
-                "Error firing event",
-                {
-                  objectEventName,
-                  stateMachineEventName
-                },
-                /* c8 ignore next */
-                e instanceof Error ? e : new Error(String(e))
-              )
-            );
-          });
-        } else if (typeof object.on === "function") {
-          object.on(objectEventName, (...args) => {
-            this.fireEvent(stateMachineEventName, object, ...args).catch(
-              (e) => this.logger.error(
-                "Error firing event",
-                {
-                  objectEventName,
-                  stateMachineEventName
-                },
-                /* c8 ignore next */
-                e instanceof Error ? e : new Error(String(e))
-              )
-            );
-          });
-        } else {
-          object[`on${objectEventName}`] = async (...args) => {
-            return this.fireEvent(stateMachineEventName, object, ...args).catch(
-              (e) => this.logger.error(
-                "Error firing event",
-                {
-                  objectEventName,
-                  stateMachineEventName
-                },
-                /* c8 ignore next */
-                e instanceof Error ? e : new Error(String(e))
-              )
-            );
-          };
-        }
+    for (const objectEventName of Object.keys(eventMap)) {
+      const stateMachineEventName = eventMap[objectEventName];
+      if (stateMachineEventName === void 0) continue;
+      if (typeof object.addEventListener === "function") {
+        object.addEventListener(objectEventName, (...args) => {
+          this.fireEvent(stateMachineEventName, object, ...args).catch(
+            (e) => this.logger.error(
+              "Error firing event",
+              {
+                objectEventName,
+                stateMachineEventName
+              },
+              /* c8 ignore next */
+              e instanceof Error ? e : new Error(String(e))
+            )
+          );
+        });
+      } else if (typeof object.on === "function") {
+        object.on(objectEventName, (...args) => {
+          this.fireEvent(stateMachineEventName, object, ...args).catch(
+            (e) => this.logger.error(
+              "Error firing event",
+              {
+                objectEventName,
+                stateMachineEventName
+              },
+              /* c8 ignore next */
+              e instanceof Error ? e : new Error(String(e))
+            )
+          );
+        });
+      } else {
+        object[`on${objectEventName}`] = async (...args) => {
+          return this.fireEvent(stateMachineEventName, object, ...args).catch(
+            (e) => this.logger.error(
+              "Error firing event",
+              {
+                objectEventName,
+                stateMachineEventName
+              },
+              /* c8 ignore next */
+              e instanceof Error ? e : new Error(String(e))
+            )
+          );
+        };
       }
     }
   }
@@ -3011,19 +3033,22 @@ var StateMachine = class _StateMachine {
       }
     };
     if (this.transitionTimeout && this.transitionTimeout > 0) {
-      return Promise.race([
-        executeAction(),
-        new Promise(
-          (_, reject) => setTimeout(
-            () => reject(new StateMachineError("Transition timeout", {
-              /* c8 ignore next */
-              action: typeof actionName === "string" ? actionName : "anonymous",
-              phase: "action"
-            })),
-            this.transitionTimeout
-          )
-        )
-      ]);
+      const timeoutMs = this.transitionTimeout;
+      let timeoutHandle;
+      const timeoutPromise = new Promise((_, reject) => {
+        const fire = () => reject(new StateMachineError("Transition timeout", {
+          /* c8 ignore next */
+          action: typeof actionName === "string" ? actionName : "anonymous",
+          phase: "action"
+        }));
+        timeoutHandle = this.setTimer(fire, timeoutMs);
+      });
+      if (this.schedulerProvided) {
+        return Promise.race([executeAction(), timeoutPromise]).finally(() => {
+          this.clearTimer(timeoutHandle);
+        });
+      }
+      return Promise.race([executeAction(), timeoutPromise]);
     }
     return executeAction();
   }
@@ -3240,7 +3265,7 @@ var StateMachine = class _StateMachine {
     }
     if (toState.invoke && toState.invoke.length > 0) {
       if (!this.stateEntryTimes.has(toStateName)) {
-        this.stateEntryTimes.set(toStateName, Date.now());
+        this.stateEntryTimes.set(toStateName, this.clock());
       }
       const timers = [];
       for (const invocation of toState.invoke) {
@@ -3286,6 +3311,9 @@ var StateMachine = class _StateMachine {
    */
   setTimer(callback, delay) {
     const scheduler = this.scheduler;
+    if (this.schedulerProvided) {
+      return scheduler.schedule(delay, callback);
+    }
     if (scheduler.isActive()) {
       return scheduler.schedule(delay, callback);
     }
@@ -3296,6 +3324,10 @@ var StateMachine = class _StateMachine {
    */
   clearTimer(timerId) {
     const scheduler = this.scheduler;
+    if (this.schedulerProvided) {
+      if (timerId !== void 0) scheduler.cancel(timerId);
+      return;
+    }
     if (scheduler.isActive() && typeof timerId === "object" && timerId !== null && !("ref" in timerId)) {
       scheduler.cancel(timerId);
     } else {
@@ -3453,13 +3485,13 @@ var StateMachine = class _StateMachine {
         this.stateEntryTimes.delete(stateName);
       }
     }
-    const now = Date.now();
+    const now = this.clock();
     for (const stateName of activeStates) {
       const state = this.states.get(stateName);
       if (!state || !state.invoke || state.invoke.length === 0) continue;
       const entryTime = this.stateEntryTimes.get(stateName);
-      const startTime = entryTime || now;
-      if (!entryTime) {
+      const startTime = entryTime ?? now;
+      if (entryTime === void 0) {
         this.stateEntryTimes.set(stateName, startTime);
       }
       const elapsed = now - startTime;
@@ -4396,6 +4428,7 @@ function isValidConfig(config) {
   StateMachineError,
   createEnhancedError,
   createMachine,
+  createVirtualScheduler,
   isAdapter,
   isRecoverableError,
   isValidConfig,