HandlerFn

HandlerFn<TCtx, TStateNames, TPayload> = (args, …extra) => TStateNames | void

Defined in: types.ts:431

A function handler for state inputs, lifecycle hooks (_onEnter, _onExit), and catch-all (*) handlers.

Return value determines transition:

• Return a valid state name → FSM transitions to that state
• Return void/undefined → FSM stays in the current state

This mirrors gen_fsm’s {next_state, StateName, NewStateData} return. Guards are just if statements. Actions are just code before the return.

The ...extra rest parameter captures additional arguments passed through handle(inputName, ...extraArgs). By default these are untyped (unknown[]). An input payload map types them per input (#195): supply it through the curried factory form (createFsm<TInputs>()), and TPayload becomes that input’s declared tuple. Handler parameters are then inferred — no annotation, no cast.

Type Parameters

TCtx

TCtx

TStateNames

TStateNames extends string = string

TPayload

TPayload extends unknown[] = unknown[]

Parameters

args

HandlerArgs<TCtx, TStateNames>

extra

…TPayload

Returns

TStateNames | void

Example

// Side effects only, no transition:
tick({ ctx }) { ctx.tickCount++; }

// Conditional transition (replaces guard + target):
timeout({ ctx }) {
  if (ctx.tickCount >= 3) return "yellow";
}

// Unconditional transition with side effect (replaces action + target):
timeout({ ctx }) {
  console.log("transitioning after", ctx.tickCount, "ticks");
  return "yellow";
}

// Handler with extra args passed via handle("success", responseData):
success({ ctx }, data) { ctx.result = data; }