@camcima/finita 3.0.1 → 4.1.0

package/dist/index.d.ts

@@ -9,16 +9,26 @@ interface Metadata {
 }
 
 interface Observer {
-    update(subject: ObservableSubject): MaybePromise<void>;
+    /**
+     * @param args The arguments the notification was invoked with — for
+     * Statemachine events, [subject, context]. Passed per-call so shared
+     * Event instances carry no per-invocation state.
+     */
+    update(subject: ObservableSubject, args?: readonly unknown[]): MaybePromise<void>;
 }
 interface ObservableSubject {
     attach(observer: Observer): void;
     detach(observer: Observer): void;
-    notify(): Promise<void>;
+    notify(args?: readonly unknown[]): Promise<void>;
     getObservers(): Iterable<Observer>;
 }
 
 interface EventInterface extends Named, Metadata, ObservableSubject {
+    /**
+     * @deprecated Always returns []. Invoke args are now passed directly to
+     * Observer.update — reading them from the event was racy when one
+     * Process served multiple Statemachines.
+     */
     getInvokeArgs(): unknown[];
     invoke(...args: unknown[]): Promise<void>;
     getMetadataValue(key: string): unknown;
@@ -31,14 +41,18 @@ declare class Event implements EventInterface {
     private readonly name;
     private readonly observers;
     private readonly metadata;
-    private invokeArgs;
     constructor(name: string);
     getName(): string;
+    /**
+     * @deprecated Always returns []. Invoke args are now passed directly to
+     * Observer.update — reading them from the event was racy when one
+     * Process served multiple Statemachines.
+     */
     getInvokeArgs(): unknown[];
     invoke(...args: unknown[]): Promise<void>;
     attach(observer: Observer): void;
     detach(observer: Observer): void;
-    notify(): Promise<void>;
+    notify(args?: readonly unknown[]): Promise<void>;
     getObservers(): Iterable<Observer>;
     getMetadata(): Record<string, unknown>;
     getMetadataValue(key: string): unknown;
@@ -167,9 +181,14 @@ declare class ProcessBuilder<TSubject = unknown> {
     addState(name: string, options?: AddStateOptions): this;
     addTransition(fromState: string, toState: string, options?: AddTransitionOptions<TSubject>): this;
     build(options?: BuildOptions): Process;
+    /** One name rule for every named entity: non-empty, no leading/trailing whitespace. */
+    private validateName;
     private validateInitialState;
     private findInitialStateName;
     private validateTransitionEndpoints;
+    /** Transition identity: (fromState, eventName, toState). Used by both the
+     *  conflict check and the build-time dedup — keep them in lockstep. */
+    private static transitionKey;
     private validateNoConflictingDuplicates;
     private collectEventNamesByState;
     /**
@@ -187,13 +206,18 @@ declare class ProcessBuilder<TSubject = unknown> {
 }
 
 /**
- * Immutable snapshot passed to AfterTransitionObserver.notify().
+ * Immutable snapshot passed to transition observers.
  *
- * 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).
+ * For AfterTransitionObserver.notify() the transition has committed:
+ * state has already moved from fromState to toState. For
+ * BeforeTransitionObserver.notify() the same shape represents the
+ * *proposed* transition — fromState is still the current state, and
+ * throwing aborts the commit. Reading any field is safe and stable for
+ * the duration of the observer call (and beyond — the frame is frozen).
  */
 interface TransitionFrame<TSubject = unknown> {
+    /** The subject this machine drives — identifies whose transition this is. */
+    readonly subject: TSubject;
     readonly fromState: StateInterface;
     readonly toState: StateInterface;
     readonly transition: TransitionInterface<TSubject>;
@@ -204,14 +228,10 @@ interface TransitionFrame<TSubject = unknown> {
     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.
+ * The frame as seen by BeforeTransitionObserver — same shape; the
+ * distinct name documents the pre-commit timing.
  */
-interface ProposedTransitionFrame<TSubject = unknown> extends TransitionFrame<TSubject> {
-}
+type ProposedTransitionFrame<TSubject = unknown> = TransitionFrame<TSubject>;
 
 /**
  * Runs before a transition commits. Throwing aborts the transition —
@@ -219,7 +239,9 @@ interface ProposedTransitionFrame<TSubject = unknown> extends TransitionFrame<TS
  * the thrown error.
  *
  * Implementations must be pure relative to the FSM: they MUST NOT call
- * triggerEvent / checkTransitions on the same Statemachine. There is no
+ * triggerEvent / checkTransitions on the same Statemachine. Doing so throws
+ * ReentrancyError when the call happens before the observer's first await;
+ * calls made after an await cannot be detected and will deadlock. There is no
  * enqueue handle in the before phase by design — vetoes and validations
  * complete synchronously per observer; chained behaviour belongs in
  * AfterTransitionObserver.
@@ -237,7 +259,14 @@ interface BeforeTransitionObserver<TSubject = unknown> {
  * (and any auto-follow-on transitions) completes.
  */
 interface EnqueueContext {
-    enqueue(event: string, context?: Map<string, unknown>): void;
+    /**
+     * @param ifStateName When provided, the enqueued event is silently
+     * skipped unless the machine is still in that state when the operation
+     * is dequeued — the machine may have moved on in the meantime.
+     * If the machine leaves and returns to that state, the op is not skipped
+     * — only the state name is compared, not entry identity or count.
+     */
+    enqueue(event: string, context?: Map<string, unknown>, ifStateName?: string): void;
 }
 /**
  * Runs after a transition has committed. State has already moved.
@@ -258,6 +287,12 @@ interface StatemachineInterface<TSubject = unknown> {
     getProcess(): ProcessInterface;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    /**
+     * Resolves once the operation queue is empty and the runner is idle,
+     * including operations chained via EnqueueContext.enqueue(). Resolves
+     * immediately if the machine is already idle.
+     */
+    whenIdle(): Promise<void>;
     attachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     detachBefore(observer: BeforeTransitionObserver<TSubject>): void;
     getBeforeObservers(): Iterable<BeforeTransitionObserver<TSubject>>;
@@ -287,10 +322,59 @@ interface StatemachineOptions<TSubject = unknown> {
     initialStateName?: string;
     /** Defaults to OneOrNoneActiveTransition. */
     transitionSelector?: TransitionSelectorInterface<TSubject>;
-    /** Defaults to NullMutex (no cross-process serialization). */
+    /**
+     * Defaults to NullMutex (no cross-process serialization).
+     *
+     * Must be exclusive to this machine — never share one MutexInterface
+     * instance between machines: the engine reads isAcquired() as "this
+     * machine holds the lock", so a shared instance silently disables mutual
+     * exclusion. To coordinate machines, share the underlying
+     * LockAdapterInterface (same resource name) and construct one mutex per
+     * machine, as MutexFactory does.
+     */
     mutex?: MutexInterface;
     /** When true, the engine releases the mutex at the end of each top-level operation. Defaults to true. */
     autoreleaseLock?: boolean;
+    /**
+     * Maximum number of automatic (eventless) transitions a single operation
+     * may take before AutomaticTransitionCycleError is thrown. Guards against
+     * non-terminating automatic loops while allowing legitimate bounded loops
+     * (e.g. condition-terminated retry cycles). Note: transitions committed
+     * before the limit is hit are NOT rolled back. Must be a positive integer;
+     * constructing a Statemachine with a value < 1 throws a RangeError.
+     * Defaults to 100.
+     */
+    maxAutomaticHops?: number;
+    /**
+     * Called when an operation chained via EnqueueContext.enqueue() fails.
+     * Chained operations are not awaited by the caller whose transition
+     * enqueued them, so without this hook their errors are discarded.
+     * Exceptions thrown by the hook itself are swallowed — it must not be
+     * able to break the machine's drain loop.
+     */
+    onChainedOperationError?: (error: unknown, info: {
+        eventName: string;
+    }) => void;
+    /**
+     * Maximum number of operations that may wait in the queue (the running
+     * operation does not count). When the limit is reached, further
+     * triggerEvent/checkTransitions calls reject with
+     * QueueLimitExceededError, and EnqueueContext.enqueue() throws it into
+     * the enqueuing after-observer's error path. In that case the original
+     * caller's promise rejects even though its transition already
+     * committed — check the machine's state, not just the rejection, before
+     * retrying. Must be a positive integer when set. Defaults to Infinity
+     * (unbounded, the previous behavior).
+     */
+    maxQueueLength?: number;
+    /**
+     * Diagnostic hook called whenever the automatic post-operation lock
+     * release throws — including when the operation itself also failed, in
+     * which case the caller's rejection carries the operation error and the
+     * release error would otherwise be discarded. Does not change rejection
+     * behavior. Exceptions thrown by the hook itself are swallowed.
+     */
+    onReleaseError?: (error: unknown) => void;
 }
 
 declare class Statemachine<TSubject = unknown> implements StatemachineInterface<TSubject> {
@@ -301,10 +385,16 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     private currentState;
     private lastState;
     private autoreleaseLock;
+    private readonly maxAutomaticHops;
+    private readonly maxQueueLength;
     private readonly queue;
     private running;
+    private idleWaiters;
+    private inSyncCallback;
     private readonly beforeObservers;
     private readonly afterObservers;
+    private readonly onChainedOperationError?;
+    private readonly onReleaseError?;
     constructor(subject: TSubject, process: ProcessInterface, options?: StatemachineOptions<TSubject>);
     getCurrentState(): StateInterface;
     getLastState(): StateInterface | null;
@@ -323,6 +413,24 @@ declare class Statemachine<TSubject = unknown> implements StatemachineInterface<
     setAutoreleaseLock(autorelease: boolean): void;
     triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
     checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    /**
+     * Resolves once the operation queue is empty and the runner is idle —
+     * i.e. every operation enqueued so far, including operations chained via
+     * EnqueueContext.enqueue(), has completed. Resolves immediately if the
+     * machine is already idle. Note this is a quiescence point, not a
+     * receipt: work scheduled later (e.g. from a timer) starts a new drain.
+     */
+    whenIdle(): Promise<void>;
+    /** Runs fn with the re-entrancy flag set for its SYNCHRONOUS portion only:
+     *  the flag is cleared as soon as fn returns (before any promise it returned
+     *  is awaited), so concurrent external callers are never affected. This
+     *  catches triggerEvent/checkTransitions calls made before a callback's first
+     *  await; calls made after a prior await are not detectable without
+     *  AsyncLocalStorage (Node-only) and will still deadlock — a documented gap. */
+    private guardSync;
+    private assertNotReentrant;
+    /** Single entry point to the operation queue — every enqueue kicks the runner. */
+    private enqueueOperation;
     private runIfIdle;
     private runOperation;
     private resolveEvent;
@@ -372,9 +480,11 @@ interface LastStateHasChangedDateInterface {
     getLastStateHasChangedDate(): Date;
 }
 
+/** @deprecated No longer used internally; will be removed in v4. */
 interface CallbackInterface {
     invoke(): MaybePromise<void>;
 }
+/** @deprecated No longer used internally; will be removed in v4. */
 interface DispatcherInterface extends CallbackInterface {
     dispatch(event: EventInterface, args?: unknown[]): void;
     invoke(): Promise<void>;
@@ -416,19 +526,24 @@ declare class Timeout implements ConditionInterface {
     checkCondition(subject: unknown, context: Map<string, unknown>): boolean;
 }
 
-declare class AndComposite<TSubject = unknown> implements ConditionInterface<TSubject> {
-    private readonly conditions;
+declare abstract class CompositeCondition<TSubject = unknown> implements ConditionInterface<TSubject> {
+    protected readonly conditions: ConditionInterface<TSubject>[];
+    private readonly joinWord;
+    constructor(joinWord: string, condition: ConditionInterface<TSubject>);
+    protected addCondition(condition: ConditionInterface<TSubject>): this;
+    getName(): string;
+    abstract checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
+}
+
+declare class AndComposite<TSubject = unknown> extends CompositeCondition<TSubject> {
     constructor(condition: ConditionInterface<TSubject>);
     addAnd(condition: ConditionInterface<TSubject>): this;
-    getName(): string;
     checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
 }
 
-declare class OrComposite<TSubject = unknown> implements ConditionInterface<TSubject> {
-    private readonly conditions;
+declare class OrComposite<TSubject = unknown> extends CompositeCondition<TSubject> {
     constructor(condition: ConditionInterface<TSubject>);
     addOr(condition: ConditionInterface<TSubject>): this;
-    getName(): string;
     checkCondition(subject: TSubject, context: Map<string, unknown>): Promise<boolean>;
 }
 
@@ -449,12 +564,18 @@ declare class Not<TSubject = unknown> implements ConditionInterface<TSubject> {
 declare class CallbackObserver implements Observer {
     private readonly callback;
     constructor(callback: (...args: unknown[]) => MaybePromise<void>);
-    update(subject: ObservableSubject): MaybePromise<void>;
+    update(subject: ObservableSubject, args?: readonly unknown[]): MaybePromise<void>;
 }
 
 declare class StatefulStatusChanger<TSubject extends StatefulInterface> implements AfterTransitionObserver<TSubject> {
     private readonly subject;
-    constructor(subject: TSubject);
+    /**
+     * @param subject Optional explicit subject to write to. When omitted
+     * (recommended), the observer writes to frame.subject — the subject of
+     * whichever machine fired the transition — so a single instance can be
+     * shared safely across every machine a Factory creates.
+     */
+    constructor(subject?: TSubject);
     notify(frame: TransitionFrame<TSubject>): void;
 }
 
@@ -466,6 +587,10 @@ declare class StatefulStatusChanger<TSubject extends StatefulInterface> implemen
  * top-level operation after the current operation completes. Other
  * after-observers registered after OnEnterObserver still see the original
  * frame, not the chained one.
+ *
+ * The chained event only fires if the machine is still in the entered state
+ * when the queue drains — states passed through transiently by automatic
+ * transitions do not fire onEnter.
  */
 declare class OnEnterObserver<TSubject = unknown> implements AfterTransitionObserver<TSubject> {
     static readonly DEFAULT_EVENT_NAME = "onEnter";
@@ -482,7 +607,14 @@ declare class TransitionLogger<TSubject = unknown> implements AfterTransitionObs
 }
 
 declare class ActiveTransitionFilter {
-    static filter<TSubject = unknown>(transitions: Iterable<TransitionInterface<TSubject>>, subject: TSubject, context: Map<string, unknown>, event?: EventInterface): Promise<TransitionInterface<TSubject>[]>;
+    static filter<TSubject = unknown>(transitions: Iterable<TransitionInterface<TSubject>>, subject: TSubject, context: Map<string, unknown>, event?: EventInterface, 
+    /**
+     * Optional wrapper run around each individual isActive() evaluation. The
+     * Statemachine passes its re-entrancy guard here so that every condition —
+     * not just the first — is evaluated with the guard active; without per-item
+     * wrapping a re-entrant condition on a later transition would deadlock.
+     */
+    wrap?: <T>(fn: () => T) => T): Promise<TransitionInterface<TSubject>[]>;
 }
 
 declare class FilterStateByEvent {
@@ -599,11 +731,12 @@ interface Graph {
     nodes: GraphNode[];
     edges: GraphEdge[];
 }
+type GraphDirection = "TB" | "BT" | "LR" | "RL";
 interface DotOptions {
-    rankdir?: string;
+    rankdir?: GraphDirection;
 }
 interface MermaidOptions {
-    direction?: string;
+    direction?: GraphDirection;
 }
 declare class GraphBuilder {
     private readonly nodes;
@@ -648,7 +781,7 @@ declare class ProcessFinalizedError extends FinitaError {
     constructor(processName: string);
 }
 
-type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidEventName" | "invalidConditionName" | "orphanState";
+type GraphValidationCode = "unknownTarget" | "unknownSource" | "missingInitialState" | "multipleInitialStates" | "invalidStateName" | "invalidEventName" | "invalidConditionName" | "invalidTransitionWeight" | "orphanState";
 declare class GraphValidationError extends FinitaError {
     readonly code: GraphValidationCode;
     readonly details: Readonly<Record<string, unknown>>;
@@ -661,6 +794,8 @@ interface DuplicateTransitionConflict {
     eventName: string | null;
     existingConditionName: string | null;
     newConditionName: string | null;
+    existingWeight?: number;
+    newWeight?: number;
 }
 declare class DuplicateTransitionError extends FinitaError {
     readonly code = "duplicateTransition";
@@ -704,9 +839,19 @@ declare class AmbiguousTransitionError extends FinitaError {
 
 declare class AutomaticTransitionCycleError extends FinitaError {
     readonly code = "automaticTransitionCycle";
-    readonly targetStateName: string;
-    readonly visitedStateNames: readonly string[];
-    constructor(targetStateName: string, visitedStateNames: Iterable<string>);
+    readonly stateName: string;
+    readonly hopLimit: number;
+    constructor(stateName: string, hopLimit: number);
+}
+
+declare class ReentrancyError extends FinitaError {
+    readonly code = "reentrancy";
+    constructor(operation: string);
+}
+
+declare class QueueLimitExceededError extends FinitaError {
+    readonly code = "queueLimitExceeded";
+    constructor(limit: number, eventName: string | null);
 }
 
-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 };
+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 GraphDirection, 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, QueueLimitExceededError, ReentrancyError, 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 };