@camcima/finita 2.1.0 → 3.0.0

package/dist/index.d.ts

@@ -65,110 +65,205 @@ interface TransitionInterface<TSubject = unknown> extends Weighted {
 
 interface StateInterface extends Named, Metadata {
     getTransitions(): Iterable<TransitionInterface>;
-    addTransition(transition: TransitionInterface): void;
     getEventNames(): string[];
     hasEvent(name: string): boolean;
     getEvent(name: string): EventInterface;
     getMetadataValue(key: string): unknown;
-    setMetadataValue(key: string, value: unknown): void;
     hasMetadataValue(key: string): boolean;
-    deleteMetadataValue(key: string): void;
+}
+
+interface StateCollectionInterface {
+    getStates(): Iterable<StateInterface>;
+    getState(name: string): StateInterface;
+    hasState(name: string): boolean;
+}
+
+interface ProcessInterface extends Named, StateCollectionInterface {
+    getInitialState(): StateInterface;
+}
+
+/**
+ * Symbol-based construction guard for State / Transition / Process.
+ *
+ * These classes' constructors require this symbol as the first argument.
+ * Only ProcessBuilder imports it, ensuring only the builder can instantiate
+ * the graph. User code receives an opaque type error if it tries to call
+ * `new State(...)` directly.
+ */
+declare const INTERNAL_CONSTRUCTION_KEY: unique symbol;
+type InternalConstructionKey = typeof INTERNAL_CONSTRUCTION_KEY;
+
+declare class Process implements ProcessInterface {
+    private readonly name;
+    private readonly initialState;
+    private readonly states;
+    constructor(key: InternalConstructionKey, name: string, initialState: StateInterface, states: Iterable<StateInterface>);
+    getName(): string;
+    getInitialState(): StateInterface;
+    getStates(): Iterable<StateInterface>;
+    getState(name: string): StateInterface;
+    hasState(name: string): boolean;
 }
 
 declare class State implements StateInterface {
     private readonly name;
-    private readonly transitions;
+    private _transitions;
     private readonly events;
     private readonly metadata;
-    constructor(name: string);
+    constructor(key: InternalConstructionKey, name: string, eventNames: Iterable<string>, metadata: ReadonlyMap<string, unknown>);
+    /**
+     * Internal: populate transitions after State construction.
+     * May only be called once and only with the construction key.
+     * Used by ProcessBuilder to break the cycle: State must exist before
+     * Transitions can target it, but State needs its transitions to be useful.
+     */
+    _initTransitions(key: InternalConstructionKey, transitions: Iterable<TransitionInterface>): void;
     getName(): string;
     getTransitions(): Iterable<TransitionInterface>;
-    addTransition(transition: TransitionInterface): void;
     getEventNames(): string[];
     hasEvent(name: string): boolean;
     getEvent(name: string): EventInterface;
     getMetadata(): Record<string, unknown>;
     getMetadataValue(key: string): unknown;
-    setMetadataValue(key: string, value: unknown): void;
     hasMetadataValue(key: string): boolean;
-    deleteMetadataValue(key: string): void;
 }
 
 declare class Transition<TSubject = unknown> implements TransitionInterface<TSubject> {
     private readonly targetState;
     private readonly eventName;
     private readonly condition;
-    private weight;
-    constructor(targetState: StateInterface, eventName?: string | null, condition?: ConditionInterface<TSubject> | null);
+    private readonly weight;
+    constructor(key: InternalConstructionKey, targetState: StateInterface, eventName: string | null, condition: ConditionInterface<TSubject> | null, weight: number);
     getTargetState(): StateInterface;
     getEventName(): string | null;
     getConditionName(): string | null;
     getCondition(): ConditionInterface<TSubject> | null;
     isActive(subject: TSubject, context: Map<string, unknown>, event?: EventInterface): Promise<boolean>;
     getWeight(): number;
-    setWeight(weight: number): void;
 }
 
-interface StateCollectionInterface {
-    getStates(): Iterable<StateInterface>;
-    getState(name: string): StateInterface;
-    hasState(name: string): boolean;
+interface AddStateOptions {
+    initial?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface AddTransitionOptions<TSubject = unknown> {
+    event?: string;
+    condition?: ConditionInterface<TSubject>;
+    weight?: number;
+}
+interface BuildOptions {
+    /**
+     * When true, orphan/unreachable states cause GraphValidationError.
+     * When false (default), orphan states are silently allowed.
+     */
+    strictOrphans?: boolean;
+}
+declare class ProcessBuilder<TSubject = unknown> {
+    private readonly processName;
+    private readonly stateSpecs;
+    private readonly transitionSpecs;
+    private built;
+    constructor(processName: string);
+    addState(name: string, options?: AddStateOptions): this;
+    addTransition(fromState: string, toState: string, options?: AddTransitionOptions<TSubject>): this;
+    build(options?: BuildOptions): Process;
+    private validateInitialState;
+    private findInitialStateName;
+    private validateTransitionEndpoints;
+    private validateNoConflictingDuplicates;
+    private collectEventNamesByState;
+    /**
+     * Two-phase construction:
+     * Phase 1 — create all final State instances with no transitions.
+     * Phase 2 — build Transitions targeting the Phase-1 States, then attach
+     *            them via State._initTransitions.
+     *
+     * Because every Transition is created after every State exists, target
+     * identity holds by construction for any graph topology (acyclic, cyclic,
+     * self-loop).
+     */
+    private buildAllStates;
+    private validateOrphans;
 }
 
-declare class StateCollectionMerger {
-    private readonly targetCollection;
-    private stateNamePrefix;
-    constructor(targetCollection: StateCollection);
-    getStateNamePrefix(): string;
-    setStateNamePrefix(prefix: string): void;
-    getTargetCollection(): StateCollection;
-    protected createState(name: string): StateInterface;
-    protected findOrCreateState(name: string): StateInterface;
-    protected createCondition(sourceTransition: TransitionInterface): ConditionInterface | null;
-    protected createTransition(sourceTransition: TransitionInterface): Transition;
-    protected mergeMetadata(source: StateInterface, target: StateInterface): void;
-    protected mergeEvent(source: StateInterface, target: StateInterface, eventName: string): void;
-    protected mergeState(sourceState: StateInterface): void;
-    merge(source: StateCollectionInterface | StateInterface): void;
-}
-
-declare class StateCollection implements StateCollectionInterface {
-    private readonly states;
-    private stateCollectionMerger;
-    getState(name: string): StateInterface;
-    getStates(): Iterable<StateInterface>;
-    hasState(name: string): boolean;
-    addState(state: StateInterface): void;
-    getStateCollectionMerger(): StateCollectionMerger;
-    merge(source: StateCollectionInterface): void;
+/**
+ * Immutable snapshot passed to AfterTransitionObserver.notify().
+ *
+ * Captures the post-commit transition: state has already moved from
+ * fromState to toState. Reading any field is safe and stable for the
+ * duration of the observer call (and beyond — the frame is frozen).
+ */
+interface TransitionFrame<TSubject = unknown> {
+    readonly fromState: StateInterface;
+    readonly toState: StateInterface;
+    readonly transition: TransitionInterface<TSubject>;
+    readonly event: EventInterface | null;
+    readonly condition: ConditionInterface<TSubject> | null;
+    readonly context: ReadonlyMap<string, unknown>;
+    readonly timestamp: number;
+    readonly machineName: string | null;
+}
+/**
+ * Immutable snapshot passed to BeforeTransitionObserver.notify().
+ *
+ * Same shape as TransitionFrame but represents a *proposed* transition
+ * — fromState is still the current state at notification time. Throwing
+ * from a before-observer aborts the transition; otherwise commit proceeds.
+ */
+interface ProposedTransitionFrame<TSubject = unknown> extends TransitionFrame<TSubject> {
 }
 
-interface ProcessInterface extends Named, StateCollectionInterface {
-    getInitialState(): StateInterface;
+/**
+ * Runs before a transition commits. Throwing aborts the transition —
+ * state is not mutated and the original caller's promise rejects with
+ * the thrown error.
+ *
+ * Implementations must be pure relative to the FSM: they MUST NOT call
+ * triggerEvent / checkTransitions on the same Statemachine. There is no
+ * enqueue handle in the before phase by design — vetoes and validations
+ * complete synchronously per observer; chained behaviour belongs in
+ * AfterTransitionObserver.
+ */
+interface BeforeTransitionObserver<TSubject = unknown> {
+    notify(frame: ProposedTransitionFrame<TSubject>): MaybePromise<void>;
 }
 
-declare class Process implements ProcessInterface {
-    private readonly name;
-    private readonly initialState;
-    private readonly states;
-    constructor(name: string, initialState: StateInterface);
-    private registerState;
-    getName(): string;
-    getInitialState(): StateInterface;
-    getStates(): Iterable<StateInterface>;
-    getState(name: string): StateInterface;
-    hasState(name: string): boolean;
+/**
+ * Handle passed to AfterTransitionObserver.notify so observers can
+ * append events to the FSM's queue without reentering it.
+ *
+ * enqueue() never runs the event inline — it returns immediately. The
+ * event runs as its own top-level operation after the current operation
+ * (and any auto-follow-on transitions) completes.
+ */
+interface EnqueueContext {
+    enqueue(event: string, context?: Map<string, unknown>): void;
+}
+/**
+ * Runs after a transition has committed. State has already moved.
+ *
+ * Errors thrown by an after-observer do NOT roll back the transition.
+ * All after-observers are still invoked (no early bail). After all have
+ * run, the caller's promise rejects: with the thrown error if exactly
+ * one observer threw, or with a standard AggregateError if multiple did.
+ */
+interface AfterTransitionObserver<TSubject = unknown> {
+    notify(frame: TransitionFrame<TSubject>, ctx: EnqueueContext): MaybePromise<void>;
 }
 
-interface StatemachineInterface<TSubject = unknown> extends ObservableSubject {
+interface StatemachineInterface<TSubject = unknown> {
     getCurrentState(): StateInterface;
+    getLastState(): StateInterface | null;
     getSubject(): TSubject;
     getProcess(): ProcessInterface;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
-    getSelectedTransition(): TransitionInterface<TSubject> | null;
-    getLastState(): StateInterface | null;
-    getCurrentContext(): Map<string, unknown> | null;
+    attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
+    detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
+    getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
+    attachAfter(observer: AfterTransitionObserver<TSubject>): void;
+    detachAfter(observer: AfterTransitionObserver<TSubject>): void;
+    getAfterObservers(): Iterable<AfterTransitionObserver<TSubject>>;
     acquireLock(): Promise<boolean>;
     releaseLock(): Promise<void>;
     isLockAcquired(): boolean;
@@ -187,59 +282,57 @@ interface TransitionSelectorInterface<TSubject = unknown> {
     selectTransition(transitions: Iterable<TransitionInterface<TSubject>>): TransitionInterface<TSubject> | null;
 }
 
-interface CallbackInterface {
-    invoke(): MaybePromise<void>;
-}
-interface DispatcherInterface extends CallbackInterface {
-    dispatch(event: EventInterface, args?: unknown[], onReadyCallback?: CallbackInterface): void;
-    isReady(): boolean;
-    invoke(): Promise<void>;
+interface StatemachineOptions<TSubject = unknown> {
+    /** Override the process's initial state. Defaults to process.getInitialState(). */
+    initialStateName?: string;
+    /** Defaults to OneOrNoneActiveTransition. */
+    transitionSelector?: TransitionSelectorInterface<TSubject>;
+    /** Defaults to NullMutex (no cross-process serialization). */
+    mutex?: MutexInterface;
+    /** When true, the engine releases the mutex at the end of each top-level operation. Defaults to true. */
+    autoreleaseLock?: boolean;
 }
 
 declare class Statemachine<TSubject = unknown> implements StatemachineInterface<TSubject> {
     private readonly subject;
-    private currentState;
-    private lastState;
-    private readonly transitionSelector;
-    private selectedTransition;
     private readonly process;
+    private readonly transitionSelector;
     private readonly mutex;
+    private currentState;
+    private lastState;
     private autoreleaseLock;
-    private dispatcher;
-    private currentEvent;
-    private currentContext;
-    private readonly observers;
-    constructor(subject: TSubject, process: ProcessInterface, stateName?: string | null, transitionSelector?: TransitionSelectorInterface<TSubject> | null, mutex?: MutexInterface | null);
-    getProcess(): ProcessInterface;
+    private readonly queue;
+    private running;
+    private readonly beforeObservers;
+    private readonly afterObservers;
+    constructor(subject: TSubject, process: ProcessInterface, options?: StatemachineOptions<TSubject>);
     getCurrentState(): StateInterface;
     getLastState(): StateInterface | null;
     getSubject(): TSubject;
-    getSelectedTransition(): TransitionInterface<TSubject> | null;
-    getCurrentContext(): Map<string, unknown> | null;
-    private doCheckTransitions;
-    private onDispatcherReady;
-    dispatchEvent(dispatcher: DispatcherInterface, name: string, context?: Map<string, unknown>): Promise<void>;
-    triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
-    checkTransitions(context?: Map<string, unknown>): Promise<void>;
-    private acquireLockOrThrowException;
-    isAutoreleaseLock(): boolean;
-    setAutoreleaseLock(autorelease: boolean): void;
+    getProcess(): ProcessInterface;
+    attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
+    detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
+    getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
+    attachAfter(observer: AfterTransitionObserver<TSubject>): void;
+    detachAfter(observer: AfterTransitionObserver<TSubject>): void;
+    getAfterObservers(): Iterable<AfterTransitionObserver<TSubject>>;
     acquireLock(): Promise<boolean>;
     releaseLock(): Promise<void>;
     isLockAcquired(): boolean;
-    attach(observer: Observer): void;
-    detach(observer: Observer): void;
-    notify(): Promise<void>;
-    getObservers(): Iterable<Observer>;
-}
-
-declare class Dispatcher implements DispatcherInterface {
-    private commands;
-    private onReadyCallbacks;
-    private ready;
-    dispatch(event: EventInterface, args?: unknown[], onReadyCallback?: CallbackInterface): void;
-    invoke(): Promise<void>;
-    isReady(): boolean;
+    isAutoreleaseLock(): boolean;
+    setAutoreleaseLock(autorelease: boolean): void;
+    triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
+    checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    private runIfIdle;
+    private runOperation;
+    private resolveEvent;
+    /**
+     * Drive transitions starting from the current state, following automatic
+     * transitions until quiescent. The first iteration may use the supplied
+     * event; subsequent iterations are automatic.
+     */
+    private processOperation;
+    private readonlyContext;
 }
 
 interface MutexFactoryInterface<TSubject = unknown> {
@@ -261,12 +354,13 @@ interface StateNameDetectorInterface<TSubject = unknown> {
 }
 
 interface FactoryInterface<TSubject = unknown> {
-    createStatemachine(subject: TSubject): Promise<StatemachineInterface<TSubject>>;
     setMutexFactory(factory: MutexFactoryInterface<TSubject> | null): void;
     setTransitionSelector(selector: TransitionSelectorInterface<TSubject>): void;
-    attachStatemachineObserver(observer: Observer): void;
-    detachStatemachineObserver(observer: Observer): void;
-    getStatemachineObservers(): Iterable<Observer>;
+    attachBeforeObserver(observer: BeforeTransitionObserver<TSubject>): void;
+    detachBeforeObserver(observer: BeforeTransitionObserver<TSubject>): void;
+    attachAfterObserver(observer: AfterTransitionObserver<TSubject>): void;
+    detachAfterObserver(observer: AfterTransitionObserver<TSubject>): void;
+    createStatemachine(subject: TSubject): Promise<StatemachineInterface<TSubject>>;
 }
 
 interface StatefulInterface {
@@ -278,6 +372,14 @@ interface LastStateHasChangedDateInterface {
     getLastStateHasChangedDate(): Date;
 }
 
+interface CallbackInterface {
+    invoke(): MaybePromise<void>;
+}
+interface DispatcherInterface extends CallbackInterface {
+    dispatch(event: EventInterface, args?: unknown[]): void;
+    invoke(): Promise<void>;
+}
+
 interface LoggerInterface {
     log(level: string, message: string, context?: Record<string, unknown>): void;
 }
@@ -337,28 +439,46 @@ declare class Not<TSubject = unknown> implements ConditionInterface<TSubject> {
     checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
 }
 
+/**
+ * Legacy Observer for Event observers (commands attached to specific events).
+ *
+ * In v3 this is no longer used as a Statemachine observer. To run a
+ * callback after every transition, implement AfterTransitionObserver
+ * directly or compose a small wrapper.
+ */
 declare class CallbackObserver implements Observer {
     private readonly callback;
     constructor(callback: (...args: unknown[]) => MaybePromise<void>);
     update(subject: ObservableSubject): MaybePromise<void>;
 }
 
-declare class StatefulStatusChanger implements Observer {
-    update(subject: ObservableSubject): void;
+declare class StatefulStatusChanger<TSubject extends StatefulInterface> implements AfterTransitionObserver<TSubject> {
+    private readonly subject;
+    constructor(subject: TSubject);
+    notify(frame: TransitionFrame<TSubject>): void;
 }
 
-declare class OnEnterObserver implements Observer {
+/**
+ * After-transition observer that fires an event named DEFAULT_EVENT_NAME
+ * (or a custom name) when entering any state that has that event declared.
+ *
+ * The chained event is *enqueued*, not invoked inline: it runs as its own
+ * top-level operation after the current operation completes. Other
+ * after-observers registered after OnEnterObserver still see the original
+ * frame, not the chained one.
+ */
+declare class OnEnterObserver<TSubject = unknown> implements AfterTransitionObserver<TSubject> {
     static readonly DEFAULT_EVENT_NAME = "onEnter";
     private readonly eventName;
     constructor(eventName?: string);
-    update(subject: ObservableSubject): Promise<void>;
+    notify(frame: TransitionFrame<TSubject>, ctx: EnqueueContext): void;
 }
 
-declare class TransitionLogger implements Observer {
+declare class TransitionLogger<TSubject = unknown> implements AfterTransitionObserver<TSubject> {
     private readonly logger;
     private readonly loggerLevel;
     constructor(logger: LoggerInterface, loggerLevel?: string);
-    update(subject: ObservableSubject): void;
+    notify(frame: TransitionFrame<TSubject>): void;
 }
 
 declare class ActiveTransitionFilter {
@@ -432,15 +552,17 @@ declare class MutexFactory<TSubject = unknown> implements MutexFactoryInterface<
 declare class Factory<TSubject = unknown> implements FactoryInterface<TSubject> {
     private readonly processDetector;
     private readonly stateNameDetector;
-    private readonly statemachineObservers;
+    private readonly beforeObservers;
+    private readonly afterObservers;
     private transitionSelector;
     private mutexFactory;
     constructor(processDetector: ProcessDetectorInterface<TSubject>, stateNameDetector?: StateNameDetectorInterface<TSubject> | null);
     setMutexFactory(factory: MutexFactoryInterface<TSubject> | null): void;
     setTransitionSelector(selector: TransitionSelectorInterface<TSubject>): void;
-    attachStatemachineObserver(observer: Observer): void;
-    detachStatemachineObserver(observer: Observer): void;
-    getStatemachineObservers(): Iterable<Observer>;
+    attachBeforeObserver(observer: BeforeTransitionObserver<TSubject>): void;
+    detachBeforeObserver(observer: BeforeTransitionObserver<TSubject>): void;
+    attachAfterObserver(observer: AfterTransitionObserver<TSubject>): void;
+    detachAfterObserver(observer: AfterTransitionObserver<TSubject>): void;
     createStatemachine(subject: TSubject): Promise<StatemachineInterface<TSubject>>;
 }
 
@@ -462,17 +584,6 @@ declare class StatefulStateNameDetector implements StateNameDetectorInterface<St
     detectCurrentStateName(subject: StatefulInterface): string | null;
 }
 
-declare class SetupHelper {
-    protected readonly stateCollection: StateCollection;
-    constructor(stateCollection: StateCollection);
-    findOrCreateState(name: string): StateInterface;
-    protected findTransition(sourceState: StateInterface, targetState: StateInterface, eventName?: string | null, condition?: ConditionInterface | null): TransitionInterface | null;
-    findOrCreateTransition(sourceStateName: string, targetStateName: string, eventName?: string | null, condition?: ConditionInterface | null): TransitionInterface;
-    findOrCreateEvent(sourceStateName: string, eventName: string): EventInterface;
-    addCommand(sourceStateName: string, eventName: string, command: Observer): void;
-    addCommandAndSelfTransition(sourceStateName: string, eventName: string, command: Observer): void;
-}
-
 interface GraphNode {
     id: string;
     label: string;
@@ -497,6 +608,7 @@ interface MermaidOptions {
 declare class GraphBuilder {
     private readonly nodes;
     private readonly edges;
+    private readonly statesWithEdges;
     private getOrCreateNode;
     protected getTransitionLabel(state: StateInterface, transition: TransitionInterface): string;
     addState(state: StateInterface): void;
@@ -507,19 +619,94 @@ declare class GraphBuilder {
     toMermaid(options?: MermaidOptions): string;
 }
 
-declare class WrongEventForStateError extends Error {
+declare abstract class FinitaError extends Error {
+    abstract readonly code: string;
+    constructor(message?: string);
+}
+
+declare class WrongEventForStateError extends FinitaError {
+    readonly code = "wrongEventForState";
     readonly stateName: string;
     readonly eventName: string;
     constructor(stateName: string, eventName: string);
 }
 
-declare class LockCanNotBeAcquiredError extends Error {
+declare class LockCanNotBeAcquiredError extends FinitaError {
+    readonly code = "lockCanNotBeAcquired";
     constructor(message?: string);
 }
 
-declare class DuplicateStateError extends Error {
+declare class DuplicateStateError extends FinitaError {
+    readonly code = "duplicateState";
     readonly stateName: string;
     constructor(stateName: string);
 }
 
-export { AbstractNamedProcessDetector, ActiveTransitionFilter, AndComposite, CallbackCondition, type CallbackInterface, CallbackObserver, type ConditionCallbackFn, type ConditionInterface, Contradiction, Dispatcher, type DispatcherInterface, type DotOptions, DuplicateStateError, Event, type EventInterface, Factory, type FactoryInterface, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, type Graph, GraphBuilder, type GraphEdge, type GraphNode, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, type LoggerInterface, type MaybePromise, type MermaidOptions, type Metadata, MutexFactory, type MutexFactoryInterface, type MutexInterface, type Named, Not, NullMutex, type ObservableSubject, type Observer, OnEnterObserver, OneOrNoneActiveTransition, OrComposite, Process, type ProcessDetectorInterface, type ProcessInterface, ScoreTransition, SetupHelper, SingleProcessDetector, State, StateCollection, type StateCollectionInterface, StateCollectionMerger, type StateInterface, type StateNameDetectorInterface, type StatefulInterface, StatefulStateNameDetector, StatefulStatusChanger, Statemachine, type StatemachineInterface, type StringConverter, Tautology, Timeout, Transition, type TransitionInterface, TransitionLogger, type TransitionSelectorInterface, WeightTransition, type Weighted, WrongEventForStateError };
+declare class ProcessFinalizedError extends FinitaError {
+    readonly code = "processFinalized";
+    readonly processName: string;
+    constructor(processName: string);
+}
+
+type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidEventName" | "invalidConditionName" | "orphanState";
+declare class GraphValidationError extends FinitaError {
+    readonly code: GraphValidationCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: GraphValidationCode, message: string, details?: Record<string, unknown>);
+}
+
+interface DuplicateTransitionConflict {
+    fromState: string;
+    toState: string;
+    eventName: string | null;
+    existingConditionName: string | null;
+    newConditionName: string | null;
+}
+declare class DuplicateTransitionError extends FinitaError {
+    readonly code = "duplicateTransition";
+    readonly conflict: Readonly<DuplicateTransitionConflict>;
+    constructor(conflict: DuplicateTransitionConflict);
+}
+
+declare class StateNotFoundError extends FinitaError {
+    readonly code = "stateNotFound";
+    readonly stateName: string;
+    readonly availableStates: readonly string[];
+    constructor(stateName: string, availableStates: Iterable<string>);
+}
+
+declare class StateEventNotFoundError extends FinitaError {
+    readonly code = "stateEventNotFound";
+    readonly stateName: string;
+    readonly eventName: string;
+    constructor(stateName: string, eventName: string);
+}
+
+declare class ProcessNotFoundError extends FinitaError {
+    readonly code = "processNotFound";
+    readonly processName: string;
+    readonly availableProcesses: readonly string[];
+    constructor(processName: string, availableProcesses: Iterable<string>);
+}
+
+declare class InvalidSubjectError extends FinitaError {
+    readonly code = "invalidSubject";
+    readonly expectedInterface: string;
+    readonly missingMembers: readonly string[];
+    constructor(expectedInterface: string, missingMembers: Iterable<string>);
+}
+
+declare class AmbiguousTransitionError extends FinitaError {
+    readonly code = "ambiguousTransition";
+    readonly activeCount: number;
+    constructor(activeCount: number);
+}
+
+declare class AutomaticTransitionCycleError extends FinitaError {
+    readonly code = "automaticTransitionCycle";
+    readonly targetStateName: string;
+    readonly visitedStateNames: readonly string[];
+    constructor(targetStateName: string, visitedStateNames: Iterable<string>);
+}
+
+export { AbstractNamedProcessDetector, ActiveTransitionFilter, type AddStateOptions, type AddTransitionOptions, type AfterTransitionObserver, AmbiguousTransitionError, AndComposite, AutomaticTransitionCycleError, type BeforeTransitionObserver, type BuildOptions, CallbackCondition, type CallbackInterface, CallbackObserver, type ConditionCallbackFn, type ConditionInterface, Contradiction, type DispatcherInterface, type DotOptions, DuplicateStateError, type DuplicateTransitionConflict, DuplicateTransitionError, type EnqueueContext, Event, type EventInterface, Factory, type FactoryInterface, FilterStateByEvent, FilterStateByFinalState, FilterStateByTransition, FilterTransitionByEvent, FinitaError, type Graph, GraphBuilder, type GraphEdge, type GraphNode, type GraphValidationCode, GraphValidationError, InvalidSubjectError, type LastStateHasChangedDateInterface, type LockAdapterInterface, LockAdapterMutex, LockCanNotBeAcquiredError, type LoggerInterface, type MaybePromise, type MermaidOptions, type Metadata, MutexFactory, type MutexFactoryInterface, type MutexInterface, type Named, Not, NullMutex, type ObservableSubject, type Observer, OnEnterObserver, OneOrNoneActiveTransition, OrComposite, Process, ProcessBuilder, type ProcessDetectorInterface, ProcessFinalizedError, type ProcessInterface, ProcessNotFoundError, type ProposedTransitionFrame, ScoreTransition, SingleProcessDetector, State, type StateCollectionInterface, StateEventNotFoundError, type StateInterface, type StateNameDetectorInterface, StateNotFoundError, type StatefulInterface, StatefulStateNameDetector, StatefulStatusChanger, Statemachine, type StatemachineInterface, type StatemachineOptions, type StringConverter, Tautology, Timeout, Transition, type TransitionFrame, type TransitionInterface, TransitionLogger, type TransitionSelectorInterface, WeightTransition, type Weighted, WrongEventForStateError };