@vedmalex/statemachine 1.0.0-beta.1

package/types/types.d.ts

@@ -0,0 +1,250 @@
+export type StateName = string;
+export type EventName = string;
+export type EventAction<T, R = void> = (adaptee: T, ...args: unknown[]) => R;
+export type ErrorHandler<T> = EventAction<T, void>;
+export type MethodsOf<T> = {
+    [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K];
+};
+export type PropertiesOf<T> = {
+    [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
+};
+export type KeysOf<T, R> = {
+    [K in keyof T]: T[K] extends R ? K : never;
+}[keyof T];
+export type ErrorContext = {
+    state?: StateName;
+    event?: EventName;
+    action?: string;
+    transition?: string;
+    phase?: 'guard' | 'action' | 'transition' | 'enter' | 'exit';
+};
+export declare class StateMachineError extends Error {
+    readonly context: ErrorContext;
+    constructor(message: string, context: ErrorContext, cause?: Error);
+    toString(): string;
+}
+export interface ILogger {
+    debug(message: string, context?: any): void;
+    info(message: string, context?: any): void;
+    warn(message: string, context?: any, error?: Error): void;
+    error(message: string, context?: any, error?: Error): void;
+}
+/** @unstable — timer scheduling injection contract; consumed by StateMachine. */
+export interface ITimerScheduler {
+    isActive(): boolean;
+    schedule(delay: number, callback: () => void): object;
+    cancel(token: object): void;
+}
+/** @unstable — transition observability context (additive on IMonitor). */
+export interface TransitionContext {
+    fromState: string;
+    toState: string;
+    eventName?: string;
+}
+/** @unstable — minimal aggregate observability snapshot for tests. */
+export interface MonitorMetricsSnapshot {
+    totalTransitions: number;
+    successCount: number;
+    errorCount: number;
+    averageDuration: number;
+}
+/**
+ * @unstable — observability injection contract.
+ * EXPANDED additively in TASK-004 per TD-T4-2: third param of `recordTransition`
+ * is parameter-optional; `recordEvent?` and `getMetrics?` are interface-optional.
+ * Existing 2-arg call site at state_machine.ts:1665 remains valid.
+ */
+export interface IMonitor {
+    recordTransition(duration: number, success: boolean, context?: TransitionContext): void;
+    recordError(error: Error, context?: ErrorContext): void;
+    recordEvent?(eventName: string, duration: number): void;
+    getMetrics?(): MonitorMetricsSnapshot;
+}
+/** @unstable — error-handler injection contract; surfaces methods consumed by host integrations. */
+export interface IErrorHandler {
+    isEnabled(): boolean;
+    enable(): void;
+    disable(): void;
+    addRecoveryStrategy(strategy: import('./error_handling').ErrorRecoveryStrategy): void;
+    removeRecoveryStrategy(strategyName: string): void;
+    getAnalytics(): import('./error_handling').ErrorAnalytics;
+}
+export interface StateMachineOptions {
+    logger?: ILogger;
+    monitor?: IMonitor;
+    scheduler?: ITimerScheduler;
+    errorHandler?: IErrorHandler;
+    /**
+     * Maximum time (ms) to wait for async entry/exit actions.
+     * If exceeded, the transition aborts with an error.
+     */
+    transitionTimeout?: number;
+    /**
+     * State to transition to if an error occurs during a transition (Zombie State Prevention).
+     */
+    errorState?: string;
+    /**
+     * If true, aborts the transition if onExit fails, keeping the state machine in the source state.
+     */
+    abortOnExitError?: boolean;
+    /**
+     * Maximum depth of the event queue before rejecting new events.
+     * Default: 1000
+     */
+    maxQueueDepth?: number;
+}
+type StringKey = string & {};
+export type SimpleStateName<S> = StringKey & keyof S;
+export type RegionStateName<S> = {
+    [K in keyof S & string]: S[K] extends {
+        regions?: infer R;
+    } ? R extends Record<string, any> ? `${K}.${StringKey & keyof R}` : never : never;
+}[keyof S & string];
+export type NestedStateName<S> = {
+    [K in keyof S & string]: S[K] extends {
+        regions?: infer R;
+    } ? R extends Record<string, any> ? {
+        [RegKey in keyof R & string]: R[RegKey] extends Record<string, any> ? `${K}.${RegKey}.${StringKey & keyof R[RegKey]}` : never;
+    }[keyof R & string] : never : never;
+}[keyof S & string];
+export type DeepNestedStateName<S> = {
+    [K in keyof S & string]: S[K] extends {
+        regions?: infer R;
+    } ? R extends Record<string, any> ? {
+        [RegKey in keyof R & string]: R[RegKey] extends Record<string, any> ? {
+            [ChildKey in keyof R[RegKey] & string]: R[RegKey][ChildKey] extends {
+                regions?: infer CR;
+            } ? CR extends Record<string, any> ? `${K}.${RegKey}.${ChildKey}.${StringKey & keyof CR}` : never : never;
+        }[keyof R[RegKey] & string] : never;
+    }[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 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']>;
+export type State<T extends object> = {
+    name: StateName;
+    display?: string;
+    comment?: string;
+    iconCls?: string;
+    onBeforeEnter?: ActionOrString<T>;
+    onEnter?: ActionOrString<T>;
+    onAfterEnter?: ActionOrString<T>;
+    onBeforeExit?: ActionOrString<T>;
+    onExit?: ActionOrString<T>;
+    onAfterExit?: ActionOrString<T>;
+    onError?: ErrorHandlerOrString<T>;
+    regions?: RegionsConfig<T>;
+    initial?: StateName;
+    history?: 'deep' | 'shallow';
+    invoke?: StateInvocation<T>[];
+};
+export interface StateInvocation<T extends object> {
+    /** Время задержки в миллисекундах */
+    delay: number;
+    /** Событие, которое будет вызвано после задержки */
+    event: EventName;
+    /** Условие запуска поручения */
+    cond?: (adaptee: T) => boolean;
+    /** Действие, выполняемое перед событием */
+    action?: ActionOrString<T>;
+}
+export type Transition<T extends object, S extends States<T>> = {
+    from: StatePaths<S>;
+    to: StatePaths<S>;
+    priority?: number;
+    guard?: ActionOrString<T, boolean>;
+    /**
+     * Action executed during the transition (after leaving `from`, before entering `to`).
+     * Receives the current owner context. Use for side-effects scoped to this edge.
+     */
+    onTransition?: ActionOrString<T>;
+    onError?: ErrorHandlerOrString<T>;
+};
+export type Event<T extends object, S extends States<T>> = {
+    name: EventName;
+    display?: string;
+    comment?: string;
+    transitions: Array<Transition<T, S>>;
+    onBefore?: ActionOrString<T>;
+    onAfter?: ActionOrString<T>;
+    onSuccess?: ActionOrString<T>;
+    onError?: ErrorHandlerOrString<T>;
+};
+export type States<T extends object> = Record<StateName, Omit<State<T>, 'name'>>;
+export type Events<T extends object, S extends States<T>> = Record<EventName, Omit<Event<T, S>, 'name'>>;
+export interface Adapter<T extends object> {
+    get adaptee(): T;
+    set(property: keyof T, value: T[keyof T]): void;
+    get(property: keyof T): T[keyof T];
+}
+export type ExtractAdaptee<T> = T extends MemoryAdapter<infer R> ? R : T;
+export declare function isAdapter<T extends object>(inp: unknown): inp is Adapter<T>;
+export interface StateMachineConfig<T extends object = object> {
+    name: string;
+    description?: string;
+    stateAttribute: KeysOf<PropertiesOf<T>, string>;
+    initialState: keyof StateMachineConfig<T>['states'];
+    events: Record<EventName, Omit<Event<T, StateMachineConfig<T>['states']>, 'name'>>;
+    states: States<T>;
+    onError?: KeysOf<T, ErrorHandler<T>>;
+}
+export interface StatePersistenceAdapter {
+    save(state?: {
+        currentState: string;
+        history: any;
+        stateEntryTimes: any;
+    }): Promise<void>;
+    restore(): Promise<{
+        currentState: string;
+        history: any;
+        stateEntryTimes: any;
+    }>;
+}
+export declare class MemoryAdapter<T extends object> implements Adapter<T>, StatePersistenceAdapter {
+    adaptee: T;
+    private _savedState;
+    constructor(data: T);
+    set(property: keyof T, value: T[keyof T]): void;
+    get(property: keyof T): T[keyof T];
+    save(state?: {
+        currentState: string;
+        history: unknown;
+        stateEntryTimes: unknown;
+    }): Promise<void>;
+    restore(): Promise<{
+        currentState: string;
+        history: unknown;
+        stateEntryTimes: unknown;
+    }>;
+}
+export declare class LocalStorageAdapter<T extends object> implements Adapter<T>, StatePersistenceAdapter {
+    adaptee: T;
+    private key;
+    constructor(data: T, storageKey?: string);
+    set(property: keyof T, value: T[keyof T]): void;
+    get(property: keyof T): T[keyof T];
+    save(state?: any): Promise<void>;
+    restore(): Promise<any>;
+}
+export declare class SessionStorageAdapter<T extends object> implements Adapter<T>, StatePersistenceAdapter {
+    adaptee: T;
+    private key;
+    constructor(data: T, storageKey?: string);
+    set(property: keyof T, value: T[keyof T]): void;
+    get(property: keyof T): T[keyof T];
+    save(state?: any): Promise<void>;
+    restore(): Promise<any>;
+}
+export declare class ServerAdapter<T extends object> implements Adapter<T>, StatePersistenceAdapter {
+    adaptee: T;
+    static data: Record<string, unknown>;
+    private endpoint;
+    constructor(data: T, endpoint?: string);
+    set(property: keyof T, value: T[keyof T]): void;
+    get(property: keyof T): T[keyof T];
+    save(state?: any): Promise<void>;
+    restore(): Promise<any>;
+}
+export {};