La API setup: declarar antes de construir

La v4 de XState te dejaba escribir la máquina primero y explicar después qué significaban los nombres que habías usado dentro de ella. Esa libertad tenía un precio, y se pagaba entero en el sistema de tipos: cuando createMachine recibía la configuración, TypeScript aún no sabía qué era guardarUsuario, ni qué forma tenía el context, ni qué eventos podían llegar; la única salida era un generador de código externo —el recordado tsTypes— que reconstruía a posteriori lo que el compilador no había podido inferir a tiempo. La v5 invierte el orden, y con ello elimina la maquinaria entera: setup es una fase de declaración que ocurre ANTES de que exista la máquina, y su valor de retorno no es configuración sino un constructor especializado que ya conoce los tipos y la lista de nombres legales. Leer este cambio como una API nueva es quedarse en la superficie; es un cambio en el orden de las fases, y de ese orden se deriva casi todo lo demás del nivel.

La deuda de la v4: construir antes de declarar

En la v4, createMachine aceptaba dos argumentos: la configuración y, opcionalmente, las implementaciones. El problema es de orden de evaluación conceptual: el primer argumento menciona nombres —asignaUsuario, esValido, cargarPerfil— cuyo significado solo aparece en el segundo. TypeScript infiere de izquierda a derecha, así que al comprobar el primer argumento no dispone todavía del contrato que le daría sentido.

// XState v4: la maquina se escribe antes de que existan sus nombres
const maquina = createMachine(
  {
    schema: {
      context: {} as { usuario: string | null },
      events: {} as { type: 'ENTRAR'; nombre: string },
    },
    tsTypes: {} as import('./maquina.typegen').Typegen0, // generado por una CLI
    initial: 'anonimo',
    states: {
      anonimo: { on: { ENTRAR: { target: 'dentro', actions: 'asignaUsuario' } } },
    },
  },
  { actions: { asignaUsuario: assign({ usuario: (_, e) => e.nombre }) } },
)

Aquel tsTypes no era un capricho: era una prótesis. Una CLI leía la máquina, deducía qué nombres existían y qué evento alcanzaba cada action, y escribía un fichero auxiliar que se importaba de vuelta para completar la inferencia. Funcionaba, pero introducía un paso de compilación externo, se desincronizaba en cuanto editabas sin regenerar, y hacía que el editor mintiera durante los segundos que tardaba en ponerse al día.

La v5 no mejora la prótesis: retira la causa. Si las declaraciones van primero, el compilador tiene toda la información cuando la necesita, y la inferencia ocurre sin ayuda externa.

import { setup, assign } from 'xstate'

// XState v5: primero se declara el vocabulario, despues se escribe la maquina
const maquina = setup({
  types: {
    context: {} as { usuario: string | null },
    events: {} as { type: 'ENTRAR'; nombre: string },
  },
  actions: {
    asignaUsuario: assign({ usuario: ({ event }) => event.nombre }),
  },
}).createMachine({
  context: { usuario: null },
  initial: 'anonimo',
  states: {
    anonimo: { on: { ENTRAR: { target: 'dentro', actions: 'asignaUsuario' } } },
    dentro: {},
  },
})

Anatomía de setup: cinco casilleros

setup acepta un objeto con cinco claves, y conviene entender que no son cinco listas equivalentes: una declara tipos y las otras cuatro declaran implementaciones asociadas a nombres.

El quinto casillero es delays, el menos vistoso y el que más ahorra: asigna nombres a duraciones para que after no quede sembrado de números mágicos, y permite que esas duraciones se calculen a partir del context. Es además, como el resto de nombres, sustituible en un test, lo que convierte un temporizador de treinta segundos en un temporizador de cero durante las pruebas.

const conRetardo = setup({
  types: { context: {} as { intentos: number }, events: {} as { type: 'REINTENTAR' } },
  delays: {
    // backoff exponencial calculado desde el context
    esperaReintento: ({ context }) => Math.min(1000 * 2 ** context.intentos, 30_000),
  },
  guards: {
    quedanIntentos: ({ context }) => context.intentos < 5,
  },
}).createMachine({
  context: { intentos: 0 },
  initial: 'esperando',
  states: {
    esperando: {
      after: { esperaReintento: { target: 'reintentando', guard: 'quedanIntentos' } },
    },
    reintentando: {},
  },
})

El constructor especializado

Lo que setup devuelve no es un objeto de configuración: es una fábrica cerrada sobre lo que acabas de declarar. Ese objeto expone createMachine, y ese createMachine es distinto del importado de xstate, porque su tipo ya está parametrizado con tu context, tus eventos y la unión exacta de nombres que declaraste. De ahí salen las tres garantías que definen la experiencia de la v5.

flowchart LR
T[types: forma de context y eventos] --> S[setup]
I[implementaciones: actions guards actors delays] --> S
S --> F[fabrica especializada]
F --> M[createMachine con vocabulario cerrado]
M --> R[maquina tipada de punta a punta]
style S fill:#cba6f7,color:#11111b
style F fill:#89b4fa,color:#11111b
style R fill:#a6e3a1,color:#11111b

La primera garantía es el autocompletado: al escribir actions: dentro de una transición, el editor ofrece exactamente los nombres declarados. La segunda es el error temprano: un nombre no declarado ya no es una cadena cualquiera, sino un valor fuera de la unión, y el compilador lo rechaza en el sitio donde lo escribiste. La tercera es la coherencia: el context que declaraste es el mismo que ves en cada assign, en cada guard, en cada snapshot y en cada useSelector, sin un solo casting por el camino.