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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vedmalex/statemachine",
-  "version": "1.0.0-beta.1",
+  "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",
@@ -45,6 +45,9 @@
     "clean": "rm -rf dist types coverage tsconfig.tsbuildinfo",
     "build": "npm run clean && tsup && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check . && tsc --noEmit && knip --no-progress",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -53,11 +56,12 @@
     "test:browser": "playwright test",
     "knip": "knip --no-progress",
     "api:check": "api-extractor run --local --verbose",
-    "prepublishOnly": "npm run build && node test/verify-dist.cjs"
+    "prepublishOnly": "npm run check && npm run build && node test/verify-dist.cjs"
   },
   "dependencies": {},
   "peerDependencies": {},
   "devDependencies": {
+    "@biomejs/biome": "2.4.14",
     "@changesets/cli": "^2.31.0",
     "@microsoft/api-extractor": "^7.58.7",
     "@playwright/test": "^1.59.1",

package/types/config_validator.d.ts

@@ -65,6 +65,38 @@ export declare class ConfigValidator {
     private validateInitialState;
     private validateCrossReferences;
     private collectStateNames;
+    /**
+     * Collects every state in the tree as {dottedPath, config} entries, walking
+     * region containers (region names are NOT registered states, so they are part
+     * of the path but never emitted as an entry — mirroring runtime expansion).
+     */
+    private collectStateEntries;
+    /**
+     * True when `composite` has at least one `final:true` atomic substate reachable
+     * through its (possibly nested) region tree — i.e. some region of the composite
+     * can become done. Used by REGION_NO_REACHABLE_FINAL.
+     */
+    private hasReachableFinal;
+    /**
+     * SCXML/UML final-state and all-regions-final (done.state.<C>) join validation.
+     *
+     * - FINAL_STATE_HAS_OUTGOING (error): a `final:true` state is the `from` of a
+     *   transition (a final pseudo-state cannot itself transition out).
+     * - FINAL_ON_COMPOSITE (warning): `final:true` on a state that has regions
+     *   (final is meaningful only on an atomic leaf; ignored at runtime).
+     * - REGION_NO_REACHABLE_FINAL (warning): a `done.state.<C>` transition exists
+     *   but composite C declares no `final` substate, so the join can never fire.
+     * - DONE_VS_PARALLEL_EXIT_AMBIGUITY (warning): the same composite C has BOTH a
+     *   `done.state.C` join AND a plain `from:'C'` user-event parallel-exit, which
+     *   can preempt the all-final join (the user event is eligible on ANY leaf).
+     * - REGION_MISSING_INITIAL (advisory warning, valid:true): a region omits an
+     *   explicit `initial`, so expansion relies on first-key insertion order.
+     */
+    private validateFinalStates;
+    /**
+     * Collects the dotted paths of every `final:true` atomic leaf in the tree.
+     */
+    private collectFinalStatePaths;
     private validatePerformanceConstraints;
     private countStates;
     private addError;

package/types/index.d.ts

@@ -37,6 +37,16 @@ export type { State } from './types';
  * @category Unstable
  */
 export type { States, Events, Event, Adapter, StateMachineOptions, RegionsConfig, StateInvocation, StateName, EventName, RegionName, EventAction, ErrorHandler, ActionOrString, ErrorHandlerOrString, RegionStateName, NestedStateName, DeepNestedStateName, StatePaths, SimpleStateName, MethodsOf, PropertiesOf, KeysOf, ExtractAdaptee, ErrorContext, } from './types';
+/**
+ * @category Unstable
+ * @unstable — validation preset/config shape used by validation helpers and presets.
+ */
+export type { ValidationConfig } from './config_validator';
+/**
+ * @category Unstable
+ * @unstable — monitoring preset/config shape used by monitoring helpers and presets.
+ */
+export type { MonitoringConfig } from './monitoring';
 export { MemoryAdapter, LocalStorageAdapter, SessionStorageAdapter, ServerAdapter, StateMachineError, isAdapter, } from './types';
 export { createEnhancedError, EnhancedStateMachineError, ErrorAnalytics, ErrorCategory, type ErrorCategory as ErrorCategoryType, ErrorHandler as EnhancedErrorHandler, type ErrorRecoveryStrategy, ErrorSeverity, type ErrorSeverity as ErrorSeverityType, type ExtendedErrorContext, FallbackStateRecoveryStrategy, isRecoverableError, RetryRecoveryStrategy, } from './error_handling';
 export { validateConfig, validateConfigStrict, isValidConfig, type ValidationResult, type ValidationError, type ValidationWarning, } from './config_validator';
@@ -50,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;
@@ -47,6 +49,7 @@ export declare class StateMachine<TOwner extends object, SMConfig extends StateM
     get currentState(): string;
     constructor(config: SMConfig, adaptee?: Adapter<PropertiesOf<TOwner>> | PropertiesOf<TOwner>, options?: StateMachineOptions);
     setContext(context: MethodsOf<TOwner>): void;
+    private resolveCallbackOwner;
     private enqueueEvent;
     private raiseEvent;
     private scheduleProcessing;
@@ -145,6 +148,106 @@ export declare class StateMachine<TOwner extends object, SMConfig extends StateM
     private getInitialCompositeState;
     private getDirectChildren;
     private getInitialStatesForRegions;
+    /**
+     * Whether `leaf` is a UML/SCXML `<final>` atomic state of its region.
+     *
+     * Reads the `final` marker straight from the flattened state map populated by
+     * processStates, so it works for any registered atomic leaf regardless of
+     * nesting depth. Returns `false` for unregistered names and for composites
+     * (the all-regions-final join derives doneness from atomic leaves, not from a
+     * `final` flag on a composite parent).
+     */
+    private isStateFinal;
+    /**
+     * Whether composite `compositeId` has reached its UML/SCXML "done"
+     * configuration: every one of its regions has its active atomic leaf in a
+     * `final` state (recursively, for nested composites).
+     *
+     * D10 (mustFix): doneness is derived by scanning the active atomic `|`-leaves
+     * against the STATIC regions tree (`this.states.get(C)?.regions`), NEVER via a
+     * region-key Map lookup (`configMap.get`) — that map keys leaves by their
+     * deepest region container and so cannot answer "which leaf is active in
+     * region X of composite C". For each region we locate the active leaf via the
+     * `C.region.` dotted prefix; the region is final iff that leaf is `final`, or
+     * the leaf lives under a nested composite that is itself `isCompositeDone`.
+     *
+     * Returns `false` for a non-composite id, for a composite with no active leaf
+     * in some region, or when no substate under it is ever `final` (cheap miss).
+     */
+    private isCompositeDone;
+    /**
+     * The OUTERMOST registered composite (regions-bearing) ancestor of `leaf`
+     * that lives strictly under `regionPrefix`, or `undefined` if the region
+     * holds a simple atomic state directly. Used by {@link isCompositeDone} to
+     * delegate a region's completeness to its nested composite (recursing over
+     * every parallel branch), independent of whether any single branch leaf
+     * happens to carry the `final` flag.
+     *
+     * ancestorChain is root-to-leaf, so the FIRST matching ancestor is the
+     * region's direct composite child (e.g. `C.p.D` for leaf `C.p.D.s.s2` under
+     * region prefix `C.p.`); isCompositeDone then recurses into its regions.
+     */
+    private regionComposite;
+    /**
+     * Whether composite `compositeId` has reached its all-regions-final ("done")
+     * configuration in the CURRENT active state. Public guard surface (`@stable`)
+     * for authoring a join as `guard: () => sm.isDone('C')` instead of (or
+     * alongside) listening on the engine `done.state.<C>` event.
+     *
+     * @param compositeId - The dotted id of the composite/parallel state.
+     * @returns `true` iff every region's active atomic leaf is `final`.
+     */
+    isDone(compositeId: string, adaptee?: Adapter<PropertiesOf<TOwner>>): boolean;
+    /**
+     * SCXML completion hook (D10/D11/D12): after a new configuration is written,
+     * raise `done.state.<C>` for each composite that became all-regions-final.
+     *
+     * - Scans only composites that GAINED an active leaf (the ancestor chain of
+     *   each `|`-leaf of `newState`), so unaffected composites are not re-checked.
+     * - Emits INNERMOST-first (a deeper composite's `done.state` precedes its
+     *   parent's), matching SCXML's inner-before-outer completion ordering, via a
+     *   per-config emitted-id Set so each id is raised at most once per call.
+     * - Gates each emission on `this.events.has('done.state.'+C)` (D11 mustFix):
+     *   raising an undeclared event would hit the `Invalid event` throw
+     *   (executeQueuedTransition) as an unhandled microtask rejection. No declared
+     *   `done.state.<C>` event => no emission, no crash, no observable effect.
+     * - Uses the internal queue (`raiseEvent`) + `scheduleProcessing` so the
+     *   completion event is processed before subsequent external events.
+     */
+    private checkCompletion;
+    /**
+     * Build the registered ancestor chain for an atomic leaf, ordered root-to-leaf.
+     *
+     * Walks every dot-prefix of `leaf` and keeps only the ones that are real
+     * registered states (`this.states.has`). Region containers are never
+     * registered (only composite parents and atomic leaves are — see
+     * processStates/processRegions), so they are filtered out automatically. The
+     * result is exactly `[parent..leaf]` for a leaf inside a composite, and
+     * `[leaf]` for a flat state.
+     *
+     * Example: `ancestorChain('a.r1.c1')` -> `['a', 'a.r1.c1']` (the `a.r1`
+     * region container is excluded). Nested:
+     * `ancestorChain('a.r1.c1.r3.x')` -> `['a', 'a.r1.c1', 'a.r1.c1.r3.x']`.
+     */
+    private ancestorChain;
+    /**
+     * Compute the ordered enter/exit sets between two composite configurations
+     * (SCXML ancestor-first entry / descendant-first exit).
+     *
+     * For each `|`-separated atomic leaf in `oldComposite` and `newComposite` the
+     * union of its {@link ancestorChain} forms the old/new active ancestry. A
+     * state shared by both ancestries lands in NEITHER diff, so a surviving
+     * ancestor is never re-entered nor exited (no onEnter/onExit re-fire, no
+     * timer re-arm/leak).
+     *
+     * - `enterStates` = new ancestry MINUS old, sorted ascending by depth then
+     *   document (insertion) order -> root-to-leaf entry.
+     * - `exitStates` = old ancestry MINUS new, sorted descending by depth ->
+     *   leaf-to-root exit.
+     *
+     * Consumed by BOTH R1 (applyTransition / setInitialState / reset) and R2.
+     */
+    private computeEnterExitSets;
     private validateCompositeState;
     private processStates;
     private processRegions;

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.
@@ -119,7 +132,7 @@ export type DeepNestedStateName<S> = {
     }[keyof R & string] : never : never;
 }[keyof S & string];
 export type StatePaths<S> = SimpleStateName<S> | RegionStateName<S> | NestedStateName<S> | DeepNestedStateName<S>;
-export type ActionOrString<T extends object, R = void> = KeysOf<T, EventAction<T, R>> | EventAction<Adapter<T>, R>;
+export type ActionOrString<T extends object, R = void> = KeysOf<T, EventAction<T, R>> | EventAction<T, R>;
 export type ErrorHandlerOrString<T extends object> = KeysOf<T, ErrorHandler<T>> | ErrorHandler<T>;
 export type RegionName = string;
 export type RegionsConfig<T extends object> = Record<RegionName, StateMachineConfig<T>['states']>;
@@ -138,6 +151,15 @@ export type State<T extends object> = {
     regions?: RegionsConfig<T>;
     initial?: StateName;
     history?: 'deep' | 'shallow';
+    /**
+     * Marks this atomic state as the SCXML/UML `<final>` pseudo-substate of its
+     * region. When every region of a composite has its active atomic leaf marked
+     * `final`, that composite is "done": the engine raises the `done.state.<id>`
+     * event and {@link StateMachine.isDone} returns `true`. Only meaningful on a
+     * leaf state (a state without `regions`); set on a composite it is ignored at
+     * runtime and flagged by the config validator.
+     */
+    final?: boolean;
     invoke?: StateInvocation<T>[];
 };
 export interface StateInvocation<T extends object> {
@@ -188,7 +210,7 @@ export interface StateMachineConfig<T extends object = object> {
     initialState: keyof StateMachineConfig<T>['states'];
     events: Record<EventName, Omit<Event<T, StateMachineConfig<T>['states']>, 'name'>>;
     states: States<T>;
-    onError?: KeysOf<T, ErrorHandler<T>>;
+    onError?: ErrorHandlerOrString<T>;
 }
 export interface StatePersistenceAdapter {
     save(state?: {