XState Invoke Pattern

Invoke promises, callbacks, observables, and child machines as services tied to state node lifecycles

When to Use

• Fetching data when entering a state (API calls, database queries)
• Running long-lived processes tied to a state (WebSocket connections, timers)
• Delegating a sub-workflow to a child machine
• Any async operation that should start on state entry and cancel on state exit

Instructions

1. Use

   invoke

   inside a state node. The service starts when the state is entered and is automatically stopped when the state is exited.
2. Handle results with

   onDone

   (success) and

   onError

   (failure) on the invoke config.
3. For promises, the resolved value becomes

   event.data

   in

   onDone

   . The rejected value becomes

   event.data

   in

   onError

   .
4. For callbacks, return a cleanup function — XState calls it when the state is exited.
5. Define services in the machine options under

   services

   (v4) or

   actors

   (v5) to keep machines testable and serializable.
6. Use

   input

   (v5) or

   withContext

   (v4) to pass data to invoked machines.

// data-fetch.machine.ts
import { createMachine, assign } from 'xstate';

interface FetchContext {
  url: string;
  data: unknown | null;
  error: string | null;
}

type FetchEvent = { type: 'RETRY' } | { type: 'REFRESH' };

const fetchMachine = createMachine<FetchContext, FetchEvent>(
  {
    id: 'fetch',
    initial: 'loading',
    context: { url: '', data: null, error: null },
    states: {
      loading: {
        invoke: {
          id: 'fetchData',
          src: 'fetchService',
          onDone: {
            target: 'success',
            actions: assign({ data: (_, event) => event.data, error: null }),
          },
          onError: {
            target: 'failure',
            actions: assign({ error: (_, event) => event.data.message }),
          },
        },
      },
      success: {
        on: { REFRESH: 'loading' },
      },
      failure: {
        on: { RETRY: 'loading' },
      },
    },
  },
  {
    services: {
      fetchService: (ctx) =>
        fetch(ctx.url).then((res) => {
          if (!res.ok) throw new Error(`HTTP ${res.status}`);
          return res.json();
        }),
    },
  }
);

// Callback service — WebSocket connection
const chatMachine = createMachine(
  {
    id: 'chat',
    initial: 'connected',
    states: {
      connected: {
        invoke: {
          id: 'websocket',
          src: 'connectWebSocket',
        },
        on: {
          MESSAGE_RECEIVED: { actions: 'addMessage' },
          DISCONNECT: 'disconnected',
        },
      },
      disconnected: { type: 'final' },
    },
  },
  {
    services: {
      connectWebSocket: (ctx) => (sendBack, onReceive) => {
        const ws = new WebSocket(ctx.wsUrl);
        ws.onmessage = (msg) => sendBack({ type: 'MESSAGE_RECEIVED', data: msg.data });
        // onReceive listens for events sent TO this service
        onReceive((event) => {
          if (event.type === 'SEND_MESSAGE') ws.send(event.text);
        });
        // Cleanup — called when state exits
        return () => ws.close();
      },
    },
  }
);

Details

Service types in v4:

• Promise — resolves once, triggers

  onDone

  or

  onError

• Callback —

  (sendBack, onReceive) => cleanup

  — long-lived, bidirectional
• Observable — emits events over time, completes triggers

  onDone

• Machine — child statechart,

  onDone

  fires when child reaches final state

XState v5 equivalents: Services become

actors

defined with helper functions:

import { fromPromise, fromCallback } from 'xstate';

const machine = setup({
  actors: {
    fetchService: fromPromise(async ({ input }: { input: { url: string } }) => {
      const res = await fetch(input.url);
      return res.json();
    }),
    wsService: fromCallback(({ sendBack, input }) => {
      const ws = new WebSocket(input.url);
      ws.onmessage = (msg) => sendBack({ type: 'MESSAGE_RECEIVED', data: msg.data });
      return () => ws.close();
    }),
  },
}).createMachine({
  /* ... */
});

Automatic cancellation: When the state that owns the invoke exits, XState automatically stops the service. For promises, the

AbortController.signal

is not used automatically — you must wire it yourself if needed. For callbacks, the cleanup function runs.

Multiple invocations: A state can have multiple

invoke

entries (use an array). All start on entry and stop on exit.

Testing: Replace services with mocks in tests by passing

{ services: { fetchService: mockService } }

to

interpret(machine.withConfig({ services: ... }))

.

Source

https://stately.ai/docs/invoke

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.