BehavioralFsm
Defined in: behavioral-fsm.ts:47
Defines FSM behavior (states + transitions) while tracking per-client state
in a WeakMap. A single BehavioralFsm instance can drive any number of
independent client objects simultaneously — each gets its own state,
deferred queue, and lifecycle.
Prefer createBehavioralFsm() over constructing this directly — the factory
infers all generic parameters from the config object.
All public methods silently no-op after dispose() is called.
Type Parameters
Section titled “Type Parameters”TClient
Section titled “TClient”TClient extends object
The client object type. Must be an object (non-primitive) so it can serve as a WeakMap key.
TStateNames
Section titled “TStateNames”TStateNames extends string
String literal union of valid state names.
TInputNames
Section titled “TInputNames”TInputNames extends string
String literal union of valid input names.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new BehavioralFsm<
TClient,TStateNames,TInputNames>(config):BehavioralFsm<TClient,TStateNames,TInputNames>
Defined in: behavioral-fsm.ts:69
Parameters
Section titled “Parameters”config
Section titled “config”FsmConfig<TClient, Record<string, Record<string, unknown>>>
Returns
Section titled “Returns”BehavioralFsm<TClient, TStateNames, TInputNames>
Properties
Section titled “Properties”[MACHINA_TYPE]
Section titled “[MACHINA_TYPE]”
readonly[MACHINA_TYPE]:"BehavioralFsm"
Defined in: behavioral-fsm.ts:55
readonlyid:string
Defined in: behavioral-fsm.ts:52
initialState
Section titled “initialState”
readonlyinitialState:TStateNames
Defined in: behavioral-fsm.ts:53
Methods
Section titled “Methods”canHandle()
Section titled “canHandle()”canHandle(
client,inputName):boolean
Defined in: behavioral-fsm.ts:126
Returns true if the client’s current state has a handler for inputName
(or a catch-all "*" handler). Does NOT initialize the client — no
_onEnter, no events, no side effects. Unseen clients are treated as
if they were already in initialState. Returns false when disposed.
Parameters
Section titled “Parameters”client
Section titled “client”TClient
inputName
Section titled “inputName”string
Returns
Section titled “Returns”boolean
compositeState()
Section titled “compositeState()”compositeState(
client):string
Defined in: behavioral-fsm.ts:255
Returns the client’s state as a dot-delimited path including any active
child FSM states (e.g. "active.connecting.retrying"). Returns just the
current state name when no child is active. Returns "" for clients that
have never been initialized (unlike currentState() which returns undefined).
Parameters
Section titled “Parameters”client
Section titled “client”TClient
Returns
Section titled “Returns”string
currentState()
Section titled “currentState()”currentState(
client):TStateNames|undefined
Defined in: behavioral-fsm.ts:154
Returns the client’s current state, or undefined if the client has
never been initialized (i.e. handle(), transition(), or reset()
have never been called for it). Does NOT trigger initialization.
Parameters
Section titled “Parameters”client
Section titled “client”TClient
Returns
Section titled “Returns”TStateNames | undefined
dispose()
Section titled “dispose()”dispose(
options?):void
Defined in: behavioral-fsm.ts:316
Permanently shut down this FSM. Irreversible — all subsequent method
calls become silent no-ops. Tears down child subscriptions, clears all
listeners, and cascades disposal to child FSMs (unless preserveChildren
is set). The same child appearing in multiple states is disposed once.
Parameters
Section titled “Parameters”options?
Section titled “options?”Returns
Section titled “Returns”void
emit()
Section titled “emit()”emit(
eventName,data?):void
Defined in: behavioral-fsm.ts:301
Emit a custom event through the FSM. Built-in lifecycle events are emitted automatically — this is for user-defined events from handlers. No-ops when disposed.
Parameters
Section titled “Parameters”eventName
Section titled “eventName”string
unknown
Returns
Section titled “Returns”void
handle()
Section titled “handle()”handle(
client,inputName, …args):void
Defined in: behavioral-fsm.ts:91
Dispatch an input to the given client’s current state handler.
Delegation order: if the current state has a _child FSM that can
handle the input, it is dispatched there. If the child emits nohandler,
the input bubbles up to this FSM’s local handler. If no handler exists
here either, nohandler is emitted on this FSM’s emitter.
No-ops silently when disposed.
Parameters
Section titled “Parameters”client
Section titled “client”TClient
inputName
Section titled “inputName”TInputNames
…unknown[]
Returns
Section titled “Returns”void
Call Signature
Section titled “Call Signature”on<
K>(eventName,callback):Subscription
Defined in: behavioral-fsm.ts:284
Subscribe to a built-in lifecycle event or the wildcard.
Named overload: typed payload includes { client: TClient } so you can
identify which client the event pertains to. Wildcard ("*") receives
(eventName, data) for every event. Returns a no-op Subscription
when disposed.
Type Parameters
Section titled “Type Parameters”K extends "transitioning" | "transitioned" | "handling" | "handled" | "nohandler" | "invalidstate" | "deferred"
Parameters
Section titled “Parameters”eventName
Section titled “eventName”K
callback
Section titled “callback”(data) => void
Returns
Section titled “Returns”Call Signature
Section titled “Call Signature”on(
eventName,callback):Subscription
Defined in: behavioral-fsm.ts:288
Subscribe to a built-in lifecycle event or the wildcard.
Named overload: typed payload includes { client: TClient } so you can
identify which client the event pertains to. Wildcard ("*") receives
(eventName, data) for every event. Returns a no-op Subscription
when disposed.
Parameters
Section titled “Parameters”eventName
Section titled “eventName”"*"
callback
Section titled “callback”(eventName, data) => void
Returns
Section titled “Returns”reset()
Section titled “reset()”reset(
client):void
Defined in: behavioral-fsm.ts:142
Transition the client back to initialState, firing _onEnter and
lifecycle events as if entering it fresh. No-ops when disposed.
Parameters
Section titled “Parameters”client
Section titled “client”TClient
Returns
Section titled “Returns”void
transition()
Section titled “transition()”transition(
client,toState):void
Defined in: behavioral-fsm.ts:172
Directly transition client to toState, running the full lifecycle:
_onExit for the current state → transitioning event → update state →
_onEnter for new state → transitioned event → child reset → deferred
queue replay → bounce (if _onEnter returned a state name).
Same-state transitions are silently ignored. Transitions to unknown state
names emit invalidstate instead of throwing. Throws if the transition
depth exceeds MAX_TRANSITION_DEPTH (likely an _onEnter → transition loop).
No-ops when disposed.
Parameters
Section titled “Parameters”client
Section titled “client”TClient
toState
Section titled “toState”TStateNames
Returns
Section titled “Returns”void