createMachine

tested

Create a type-safe synchronous finite state machine with context

Example

const machine = createMachine({
  initial: 'idle',
  context: { retries: 0 },
  states: {
    idle: {
      on: { START: 'running' },
    },
    running: {
      on: {
        FAIL: {
          target: 'idle',
          guard: (ctx) => ctx.retries < 3,
          action: (ctx) => { ctx.retries++; },
        },
        STOP: 'idle',
      },
    },
  },
});

machine.send('START'); // 'running'

Signatures

export function createMachine<
  const States extends Record<string, SyncStateNodeConfig<Context>>,
  Context,
>(config: {
  initial: NoInfer<ExtractStates<States>>;
  context: Context;
  states: States;
}): StateMachine<ExtractStates<States>, ExtractEvents<States>, Context>;

export function createMachine<
  const States extends Record<string, SyncStateNodeConfig<undefined>>,
>(config: {
  initial: NoInfer<ExtractStates<States>>;
  states: States;
}): StateMachine<ExtractStates<States>, ExtractEvents<States>, undefined>;

Parameters

Parameter	Type	Default	Description
`config`	{ initial: string; context?: unknown; // Overload-implementation signature: the typed overloads above expose the real // per-context API; `any` here accepts every concrete `SyncStateNodeConfig<C>` // (contravariant in `C`, so `unknown` would reject them). states: Record<string, SyncStateNodeConfig<any>>; }	—	—

Returns

StateMachine

Property	Type	Default	Description
`send`	`(event: string) => string`	—	Send an event to the machine, potentially causing a state transition
`can`	`(event: string) => boolean`	—	Check if an event can trigger a transition from the current state
`currentState`	`States`	—	—
`states`	`Record<string, NodeConfig>`	—	—
`context`	`Context`	—	Machine context
`current`	`string`	—	Current state of the machine
`matches`	`(state: string) => boolean`	—	Check if the machine is in a specific state

Related Types

TransitionConfig

Configuration for a state transition

interface TransitionConfig<Context, Guard = boolean, Action = void>

Property	Type	Default	Description
`target`	`string`	—	Target state to transition to
`guard`?	`(context: Context) => Guard`	—	Guard condition — transition only occurs if this returns true
`action`?	`(context: Context) => Action`	—	Side effect executed during transition (before entering target state)

StateNodeConfig

Configuration for a state node

interface StateNodeConfig<Context, Guard = boolean, Hook = void>

Property	Type	Default	Description
`on`?	`Record<string, Transition<Context, Guard, Hook>>`	—	Map of event names to transitions
`entry`?	`(context: Context) => Hook`	—	Hook called when entering this state
`exit`?	`(context: Context) => Hook`	—	Hook called when exiting this state

Transition

A transition can be a target state name or a detailed configuration

export type Transition<
  Context,
  Guard = boolean,
  Action = void,
> = string | TransitionConfig<Context, Guard, Action>;

SyncStateNodeConfig

Sync state node config — guards return boolean, hooks return void

export type SyncStateNodeConfig<Context> = StateNodeConfig<Context, boolean, void>;

AsyncStateNodeConfig

Async state node config — guards return MaybePromise<boolean>, hooks return MaybePromise<void>

export type AsyncStateNodeConfig<Context> = StateNodeConfig<Context, MaybePromise<boolean>, MaybePromise<void>>;