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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vedmalex/statemachine",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "Hierarchical state machine for TypeScript with monitoring, validation, and persistence (lite-only DI-free surface).",
   "keywords": [
     "state-machine",
@@ -47,7 +47,7 @@
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
-    "check": "biome check . && tsc --noEmit",
+    "check": "biome check . && tsc --noEmit && knip --no-progress",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

package/types/index.d.ts

@@ -60,6 +60,29 @@ export type { IMonitor } from './types';
  * @unstable — timer scheduling injection contract; implement for WASM/host portability.
  */
 export type { ITimerScheduler } from './types';
+/**
+ * @category Unstable
+ * @unstable — virtual-clock type alias; matches the `clock` option in StateMachineOptions.
+ */
+export type { Clock } from './scheduler';
+/**
+ * @category Unstable
+ * @unstable — factory for a deterministic, non-real-time scheduler. Pass the
+ * returned scheduler together with the same `clock` function in StateMachine
+ * options to enable virtual-time (DST) testing without real setTimeout.
+ *
+ * @example
+ * ```ts
+ * let t = 0
+ * const clock = () => t
+ * const scheduler = createVirtualScheduler(clock)
+ * const sm = new StateMachine(config, adapter, { clock, scheduler })
+ * await Promise.resolve() // flush microtasks: enter initial state + arm invoke timers
+ * t = 1000
+ * scheduler.process() // advance virtual time to 1000 ms
+ * ```
+ */
+export { createVirtualScheduler } from './scheduler';
 /**
  * @category Unstable
  * @unstable — error-handler injection contract; implement to replace built-in recovery.

package/types/scheduler.d.ts

@@ -1,4 +1,9 @@
 import type { ITimerScheduler } from './types';
+/**
+ * Clock function type: returns the current virtual or real time in ms.
+ * Matches the signature of `Date.now`.
+ */
+export type Clock = () => number;
 /**
  * Тип для идентификатора таймера
  */
@@ -12,7 +17,8 @@ export declare class TimerScheduler {
     private activeTokens;
     private intervalId;
     private pollingInterval;
-    constructor();
+    private readonly clock;
+    constructor(clock?: Clock);
     /**
      * Настройка режима опроса
      * @param interval Интервал проверки в мс. Если 0 или null - авто-тик выключается (ручной режим)
@@ -62,4 +68,28 @@ export declare class TimerScheduler {
  * Same-module placement required: TimerScheduler constructor is public within module.
  */
 export declare function createDefaultScheduler(): ITimerScheduler;
+/**
+ * Returns a deterministic virtual-time scheduler driven entirely by the
+ * supplied `clock` function. Intended for tests, simulation, and DST.
+ *
+ * Guarantees:
+ *  - `isActive()` always returns `true` — StateMachine routes all timers
+ *    through it and never touches real `setTimeout`/`setInterval`.
+ *  - No real timer is ever created.
+ *  - `schedule(delay, cb)` queues a task at `clock() + delay`.
+ *  - `process(now?)` drains every task whose `executeAt <= now`
+ *    (default `now` is `clock()`).
+ *
+ * @example
+ * ```ts
+ * let t = 0
+ * const clock = () => t
+ * const scheduler = createVirtualScheduler(clock)
+ * const sm = new StateMachine(config, adaptee, { clock, scheduler })
+ * await Promise.resolve() // flush microtasks: enter initial state + arm invoke timers
+ * t = 1000
+ * scheduler.process() // fires all tasks due by t=1000
+ * ```
+ */
+export declare function createVirtualScheduler(clock: Clock): ITimerScheduler;
 export {};

package/types/state_machine.d.ts

@@ -18,6 +18,8 @@ export declare class StateMachine<TOwner extends object, SMConfig extends StateM
     private monitor;
     private scheduler;
     private errorHandler;
+    private clock;
+    private schedulerProvided;
     private states;
     private events;
     private stateAttribute;

package/types/types.d.ts

@@ -34,6 +34,12 @@ export interface ITimerScheduler {
     isActive(): boolean;
     schedule(delay: number, callback: () => void): object;
     cancel(token: object): void;
+    /**
+     * Optional manual drain — advance virtual time and fire all timers whose
+     * `executeAt <= now` (default `now` is the scheduler's own clock). Real-time
+     * schedulers driven by setInterval may leave this unimplemented.
+     */
+    process?(now?: number): void;
 }
 /** @unstable — transition observability context (additive on IMonitor). */
 export interface TransitionContext {
@@ -74,6 +80,13 @@ export interface StateMachineOptions {
     monitor?: IMonitor;
     scheduler?: ITimerScheduler;
     errorHandler?: IErrorHandler;
+    /**
+     * Clock function returning the current time in milliseconds.
+     * Default: `Date.now`. Inject a virtual clock together with a
+     * `scheduler` (see `createVirtualScheduler`) for deterministic replay / DST.
+     * Used for `stateEntryTimes`, `resumeTimers`, and `getQueuedEvents` age math.
+     */
+    clock?: () => number;
     /**
      * Maximum time (ms) to wait for async entry/exit actions.
      * If exceeded, the transition aborts with an error.