Finite State Machine Patterns

# Finite State Machine Patterns

Build predictable, maintainable applications with finite state machines in your Google Antigravity projects. This guide covers state machine fundamentals, complex flows, and React integration patterns.

## Basic State Machine

Create a simple state machine for a toggle:

```typescript
// machines/toggleMachine.ts
import { createMachine, assign } from "xstate";

export const toggleMachine = createMachine({
  id: "toggle",
  initial: "inactive",
  context: {
    count: 0,
  },
  states: {
    inactive: {
      on: {
        TOGGLE: {
          target: "active",
          actions: assign({
            count: ({ context }) => context.count + 1,
          }),
        },
      },
    },
    active: {
      on: {
        TOGGLE: "inactive",
      },
    },
  },
});
```

## Multi-Step Form Machine

Manage complex form flows with state machines:

```typescript
// machines/checkoutMachine.ts
import { createMachine, assign } from "xstate";

interface CheckoutContext {
  shippingAddress: ShippingAddress | null;
  paymentMethod: PaymentMethod | null;
  items: CartItem[];
  error: string | null;
}

type CheckoutEvent =
  | { type: "NEXT" }
  | { type: "BACK" }
  | { type: "SET_SHIPPING"; address: ShippingAddress }
  | { type: "SET_PAYMENT"; method: PaymentMethod }
  | { type: "SUBMIT" }
  | { type: "RETRY" };

export const checkoutMachine = createMachine({
  id: "checkout",
  initial: "cart",
  context: {
    shippingAddress: null,
    paymentMethod: null,
    items: [],
    error: null,
  } as CheckoutContext,
  states: {
    cart: {
      on: {
        NEXT: {
          target: "shipping",
          guard: ({ context }) => context.items.length > 0,
        },
      },
    },
    shipping: {
      on: {
        SET_SHIPPING: {
          actions: assign({
            shippingAddress: ({ event }) => event.address,
          }),
        },
        NEXT: {
          target: "payment",
          guard: ({ context }) => context.shippingAddress !== null,
        },
        BACK: "cart",
      },
    },
    payment: {
      on: {
        SET_PAYMENT: {
          actions: assign({
            paymentMethod: ({ event }) => event.method,
          }),
        },
        NEXT: {
          target: "review",
          guard: ({ context }) => context.paymentMethod !== null,
        },
        BACK: "shipping",
      },
    },
    review: {
      on: {
        SUBMIT: "processing",
        BACK: "payment",
      },
    },
    processing: {
      invoke: {
        src: "submitOrder",
        onDone: "success",
        onError: {
          target: "error",
          actions: assign({
            error: ({ event }) => event.error.message,
          }),
        },
      },
    },
    success: {
      type: "final",
    },
    error: {
      on: {
        RETRY: "processing",
        BACK: "review",
      },
    },
  },
});
```

## React Integration

Use state machines in React components:

```typescript
// components/CheckoutFlow.tsx
"use client";

import { useMachine } from "@xstate/react";
import { checkoutMachine } from "@/machines/checkoutMachine";

export function CheckoutFlow() {
  const [state, send] = useMachine(checkoutMachine, {
    services: {
      submitOrder: async ({ context }) => {
        const response = await fetch("/api/orders", {
          method: "POST",
          body: JSON.stringify({
            items: context.items,
            shipping: context.shippingAddress,
            payment: context.paymentMethod,
          }),
        });
        if (!response.ok) throw new Error("Order failed");
        return response.json();
      },
    },
  });

  const renderStep = () => {
    switch (true) {
      case state.matches("cart"):
        return <CartStep onNext={() => send({ type: "NEXT" })} />;
      case state.matches("shipping"):
        return (
          <ShippingStep
            onSubmit={(address) => {
              send({ type: "SET_SHIPPING", address });
              send({ type: "NEXT" });
            }}
            onBack={() => send({ type: "BACK" })}
          />
        );
      case state.matches("processing"):
        return <ProcessingStep />;
      case state.matches("success"):
        return <SuccessStep />;
    }
  };

  return (
    <div className="max-w-2xl mx-auto">
      <ProgressBar currentStep={state.value as string} />
      {renderStep()}
    </div>
  );
}
```

## Authentication Machine

Manage authentication flows:

```typescript
// machines/authMachine.ts
import { createMachine, assign } from "xstate";

export const authMachine = createMachine({
  id: "auth",
  initial: "checking",
  context: {
    user: null,
    error: null,
  },
  states: {
    checking: {
      invoke: {
        src: "checkSession",
        onDone: {
          target: "authenticated",
          actions: assign({ user: ({ event }) => event.output }),
        },
        onError: "unauthenticated",
      },
    },
    unauthenticated: {
      on: {
        LOGIN: "loggingIn",
        SIGNUP: "signingUp",
      },
    },
    loggingIn: {
      invoke: {
        src: "login",
        onDone: {
          target: "authenticated",
          actions: assign({ user: ({ event }) => event.output }),
        },
        onError: {
          target: "unauthenticated",
          actions: assign({ error: ({ event }) => event.error.message }),
        },
      },
    },
    authenticated: {
      on: {
        LOGOUT: "loggingOut",
      },
    },
    loggingOut: {
      invoke: {
        src: "logout",
        onDone: {
          target: "unauthenticated",
          actions: assign({ user: null }),
        },
      },
    },
  },
});
```

## Best Practices

1. **Explicit States**: Model all possible states explicitly
2. **Guard Conditions**: Use guards to validate transitions
3. **Side Effects**: Handle async operations with invoke
4. **Context Updates**: Use assign for context mutations
5. **TypeScript**: Define context and event types for type safety
6. **Visualization**: Use XState visualizer during development