State Machine Patterns (XState v5)

Read specific reference files based on your task.

When to Use State Machines

Core Pattern: setup + createMachine

Always use setup() for type-safe machines:

import { setup, assign, createActor } from 'xstate';

// 1. Define types explicitly
type Context = {
  data: Data | null;
  error: string | null;
  retries: number;
};

type Events =
  | { type: 'FETCH' }
  | { type: 'SUCCESS'; data: Data }
  | { type: 'FAILURE'; error: string }
  | { type: 'RETRY' };

// 2. Setup with typed implementations
const machine = setup({
  types: {
    context: {} as Context,
    events: {} as Events,
  },
  actions: {
    setData: assign({
      data: ({ event }) => (event as { type: 'SUCCESS'; data: Data }).data,
      error: null,
    }),
    setError: assign({
      error: ({ event }) => (event as { type: 'FAILURE'; error: string }).error,
    }),
    incrementRetries: assign({
      retries: ({ context }) => context.retries + 1,
    }),
  },
  guards: {
    hasRetriesLeft: ({ context }) => context.retries < 3,
  },
}).createMachine({
  id: 'dataFetcher',
  initial: 'idle',
  context: { data: null, error: null, retries: 0 },

  states: {
    idle: {
      on: { FETCH: 'loading' },
    },
    loading: {
      on: {
        SUCCESS: { target: 'success', actions: 'setData' },
        FAILURE: [
          { guard: 'hasRetriesLeft', target: 'retrying', actions: 'setError' },
          { target: 'error', actions: 'setError' },
        ],
      },
    },
    retrying: {
      after: {
        1000: { target: 'loading', actions: 'incrementRetries' },
      },
    },
    success: {
      on: { FETCH: 'loading' },
    },
    error: {
      on: { RETRY: { target: 'loading', actions: assign({ retries: 0 }) } },
    },
  },
});

Quick Reference

When to Read Reference Files

Visualization

XState machines can be visualized at https://stately.ai/viz