use-machine

Finite state machine with typed states, events, and targets.


Package	`@vizejs/composable/use-machine`
Own the source	`vize lib pull composable:use-machine`
Runtime exports	`useMachine`
Gzip budget	1536 B

Usage

import { useMachine } from "@vizejs/composable/use-machine";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useMachine`	state	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—

API

`useMachine`

Finite state machine with typed states, events, and targets. State names are inferred from the keys of states, event names from the keys of every on map, and every target (and initial) must name a declared state, so typos fail to compile. Transitions may carry guards (first passing guard wins) and actions that return the next context; exit runs on the old state before entry runs on the new one, and a self-transition runs both. Synchronous and free of globals: identical on server and client, nothing to dispose.

function useMachine<State extends string, Event extends string = never, Context = undefined>( config: MachineConfig<State, Event, Context>, ): Machine<State, Event, Context>

const fetcher = useMachine({
  initial: "idle",
  context: { retries: 0 },
  states: {
    idle: { on: { FETCH: "loading" } },
    loading: { on: { RESOLVE: "success", REJECT: "failure" } },
    failure: {
      on: {
        RETRY: { target: "loading", guard: (c) => c.retries < 3, action: (c) => ({ retries: c.retries + 1 }) },
      },
    },
    success: {},
  },
});
fetcher.send("FETCH");

Types

`MachineTransition`

Guarded, effectful transition to target.

Member	Type	Description
`target`	`State`	State entered when the transition is taken.
`guard`?	`(context: Context) => boolean`	Take the transition only when this returns `true`.
`action`?	`(context: Context) => Context`	Produce the next context while transitioning.

`MachineStateNode`

One state of a MachineConfig.

Member	Type	Description
`on`?	`{ readonly [Name in Event]?: \| State \| MachineTransition<State, Context> \| readonly MachineTransition<State, Context>[]; }`	Transitions keyed by event: a target state name, one transition object, or a list of guarded transitions where the first passing guard wins.
`entry`?	`(context: Context) => void`	Called with the context after the machine enters this state.
`exit`?	`(context: Context) => void`	Called with the context before the machine leaves this state.

`MachineConfig`

Definition consumed by useMachine.

Member	Type	Description
`initial`	`NoInfer<State>`	State the machine starts (and resets) in.
`context`	`Context`	Initial extended state.
`states`	`{ readonly [Name in State]: MachineStateNode<NoInfer<State>, Event, Context> }`	Every state, keyed by name.

`Machine`

Reactive machine returned by useMachine.

Member	Type	Description
`state`	`Readonly<ShallowRef<State>>`	Current state name.
`context`	`Readonly<ShallowRef<Context>>`	Current extended state.
`nextEvents`	`ComputedRef<Event[]>`	Events that would cause a transition from the current state right now.
`send`	`(event: Event) => boolean`	Deliver an event.
`can`	`(event: Event) => boolean`	Whether `event` would cause a transition right now (guards included).
`matches`	`(...states: readonly State[]) => boolean`	Whether the current state is one of `states`.
`reset`	`() => void`	Return to the initial state and context without running hooks.