HandlerArgs

Defined in: types.ts:111

The single combined object passed to every handler.

Handlers return a state name to transition, or void to stay put. This replaces imperative transition() calls — closer to gen_fsm’s return-based model and symmetrical with string shorthand handlers.

Example

// Conditional transition — return the target state:
timeout({ ctx }) {
  if (ctx.tickCount >= 3) return "yellow";
}

// Side effects without transition — return nothing:
tick({ ctx }) {
  ctx.tickCount++;
}

// In a catch-all — inputName tells you what was received:
"*"({ inputName }) {
  console.log(`unhandled input: ${inputName}`);
}

Type Parameters

TCtx

TCtx

The context type. For Fsm this is the config-defined context object. For BehavioralFsm this is the client object itself.

TStateNames

TStateNames extends string = string

String literal union of valid state names. Defaults to string for loose usage; the factory functions narrow this to the actual state names inferred from the config.

Properties

ctx

ctx: TCtx

Defined in: types.ts:113

The context (Fsm) or client object (BehavioralFsm)

---

inputName

inputName: string

Defined in: types.ts:124

The name of the input currently being handled.

Typed as string rather than the inferred input union because:

1. Inside a named handler you already know the input name
2. In a catch-all (*) handler it could be anything
3. Narrowing to the literal per-handler would require complex mapped types for zero practical benefit

Methods

defer()

defer(opts?): void

Defined in: types.ts:139

Defer the current input for replay after a future transition. Erlang’s selective receive, in JS form.

Parameters

opts?

until

TStateNames

Returns

void

Example

// Replay on the next transition to any state
defer();

// Replay only when entering "yellow"
defer({ until: "yellow" });

---

emit()

emit(eventName, data?): void

Defined in: types.ts:146

Emit a custom event through the FSM’s emitter. Built-in events (transitioning, transitioned, etc.) are emitted automatically by the FSM engine — this is for user-defined events.

Parameters

eventName

string

data?

unknown

Returns

void