Advanced

import { createMachine, createActor, assign } from "xstate";
 
// Minimal child machines -- each has its own isolated context
const authMachine = createMachine({
  // => Simple machine representing authentication state
  id: "auth",
  context: { token: null as string | null },
  // => Private to authActor; parent cannot access directly
  initial: "idle",
  states: { idle: {} },
  // => Starts idle, awaiting login events
});
 
const dataMachine = createMachine({
  // => Simple machine representing remote data state
  id: "data",
  context: { items: [] as string[] },
  // => Private to dataActor; parent cannot access directly
  initial: "idle",
  states: { idle: {} },
  // => Starts idle, awaiting fetch events
});
 
// Parent machine spawns both children on entry
const rootMachine = createMachine({
  // => Orchestrates child actors
  id: "root",
  context: {
    authRef: null as any,
    // => Will hold ActorRef to authActor
    dataRef: null as any,
    // => Will hold ActorRef to dataActor
  },
  initial: "running",
  states: {
    running: {
      entry: assign({
        // => entry action fires when machine enters 'running'
        authRef: ({ spawn }) => spawn(authMachine, { id: "authActor" }),
        // => spawn returns ActorRef; id must be unique in this actor system
        dataRef: ({ spawn }) => spawn(dataMachine, { id: "dataActor" }),
        // => Both children start concurrently and immediately
      }),
    },
  },
});
 
const actor = createActor(rootMachine).start();
// => actor.getSnapshot().context.authRef is an ActorRef
// => actor.getSnapshot().context.dataRef is a separate ActorRef

import { createMachine, createActor, assign, sendTo, sendParent } from "xstate";
 
// Producer machine -- sends event to parent when work is done
const producerMachine = createMachine({
  // => A child that notifies the parent about work completion
  id: "producer",
  initial: "working",
  states: {
    working: {
      on: {
        DONE: {
          // => External trigger signals work completion
          actions: sendParent({ type: "CHILD_DONE", payload: "result" }),
          // => sendParent forwards the event up to the spawning machine
          // => Child does NOT know about sibling consumers
        },
      },
    },
  },
});
 
// Consumer machine -- receives routed events from parent
const consumerMachine = createMachine({
  // => A child that waits for routed messages
  id: "consumer",
  initial: "idle",
  states: {
    idle: {
      on: {
        PROCESS: { target: "processing" },
        // => Only responds to PROCESS; parent decides when to send it
      },
    },
    processing: {},
  },
});
 
// Mediator parent: routes CHILD_DONE → consumer
const mediatorMachine = createMachine({
  // => Central router; children communicate only through this machine
  id: "mediator",
  context: { producerRef: null as any, consumerRef: null as any },
  initial: "active",
  states: {
    active: {
      entry: assign({
        producerRef: ({ spawn }) => spawn(producerMachine, { id: "producer" }),
        // => Spawns producer child
        consumerRef: ({ spawn }) => spawn(consumerMachine, { id: "consumer" }),
        // => Spawns consumer child
      }),
      on: {
        CHILD_DONE: {
          // => Mediator intercepts producer's notification
          actions: sendTo(
            ({ context }) => context.consumerRef,
            { type: "PROCESS" },
            // => Routes to consumer with transformed event type
          ),
        },
      },
    },
  },
});

import { createMachine, createActor, assign, sendTo } from "xstate";
 
// Worker machine -- processes one job at a time
const workerMachine = createMachine({
  // => Each instance is an independent actor in the pool
  id: "worker",
  initial: "idle",
  states: {
    idle: {
      on: {
        JOB: {
          // => Receives job event from dispatcher
          target: "busy",
          actions: ({ event }) => console.log("Worker got job:", event.payload),
          // => Logs the job payload; real machine would invoke async work
        },
      },
    },
    busy: {
      on: { DONE: "idle" },
      // => Returns to idle after job completes
    },
  },
});
 
const POOL_SIZE = 3;
// => Fixed pool size; tune based on concurrency needs
 
// Dispatcher machine manages pool + round-robin index
const poolMachine = createMachine({
  // => Spawns N workers; routes jobs in round-robin order
  id: "pool",
  context: {
    workers: [] as any[],
    // => Array of ActorRefs, one per worker
    nextIndex: 0,
    // => Tracks which worker receives the next job
  },
  initial: "running",
  states: {
    running: {
      entry: assign({
        workers: ({ spawn }) =>
          Array.from({ length: POOL_SIZE }, (_, i) => spawn(workerMachine, { id: `worker-${i}` })),
        // => Spawns POOL_SIZE worker actors; each gets a unique id
      }),
      on: {
        DISPATCH: {
          // => External event triggers round-robin dispatch
          actions: [
            sendTo(
              ({ context }) => context.workers[context.nextIndex],
              // => Selects current worker by index
              ({ event }) => ({ type: "JOB", payload: event.payload }),
              // => Forwards the payload as a JOB event
            ),
            assign({
              nextIndex: ({ context }) => (context.nextIndex + 1) % POOL_SIZE,
              // => Advances index; wraps at POOL_SIZE (round-robin)
            }),
          ],
        },
      },
    },
  },
});

import { createMachine, createActor, assign, sendTo } from "xstate";
 
// Notification machine -- registered with a system-wide id
const notificationMachine = createMachine({
  // => Acts as a global notification sink in the actor system
  id: "notifications",
  initial: "listening",
  states: {
    listening: {
      on: {
        NOTIFY: {
          // => Any actor in the system can send NOTIFY here
          actions: ({ event }) => console.log("Notification:", event.message),
          // => Centralises all user-facing messages in one machine
        },
      },
    },
  },
});
 
// Deep child machine -- uses system.get to reach the notification actor
const deepChildMachine = createMachine({
  // => Nested actor that does not hold notificationRef in its own context
  id: "deepChild",
  initial: "working",
  states: {
    working: {
      on: {
        FINISH: {
          // => When work finishes, notify via system registry
          actions: sendTo(
            ({ system }) => system.get("notifier"),
            // => system.get resolves actor by systemId at event time
            // => No need to pass ActorRef through parent context chain
            { type: "NOTIFY", message: "Deep child finished" },
          ),
        },
      },
    },
  },
});
 
// Root machine registers the notification actor with a systemId
const rootMachine = createMachine({
  // => Registers notifier so any actor can resolve it via system.get
  id: "root",
  context: { notifierRef: null as any, childRef: null as any },
  initial: "running",
  states: {
    running: {
      entry: assign({
        notifierRef: ({ spawn }) =>
          spawn(notificationMachine, {
            id: "notifier",
            systemId: "notifier",
            // => systemId registers this actor in the actor system registry
          }),
        childRef: ({ spawn }) => spawn(deepChildMachine, { id: "child" }),
        // => deepChild does NOT receive notifierRef as a prop
      }),
    },
  },
});
 
const actor = createActor(rootMachine).start();
// => actor.system.get("notifier") returns the notification ActorRef

import { createMachine, assign, fromPromise } from "xstate";
 
// Simulated login API -- replace with real fetch in production
const loginAPI = async (credentials: { email: string; password: string }) => {
  // => Async function; returns user object or throws on failure
  if (credentials.password === "wrong") throw new Error("Invalid credentials");
  // => Simulates server rejection
  return { user: { id: "1", name: "Alice" }, token: "tok_abc123" };
  // => Returns strongly typed user and token on success
};
 
export const authMachine = createMachine(
  {
    // => Top-level auth FSM; controls all login/logout state
    id: "auth",
    initial: "unauthenticated",
    context: {
      user: null as { id: string; name: string } | null,
      token: null as string | null,
      // => Null until authenticated; cleared on logout
      error: null as string | null,
      // => Holds last error message for display
    },
    states: {
      unauthenticated: {
        on: {
          LOGIN: {
            target: "authenticating",
            // => Trigger: user submits credentials
          },
        },
      },
      authenticating: {
        invoke: {
          src: "loginAPI",
          // => Calls the loginAPI actor (defined in actors config below)
          input: ({ event }) => (event as any).credentials,
          // => Passes credentials from the LOGIN event to the API
          onDone: {
            target: "authenticated",
            actions: assign({
              user: ({ event }) => event.output.user,
              // => Stores returned user in context
              token: ({ event }) => event.output.token,
              // => Stores token for subsequent API calls
              error: null,
              // => Clears any previous error
            }),
          },
          onError: {
            target: "failed",
            actions: assign({
              error: ({ event }) => (event.error as Error).message,
              // => Preserves error message for UI display
            }),
          },
        },
      },
      authenticated: {
        on: {
          LOGOUT: {
            target: "unauthenticated",
            actions: assign({ user: null, token: null }),
            // => Clears credentials; machine returns to initial state
          },
        },
      },
      failed: {
        on: { RETRY: "authenticating" },
        // => User can retry from the same failed state
      },
    },
  },
  {
    actors: {
      loginAPI: fromPromise(({ input }) => loginAPI(input as any)),
      // => Wraps async function as a promise actor
    },
  },
);

import { createMachine, assign, fromPromise } from "xstate";
 
// Wizard context accumulates all form fields
type WizardContext = {
  name: string;
  email: string;
  plan: string;
  error: string | null;
};
 
export const wizardMachine = createMachine(
  {
    // => Three-step sign-up wizard
    id: "wizard",
    initial: "step1",
    context: { name: "", email: "", plan: "", error: null } as WizardContext,
    states: {
      step1: {
        on: {
          NEXT: {
            target: "step2",
            actions: assign({ name: ({ event }) => (event as any).name }),
            // => Captures name from event; context is updated before transition
          },
        },
      },
      step2: {
        on: {
          NEXT: {
            target: "step3",
            actions: assign({ email: ({ event }) => (event as any).email }),
            // => Captures email; previous fields (name) remain intact
          },
          BACK: "step1",
          // => Back navigation preserves context; only state changes
        },
      },
      step3: {
        on: {
          SUBMIT: "submitting",
          // => Triggers final submission with all accumulated context
          BACK: "step2",
          // => User can still go back and change email
        },
      },
      submitting: {
        invoke: {
          src: "submitWizard",
          // => Submits the complete wizard context to the API
          input: ({ context }) => context,
          // => Passes entire accumulated context as the API input
          onDone: "success",
          onError: {
            target: "failure",
            actions: assign({
              error: ({ event }) => (event.error as Error).message,
            }),
          },
        },
      },
      success: { type: "final" },
      // => Terminal state; wizard is complete
      failure: {
        on: { RETRY: "submitting" },
        // => User can retry submission without re-entering form data
      },
    },
  },
  {
    actors: {
      submitWizard: fromPromise(async ({ input }) => {
        // => Replace with real API call
        console.log("Submitting:", input);
        // => Logs accumulated wizard data
        return { ok: true };
      }),
    },
  },
);

import { createMachine, assign, fromCallback } from "xstate";
 
// fromCallback actor wraps the native WebSocket lifecycle
const websocketActor = fromCallback(({ sendBack, input }) => {
  // => sendBack sends events to the parent machine
  // => input contains { url } from the invoke's input field
  const ws = new WebSocket((input as any).url);
  // => Create socket; does not block -- callbacks fire asynchronously
 
  ws.onopen = () => sendBack({ type: "WS_OPEN" });
  // => Fires when connection is established
  ws.onmessage = (e) => sendBack({ type: "WS_MESSAGE", data: e.data });
  // => Fires for each incoming message
  ws.onerror = () => sendBack({ type: "WS_ERROR" });
  // => Fires on connection error
  ws.onclose = () => sendBack({ type: "WS_CLOSE" });
  // => Fires when connection drops unexpectedly
 
  return () => ws.close();
  // => Cleanup: close socket when machine leaves the invoking state
});
 
export const wsMachine = createMachine({
  // => WebSocket connection lifecycle FSM
  id: "ws",
  initial: "disconnected",
  context: { url: "wss://echo.example.com", retries: 0 },
  states: {
    disconnected: {
      on: { CONNECT: "connecting" },
    },
    connecting: {
      invoke: {
        src: websocketActor,
        input: ({ context }) => ({ url: context.url }),
        // => Passes url from context to the fromCallback actor
      },
      on: {
        WS_OPEN: "connected",
        // => Transition fires when ws.onopen sends WS_OPEN
        WS_ERROR: "disconnected",
        // => Failed to connect; return to disconnected
      },
    },
    connected: {
      on: {
        DISCONNECT: "disconnected",
        // => Intentional disconnect; cleanup runs automatically
        WS_CLOSE: "reconnecting",
        // => Unexpected close; attempt to reconnect
        WS_MESSAGE: {
          actions: ({ event }) => console.log("Received:", event.data),
          // => Handle incoming data; stays in connected state
        },
      },
    },
    reconnecting: {
      after: {
        2000: "connecting",
        // => Wait 2 s then attempt reconnect
      },
      on: {
        GIVE_UP: "disconnected",
        // => User or external logic can abort reconnection
      },
    },
  },
});

import { createMachine, assign, fromPromise } from "xstate";
 
const MAX_RETRIES = 3;
// => Cap retries to prevent infinite loops
 
const fetchData = async (url: string) => {
  // => Real implementation would use fetch(); this simulates failure then success
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
};
 
export const fetchMachine = createMachine(
  {
    // => Data fetching FSM with exponential backoff
    id: "fetch",
    initial: "idle",
    context: { data: null as unknown, error: null as string | null, retries: 0 },
    states: {
      idle: {
        on: { FETCH: "loading" },
      },
      loading: {
        entry: assign({ error: null }),
        // => Clear previous error on each attempt
        invoke: {
          src: "fetchData",
          input: () => "https://api.example.com/data",
          // => URL could come from context or event in a real machine
          onDone: {
            target: "success",
            actions: assign({
              data: ({ event }) => event.output,
              retries: 0,
              // => Reset retries on success
            }),
          },
          onError: {
            target: "failed",
            actions: assign({
              error: ({ event }) => (event.error as Error).message,
              retries: ({ context }) => context.retries + 1,
              // => Increment retry counter for backoff calculation
            }),
          },
        },
      },
      success: { type: "final" },
      failed: {
        always: {
          guard: ({ context }) => context.retries >= MAX_RETRIES,
          // => Guard: if max retries reached, stay in failed (no auto-retry)
          target: "idle",
          // => Reset to idle so user can manually retry
        },
        after: {
          BACKOFF_DELAY: "loading",
          // => Named delay; value computed dynamically in delays config
        },
        on: { CANCEL: "idle" },
      },
    },
  },
  {
    actors: {
      fetchData: fromPromise(({ input }) => fetchData(input as string)),
    },
    delays: {
      BACKOFF_DELAY: ({ context }) => Math.min(1000 * 2 ** context.retries, 30000),
      // => 1s, 2s, 4s, 8s … capped at 30 s
      // => Exponential backoff reduces server pressure during outages
    },
  },
);

import { createMachine, assign, fromPromise } from "xstate";
 
type ItemContext = {
  value: string;
  previousValue: string | null;
  // => Snapshot before optimistic update; used for rollback
  error: string | null;
};
 
export const optimisticMachine = createMachine(
  {
    // => Optimistic update FSM: apply first, confirm or rollback later
    id: "optimistic",
    initial: "idle",
    context: { value: "initial", previousValue: null, error: null } as ItemContext,
    states: {
      idle: {
        on: {
          UPDATE: {
            target: "saving",
            actions: assign({
              previousValue: ({ context }) => context.value,
              // => Snapshot current value BEFORE overwriting
              value: ({ event }) => (event as any).newValue,
              // => Apply new value immediately -- user sees it at once
              error: null,
            }),
          },
        },
      },
      saving: {
        invoke: {
          src: "updateAPI",
          input: ({ context }) => ({ value: context.value }),
          // => Sends the optimistically applied value to the server
          onDone: {
            target: "idle",
            actions: assign({ previousValue: null }),
            // => Server confirmed: discard the snapshot
          },
          onError: {
            target: "idle",
            actions: assign({
              value: ({ context }) => context.previousValue ?? context.value,
              // => Roll back to snapshot on failure
              previousValue: null,
              error: ({ event }) => (event.error as Error).message,
              // => Surface error to UI
            }),
          },
        },
      },
    },
  },
  {
    actors: {
      updateAPI: fromPromise(async ({ input }) => {
        // => Simulated API; throws 50% of the time for demo
        if (Math.random() < 0.5) throw new Error("Network error");
        return input;
      }),
    },
  },
);

// Note: requires react, @tanstack/react-query, @xstate/react
import { createMachine, fromPromise } from "xstate";
// => XState imports -- no React Query import needed inside the machine
 
// The machine wraps the mutation as a fromPromise actor
// React Query's mutateAsync is passed in via machine input
export const formMachine = createMachine(
  {
    // => Controls form submission lifecycle; agnostic to server-cache details
    id: "form",
    initial: "idle",
    context: { error: null as string | null },
    states: {
      idle: {
        on: { SUBMIT: "submitting" },
      },
      submitting: {
        invoke: {
          src: "submitMutation",
          // => Calls the actor registered below; actor wraps mutateAsync
          input: ({ event }) => (event as any).formData,
          // => Passes form data from the SUBMIT event
          onDone: "success",
          onError: {
            target: "idle",
            actions: ({ context, event }) => {
              (context as any).error = (event.error as Error).message;
              // => Stores error for display in the form
            },
          },
        },
      },
      success: {},
    },
  },
  {
    actors: {
      // submitMutation is provided at runtime via machine.provide()
      // allowing the React Query mutateAsync to be injected:
      // const machine = formMachine.provide({
      //   actors: { submitMutation: fromPromise(({ input }) => mutateAsync(input)) }
      // });
      submitMutation: fromPromise(async ({ input }) => input),
      // => Placeholder; replaced at runtime with mutateAsync
    },
  },
);
 
// React component usage (pseudocode):
// const mutation = useMutation({ mutationFn: createPost });
// const [state, send] = useMachine(
//   formMachine.provide({
//     actors: { submitMutation: fromPromise(({ input }) => mutation.mutateAsync(input)) }
//   })
// );

// Note: requires the 'effect' npm package
// import { Effect } from "effect";
 
import { createMachine, fromPromise } from "xstate";
 
// Simulated Effect-style computation (without importing effect for portability)
// In real usage: Effect.gen(function* () { ... }).pipe(Effect.runPromise)
const effectLikeComputation = async (userId: string): Promise<{ name: string }> => {
  // => Represents Effect<User, HttpError, never> bridged to Promise
  if (!userId) throw Object.assign(new Error("Not found"), { _tag: "NotFound" });
  // => Effect's typed errors become typed thrown objects
  return { name: "Alice" };
  // => Success case resolves with User
};
 
export const effectMachine = createMachine(
  {
    // => Machine that invokes an Effect-based service
    id: "effectMachine",
    initial: "idle",
    context: {
      user: null as { name: string } | null,
      errorTag: null as string | null,
      // => Stores Effect error _tag for precise error handling
    },
    states: {
      idle: {
        on: { LOAD: "loading" },
      },
      loading: {
        invoke: {
          src: "loadUser",
          input: ({ event }) => (event as any).userId,
          // => Passes userId to the actor
          onDone: {
            target: "success",
            actions: ({ context, event }) => {
              context.user = event.output;
              // => Stores the resolved user from Effect output
            },
          },
          onError: {
            target: "error",
            actions: ({ context, event }) => {
              context.errorTag = (event.error as any)._tag ?? "Unknown";
              // => Captures Effect's discriminated error tag
              // => Allows machine to branch on NotFound vs Unauthorized etc.
            },
          },
        },
      },
      success: {},
      error: {},
    },
  },
  {
    actors: {
      loadUser: fromPromise(
        ({ input }) => effectLikeComputation(input as string),
        // => Effect.runPromise(myEffect) would go here in real usage
        // => fromPromise is the only bridge needed; no XState-Effect adapter required
      ),
    },
  },
);

// Note: requires zustand -- npm install zustand
// import { create } from "zustand";
 
import { createMachine, assign, fromPromise } from "xstate";
 
// Simulated Zustand store shape (without importing zustand for portability)
type AppStore = {
  draftName: string;
  savedName: string;
  setSavedName: (name: string) => void;
};
 
// In real usage: const useAppStore = create<AppStore>((set) => ({ ... }));
// Machine reads initial draftName from store, saves result back
 
export const editNameMachine = createMachine(
  {
    // => Multi-step edit flow; reads from and writes to external Zustand store
    id: "editName",
    initial: "editing",
    context: ({ input }) => ({
      // => input is provided at createActor time from Zustand store
      draftName: (input as any)?.draftName ?? "",
      // => Bootstraps context from Zustand; not live-synced
      savedName: null as string | null,
    }),
    states: {
      editing: {
        on: {
          CHANGE: {
            actions: assign({
              draftName: ({ event }) => (event as any).value,
              // => XState context tracks local edits; Zustand unchanged
            }),
          },
          SAVE: "saving",
        },
      },
      saving: {
        invoke: {
          src: "saveToAPI",
          input: ({ context }) => context.draftName,
          onDone: {
            target: "saved",
            actions: [
              assign({ savedName: ({ context }) => context.draftName }),
              // => Update machine context with persisted value
              ({ context }) => {
                // => Side-effect: write back to Zustand store
                // useAppStore.getState().setSavedName(context.draftName);
                console.log("Zustand updated with:", context.draftName);
                // => In production, call the Zustand setter here
              },
            ],
          },
        },
      },
      saved: { type: "final" },
    },
  },
  {
    actors: {
      saveToAPI: fromPromise(async ({ input }) => {
        console.log("Saving:", input);
        return input;
      }),
    },
  },
);
 
// Usage with Zustand (pseudocode):
// const { draftName } = useAppStore();
// const actor = createActor(editNameMachine, { input: { draftName } });

// Note: requires react-hook-form and @xstate/react
// import { useForm } from "react-hook-form";
// import { useMachine } from "@xstate/react";
 
import { createMachine, assign, fromPromise } from "xstate";
 
type FormData = { email: string; password: string };
 
export const rhfMachine = createMachine(
  {
    // => Submission lifecycle machine; RHF handles field-level concerns
    id: "rhfForm",
    initial: "idle",
    context: { error: null as string | null },
    states: {
      idle: {
        on: {
          SUBMIT: "submitting",
          // => Triggered by RHF handleSubmit after validation passes
          // => Event carries validated FormData
        },
      },
      submitting: {
        invoke: {
          src: "submitForm",
          input: ({ event }) => (event as any).data as FormData,
          // => RHF-validated data is the actor input
          onDone: "done",
          onError: {
            target: "error",
            actions: assign({
              error: ({ event }) => (event.error as Error).message,
              // => Captures server-side error for display
            }),
          },
        },
      },
      done: {},
      // => Success state; component shows confirmation UI
      error: {
        on: { RESET: { target: "idle", actions: assign({ error: null }) } },
        // => Allows user to dismiss error and resubmit
      },
    },
  },
  {
    actors: {
      submitForm: fromPromise(async ({ input }) => {
        console.log("Submitting form:", input);
        // => Replace with real API call e.g. POST /api/login
        return { userId: "u_123" };
      }),
    },
  },
);
 
// React component pattern (pseudocode):
// const { register, handleSubmit } = useForm<FormData>();
// const [state, send] = useMachine(rhfMachine);
// const onSubmit = handleSubmit((data) => send({ type: "SUBMIT", data }));
// RHF validates then calls send; XState takes over from there

// Note: requires @xstate/graph -- npm install @xstate/graph
// import { createTestModel } from "@xstate/graph";
 
import { createMachine } from "xstate";
 
// Simple toggle machine as the system under test
const toggleMachine = createMachine({
  // => Target machine for model-based test generation
  id: "toggle",
  initial: "off",
  states: {
    off: { on: { TOGGLE: "on" } },
    on: { on: { TOGGLE: "off" } },
  },
});
 
// Model-based test setup (pseudocode -- requires @xstate/graph in test env)
// const model = createTestModel(toggleMachine);
// => createTestModel wraps the machine with path-traversal utilities
 
// const paths = model.getShortestPaths();
// => Generates all shortest paths through the graph:
// =>   Path 1: off → (TOGGLE) → on
// =>   Path 2: off → (TOGGLE) → on → (TOGGLE) → off
 
// paths.forEach((path) => {
//   it(path.description, async () => {
//     await path.test({
//       states: {
//         off: ({ actor }) => expect(actor.getSnapshot().value).toBe("off"),
//         // => Assert UI renders "OFF" button
//         on: ({ actor }) => expect(actor.getSnapshot().value).toBe("on"),
//         // => Assert UI renders "ON" button
//       },
//       events: {
//         TOGGLE: ({ actor }) => actor.send({ type: "TOGGLE" }),
//         // => Drive the machine by sending the event
//       },
//     });
//   });
// });
 
// Standalone verification (no @xstate/graph import needed)
const actor = createMachine({
  // => Manual path traversal as fallback for test environments without graph
  id: "toggleTest",
  initial: "off",
  states: {
    off: { on: { TOGGLE: "on" } },
    on: { on: { TOGGLE: "off" } },
  },
});
 
console.log("Model-based testing traverses all paths automatically");
// => In real usage, @xstate/graph generates the path objects

import { createMachine, createActor, assign, sendTo } from "xstate";
import { describe, it, expect, vi } from "vitest";
 
// Child machine that tracks received events
const childMachine = createMachine({
  // => Simple counter child; each INCREMENT increments count
  id: "child",
  context: { count: 0 },
  on: {
    INCREMENT: {
      actions: assign({ count: ({ context }) => context.count + 1 }),
      // => Increments on each INCREMENT event from parent
    },
  },
});
 
// Parent that spawns child and forwards TICK events as INCREMENT
const parentMachine = createMachine({
  // => Parent forwards external TICK events to child actor
  id: "parent",
  context: { childRef: null as any },
  initial: "running",
  states: {
    running: {
      entry: assign({
        childRef: ({ spawn }) => spawn(childMachine, { id: "child" }),
        // => Spawn child on entry
      }),
      on: {
        TICK: {
          actions: sendTo(({ context }) => context.childRef, { type: "INCREMENT" }),
          // => Route TICK → INCREMENT to child
        },
      },
    },
  },
});
 
describe("Actor system", () => {
  it("child receives forwarded events from parent", () => {
    const actor = createActor(parentMachine).start();
    // => Start the parent actor (child spawns immediately)
 
    const childRef = actor.getSnapshot().context.childRef;
    // => Retrieve child ActorRef from parent context
 
    const snapshots: any[] = [];
    childRef.subscribe((snap: any) => snapshots.push(snap));
    // => Subscribe to child snapshots to observe state changes
 
    actor.send({ type: "TICK" });
    // => Send TICK to parent; parent forwards INCREMENT to child
    actor.send({ type: "TICK" });
    // => Second TICK; child should now have count = 2
 
    expect(childRef.getSnapshot().context.count).toBe(2);
    // => Assert child processed both forwarded events
    expect(snapshots.length).toBeGreaterThanOrEqual(2);
    // => Subscription fired at least twice (one per INCREMENT)
  });
});

import { createMachine, createActor } from "xstate";
import { SimulatedClock } from "xstate/simulation";
// => SimulatedClock is a test utility bundled with xstate
import { describe, it, expect } from "vitest";
 
// Machine with a delayed self-transition (auto-closes after 3 s)
const toastMachine = createMachine({
  // => Notification toast that auto-dismisses after 3000 ms
  id: "toast",
  initial: "visible",
  states: {
    visible: {
      after: {
        3000: "dismissed",
        // => Normally waits 3 real seconds; SimulatedClock bypasses this
      },
      on: { DISMISS: "dismissed" },
      // => Manual dismiss also available
    },
    dismissed: { type: "final" },
    // => Terminal state; toast is gone
  },
});
 
describe("Toast auto-dismiss", () => {
  it("dismisses after 3000 ms without real delay", () => {
    const clock = new SimulatedClock();
    // => Create a controllable clock; starts at time 0
 
    const actor = createActor(toastMachine, { clock }).start();
    // => Pass clock to actor; all internal timers use it
 
    expect(actor.getSnapshot().value).toBe("visible");
    // => At t=0, toast is visible
 
    clock.increment(3000);
    // => Advance simulated time by 3000 ms instantly
    // => The after(3000) transition fires synchronously
 
    expect(actor.getSnapshot().value).toBe("dismissed");
    // => Toast is now dismissed without waiting real time
  });
});

import { createMachine, initialSnapshot } from "xstate";
 
// Simple traffic light machine
const trafficMachine = createMachine({
  // => FSM for stateless server-side transition calculation
  id: "traffic",
  initial: "green",
  states: {
    green: { on: { NEXT: "yellow" } },
    yellow: { on: { NEXT: "red" } },
    red: { on: { NEXT: "green" } },
  },
});
 
// Get the initial snapshot without starting an actor
const initial = initialSnapshot(trafficMachine);
// => Returns a MachineSnapshot with value: "green"
// => No actor is created; no effects run
 
// Calculate next state purely
const afterFirst = trafficMachine.transition(initial, { type: "NEXT" });
// => Returns new MachineSnapshot with value: "yellow"
// => Synchronous; no timers, promises, or subscriptions created
 
const afterSecond = trafficMachine.transition(afterFirst, { type: "NEXT" });
// => Returns new MachineSnapshot with value: "red"
 
console.log(initial.value); // => "green"
console.log(afterFirst.value); // => "yellow"
console.log(afterSecond.value); // => "red"
 
// Server-side usage: calculate next state from persisted snapshot
// const persisted = JSON.parse(req.body.snapshot);
// const restored = trafficMachine.resolveSnapshot(persisted);
// const next = trafficMachine.transition(restored, event);
// res.json(next);

import { createMachine, createActor } from "xstate";
 
const editorMachine = createMachine({
  // => Editor with pause/resume that restores exact substate
  id: "editor",
  initial: "editing",
  states: {
    editing: {
      initial: "writing",
      states: {
        writing: { on: { FORMAT: "formatting" } },
        formatting: { on: { WRITE: "writing" } },
        hist: {
          type: "history",
          history: "deep",
          // => 'deep': restores entire active configuration recursively
          // => 'shallow' (default): only restores direct child substate
        },
      },
      on: { PAUSE: "paused" },
    },
    paused: {
      on: {
        RESUME: "editing.hist",
        // => Re-enters editing via the history pseudostate
        // => Restores whatever substate was active when PAUSE was sent
      },
    },
  },
});
 
const actor = createActor(editorMachine).start();
// => Starts in editing.writing
 
actor.send({ type: "FORMAT" });
// => Now in editing.formatting
 
actor.send({ type: "PAUSE" });
// => Transitions to paused; editing.formatting is remembered in hist
 
actor.send({ type: "RESUME" });
// => Transitions to editing.hist → restores editing.formatting
// => Deep history: even deeply nested substates are restored
 
console.log(actor.getSnapshot().value);
// => { editing: "formatting" } -- not editing.writing (the initial)

import { createMachine, createActor } from "xstate";
 
const checkoutMachine = createMachine({
  // => Multi-step checkout; user must be able to resume after page reload
  id: "checkout",
  initial: "cart",
  context: { items: [] as string[], address: "" },
  states: {
    cart: { on: { NEXT: "address" } },
    address: {
      on: {
        NEXT: "payment",
        SET_ADDRESS: {
          actions: ({ context, event }) => {
            context.address = (event as any).value;
            // => Store address in context for persistence
          },
        },
      },
    },
    payment: { on: { CONFIRM: "confirmed" } },
    confirmed: { type: "final" },
  },
});
 
// --- Persist ---
const actor = createActor(checkoutMachine).start();
actor.send({ type: "NEXT" }); // cart → address
actor.send({ type: "SET_ADDRESS", value: "123 Main St" });
 
const persistedSnapshot = actor.getPersistedSnapshot();
// => Returns a serialisable plain object representing current state + context
 
const serialised = JSON.stringify(persistedSnapshot);
// => Store in localStorage, database, or server session
// localStorage.setItem("checkout", serialised);
 
// --- Restore ---
const stored = JSON.parse(serialised);
// => Retrieve from storage (simulated here)
 
const restoredActor = createActor(checkoutMachine, { snapshot: stored }).start();
// => Starts directly in the persisted state ('address') with persisted context
 
console.log(restoredActor.getSnapshot().value); // => "address"
console.log(restoredActor.getSnapshot().context.address); // => "123 Main St"
// => Full state + context restored; user picks up exactly where they left off

// Note: requires @xstate/inspect -- npm install @xstate/inspect
// import { createBrowserInspector } from "@xstate/inspect";
 
import { createMachine, createActor } from "xstate";
 
// Any machine can be inspected -- use your real machine here
const counterMachine = createMachine({
  // => Simple counter; used here to demonstrate inspector attachment
  id: "counter",
  context: { count: 0 },
  on: {
    INCREMENT: {
      actions: ({ context }) => {
        context.count += 1;
        // => In-place mutation pattern (XState v5 immer-style)
      },
    },
  },
});
 
// Production-safe inspector setup (only in development)
const isDev = process.env.NODE_ENV === "development";
// => Guard prevents inspector overhead in production
 
// In development, create the inspector:
// const { inspect } = createBrowserInspector();
// => Opens inspector panel in browser devtools
// => Inspector URL: http://stately.ai/viz?inspect
 
// Attach inspector to actor via inspect option:
const actor = createActor(
  counterMachine,
  isDev
    ? {
        // inspect,
        // => Uncomment to enable inspector; all events stream to devtools
      }
    : {},
  // => In production, no inspect option = zero overhead
);
 
actor.start();
actor.send({ type: "INCREMENT" });
// => In dev mode, this event appears in the inspector timeline
actor.send({ type: "INCREMENT" });
// => Inspector shows state, context, and full event history
 
console.log(actor.getSnapshot().context.count); // => 2
// => Context is also visible in inspector panel

// v4: Machine() + interpret() + services config
import { Machine, interpret } from "xstate"; // => v4 imports
 
const machineV4 = Machine(
  {
    // => Machine() is removed in v5; use createMachine()
    id: "counter",
    context: { count: 0 },
    on: {
      INC: { actions: "increment" },
    },
  },
  {
    services: {
      // => 'services' key renamed to 'actors' in v5
      myService: () => Promise.resolve(42),
    },
    actions: {
      increment: (context) => {
        context.count += 1;
      },
      // => v4 actions receive context directly as first arg
    },
  },
);
 
const serviceV4 = interpret(machineV4).start();
// => interpret() removed in v5; use createActor()

// v5: createMachine() + createActor() + actors config
import { createMachine, createActor, assign, fromPromise } from "xstate";
// => v5 imports; all named exports, no default export
 
const machineV5 = createMachine(
  {
    // => createMachine() replaces Machine()
    id: "counter",
    context: { count: 0 },
    on: {
      INC: { actions: assign({ count: ({ context }) => context.count + 1 }) },
      // => assign() takes a function returning partial context (v5)
      // => v4 object-assign form still works but function form preferred
    },
  },
  {
    actors: {
      // => 'actors' replaces 'services' in implementation config
      myActor: fromPromise(() => Promise.resolve(42)),
      // => fromPromise() wraps async functions as actor logic
    },
  },
);
 
const actorV5 = createActor(machineV5).start();
// => createActor() replaces interpret()
// => API is identical after .start(): send(), getSnapshot(), subscribe()

// Counter reducer -- fine for simple linear state
type CounterState = { count: number; loading: boolean; error: string | null };
 
function counterReducer(state: CounterState, action: { type: string }): CounterState {
  // => Reducer handles all actions in all states -- no guard on loading
  switch (action.type) {
    case "INCREMENT":
      return { ...state, count: state.count + 1 };
    // => BUG RISK: can increment while loading=true; reducer allows it
    case "FETCH_START":
      return { ...state, loading: true };
    case "FETCH_SUCCESS":
      return { ...state, loading: false };
    default:
      return state;
  }
}

import { createMachine, assign } from "xstate";
 
// Same counter but with impossible-state prevention
const counterMachine = createMachine({
  // => XState structurally forbids INCREMENT in 'loading' state
  id: "counter",
  initial: "idle",
  context: { count: 0 },
  states: {
    idle: {
      on: {
        INCREMENT: { actions: assign({ count: ({ context }) => context.count + 1 }) },
        // => INCREMENT only valid in 'idle'; ignored in 'loading'
        FETCH: "loading",
      },
    },
    loading: {
      // => No INCREMENT here -- the state makes it structurally impossible
      // => Reducer needs runtime guard; machine enforces this at definition time
      on: { SUCCESS: "idle", FAILURE: "error" },
    },
    error: { on: { RETRY: "loading" } },
  },
});

import { setup, assign } from "xstate";
 
// Discriminated union context: each status has exactly the right fields
type FetchContext =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: string[] }
  // => 'data' only exists when status is 'success'
  | { status: "error"; message: string };
// => 'message' only exists when status is 'error'
 
// setup() declares types before the machine body
const fetchMachine = setup({
  types: {
    context: {} as FetchContext,
    // => TypeScript uses this annotation to type all context accesses
    events: {} as { type: "FETCH" } | { type: "SUCCESS"; data: string[] } | { type: "ERROR"; message: string },
    // => Exhaustive event union; unknown event types are compile errors
  },
}).createMachine({
  // => Machine body uses declared types; no `as any` needed
  id: "fetch",
  initial: "idle",
  context: { status: "idle" } as FetchContext,
  states: {
    idle: {
      on: {
        FETCH: {
          target: "loading",
          actions: assign(() => ({ status: "loading" as const })),
          // => assign returns new context shape; discriminant updated
        },
      },
    },
    loading: {
      on: {
        SUCCESS: {
          target: "success",
          actions: assign(({ event }) => ({
            status: "success" as const,
            data: event.data,
            // => TypeScript knows event.data exists because event type is SUCCESS
          })),
        },
        ERROR: {
          target: "error",
          actions: assign(({ event }) => ({
            status: "error" as const,
            message: event.message,
            // => TypeScript knows event.message exists because event type is ERROR
          })),
        },
      },
    },
    success: {},
    // => In 'success' state, context.status === 'success' and data is available
    error: {},
    // => In 'error' state, context.status === 'error' and message is available
  },
});

import { createMachine, createActor } from "xstate";
 
const pageMachine = createMachine({
  // => Page state machine run on server for SSR
  id: "page",
  initial: "loading",
  context: { user: null as string | null, theme: "light" },
  states: {
    loading: {
      on: {
        LOADED: {
          target: "ready",
          actions: ({ context, event }) => {
            context.user = (event as any).user;
            // => Server sets user from session/DB during SSR
          },
        },
      },
    },
    ready: {},
  },
});
 
// --- SERVER SIDE (e.g. Next.js getServerSideProps) ---
function serverRender(sessionUser: string) {
  const serverActor = createActor(pageMachine).start();
  // => Create actor on server; does not run browser APIs
 
  serverActor.send({ type: "LOADED", user: sessionUser });
  // => Drive machine to the correct initial client state
 
  const snapshot = serverActor.getPersistedSnapshot();
  // => Serialisable snapshot; value: "ready", context.user set
 
  serverActor.stop();
  // => Clean up; no async work continues after response
 
  return JSON.stringify(snapshot);
  // => Serialised snapshot sent to client as prop or inline script
}
 
// --- CLIENT SIDE (e.g. React component) ---
function clientHydrate(serialisedSnapshot: string) {
  const snapshot = JSON.parse(serialisedSnapshot);
  // => Parse snapshot received from server
 
  const clientActor = createActor(pageMachine, { snapshot }).start();
  // => Hydrates directly into 'ready' state with correct context
  // => No loading flash; no duplicate server fetch
 
  console.log(clientActor.getSnapshot().value); // => "ready"
  console.log(clientActor.getSnapshot().context.user); // => sessionUser value
  // => Client picks up exactly where server left off
}
 
const serialised = serverRender("alice");
clientHydrate(serialised);

import { createMachine, createActor, raise, cancel } from "xstate";
 
const idleTimeoutMachine = createMachine(
  {
    // => Resets a countdown timer on each user activity; logs out after inactivity
    id: "idleTimeout",
    initial: "active",
    context: { cancelId: null as string | null },
    states: {
      active: {
        entry: {
          type: "scheduleCheck",
          // => Named action; defined in actions config below
        },
        on: {
          ACTIVITY: {
            // => User action resets the idle timer
            target: "active",
            // => Re-entering 'active' triggers entry action again
            // => Previous raise is automatically cancelled on re-entry
          },
          IDLE_CHECK: "timedOut",
          // => Fires if ACTIVITY doesn't arrive within 5 s
        },
      },
      timedOut: { type: "final" },
      // => Terminal state: session expired
    },
  },
  {
    actions: {
      scheduleCheck: raise(
        { type: "IDLE_CHECK" },
        { delay: 5000, id: "idleCheck" },
        // => id allows external cancellation via cancel("idleCheck")
        // => Sends IDLE_CHECK to self after 5 s unless cancelled
      ),
    },
  },
);
 
const actor = createActor(idleTimeoutMachine).start();
// => Entry fires scheduleCheck; IDLE_CHECK scheduled in 5 s
 
// Simulate user activity at 3 s
setTimeout(() => {
  actor.send({ type: "ACTIVITY" });
  // => Re-enters 'active'; previous scheduled IDLE_CHECK is discarded
  // => New 5 s timer starts from this point
}, 3000);
 
// Without ACTIVITY, actor transitions to timedOut at t=5 s
// With ACTIVITY at t=3 s, timedOut fires at t=8 s (3 + 5)

import { createMachine, createActor, assign, sendParent, stopChild } from "xstate";
 
// Child machine template -- each child reports errors to parent
const makeChildMachine = (name: string) =>
  createMachine({
    // => Generic child machine; reports errors via sendParent
    id: name,
    initial: "running",
    states: {
      running: {
        on: {
          FAIL: {
            // => Simulates a child failure
            actions: sendParent({ type: "CHILD_ERROR", childId: name }),
            // => Notifies parent before stopping; parent can decide recovery
          },
        },
      },
    },
  });
 
const authMachine = makeChildMachine("auth");
const dataMachine = makeChildMachine("data");
const notifMachine = makeChildMachine("notif");
 
// Root AppMachine orchestrates all children
const appMachine = createMachine({
  // => Root actor: spawns children, handles errors, shuts down gracefully
  id: "app",
  initial: "running",
  context: {
    authRef: null as any,
    dataRef: null as any,
    notifRef: null as any,
    // => ActorRef handles for all child actors
    errorLog: [] as string[],
    // => Collects error reports from children
  },
  states: {
    running: {
      entry: assign({
        authRef: ({ spawn }) => spawn(authMachine, { id: "auth" }),
        dataRef: ({ spawn }) => spawn(dataMachine, { id: "data" }),
        notifRef: ({ spawn }) => spawn(notifMachine, { id: "notif" }),
        // => All three children spawn concurrently on entry
      }),
      on: {
        CHILD_ERROR: {
          // => Error boundary: catches failures from any child
          actions: assign({
            errorLog: ({ context, event }) => [
              ...context.errorLog,
              `${(event as any).childId} failed`,
              // => Log the failing child's id; real system would alert/recover
            ],
          }),
          // => Machine stays in 'running'; other children continue operating
          // => A stricter system could transition to 'degraded' or 'error'
        },
        STOP: {
          target: "stopped",
          // => Graceful shutdown trigger
        },
      },
    },
    stopped: {
      entry: [
        stopChild("auth"),
        // => stopChild sends stop signal to named child actor
        stopChild("data"),
        // => Each child's cleanup logic runs before it halts
        stopChild("notif"),
        // => All three stopped before AppMachine enters terminal state
      ],
      type: "final",
      // => App is fully shut down; no further events processed
    },
  },
});
 
// Start the production system
const app = createActor(appMachine).start();
// => All three child actors running
 
app.send({ type: "CHILD_ERROR", childId: "data" });
// => Error boundary catches it; errorLog updated; system stays running
 
console.log(app.getSnapshot().context.errorLog);
// => ["data failed"]
 
app.send({ type: "STOP" });
// => Graceful shutdown; all children stopped before AppMachine halts
console.log(app.getSnapshot().status); // => "done"