invoke: un actor atado a la vida de un estado

Una máquina de estado describe con precisión situaciones discretas y las transiciones válidas entre ellas. Pero una aplicación real no vive solo en estados: vive en el tiempo, lanzando peticiones que tardan, abriendo sockets que emiten, arrancando temporizadores que laten. El instinto ingenuo es colocar esos efectos en acciones de entrada y confiar en acordarse de cancelarlos al salir. Ese olvido es la fuente inagotable de fugas: peticiones que resuelven sobre un estado que ya no existe, sockets que siguen abiertos, timers que disparan en el vacío. La tesis de invoke es quirúrgica: un efecto que pertenece a un estado debe nacer al entrar en él y morir al salir, y de esa contabilidad se encarga la máquina, no tú. Al hacerlo, invoke convierte lo asíncrono en un actor: una unidad con identidad, buzón y ciclo de vida, subordinada al estado que la invoca.

El efecto que pertenece a un estado

Piensa en un estado llamado cargando. Su nombre no describe una configuración estática: describe algo que está ocurriendo. Mientras la máquina permanece en cargando, hay una petición en vuelo; cuando la petición termina, la máquina ya no debería estar en cargando. El estado y el efecto son el mismo hecho visto desde dos ángulos —uno declarativo, otro operacional—. invoke hace literal esa identidad: declara que, por definición, estar en cargando ES tener corriendo cierto actor.

Esta atadura resuelve de raíz el problema del efecto huérfano. En el modelo de acciones sueltas, el efecto y el estado tienen ciclos de vida independientes y hay que sincronizarlos a mano. Con invoke, el ciclo de vida del efecto ES el del estado: no hay nada que sincronizar porque no hay dos cosas, hay una. La cancelación deja de ser una tarea que puedes olvidar y pasa a ser una consecuencia estructural de salir del estado.

stateDiagram-v2
[*] --> inactivo
inactivo --> cargando : FETCH
cargando --> exito : onDone
cargando --> fallo : onError
fallo --> cargando : REINTENTAR
cargando : entry nace el actor invocado
cargando : exit muere el actor invocado

Anatomía de un invoke

Un invoke es un objeto declarado dentro de un estado. En XState v5 lo habitual es registrar la lógica del actor en setup bajo actors y referenciarla por nombre desde src, lo que mantiene la máquina serializable y tipada.

import { setup, fromPromise, assign } from 'xstate'

const maquina = setup({
  types: {
    context: {} as { userId: string; usuario: Usuario | null; error: unknown },
    events: {} as { type: 'FETCH'; userId: string } | { type: 'REINTENTAR' },
  },
  actors: {
    cargarUsuario: fromPromise(
      async ({ input }: { input: { userId: string } }) => {
        const res = await fetch(`/api/users/${input.userId}`)
        if (!res.ok) throw new Error(`HTTP ${res.status}`)
        return (await res.json()) as Usuario
      },
    ),
  },
}).createMachine({
  id: 'perfil',
  initial: 'inactivo',
  context: { userId: '', usuario: null, error: null },
  states: {
    inactivo: {
      on: {
        FETCH: {
          target: 'cargando',
          actions: assign({ userId: ({ event }) => event.userId }),
        },
      },
    },
    cargando: {
      invoke: {
        id: 'cargarUsuario',
        src: 'cargarUsuario',
        input: ({ context }) => ({ userId: context.userId }),
        onDone: {
          target: 'exito',
          actions: assign({ usuario: ({ event }) => event.output }),
        },
        onError: {
          target: 'fallo',
          actions: assign({ error: ({ event }) => event.error }),
        },
      },
    },
    exito: { type: 'final' },
    fallo: { on: { REINTENTAR: 'cargando' } },
  },
})

Cada campo tiene un papel exacto. src nombra la lógica del actor a ejecutar; id le da una identidad estable dentro de la máquina, indispensable para dirigirle eventos o leer su instantánea; input calcula el argumento con el que nace el actor a partir del contexto y del evento; onDone y onError son transiciones que se disparan cuando el actor termina bien o falla. Sin id, XState deriva uno del src, pero declararlo explícitamente es la disciplina profesional.

El actor invocado es un ciudadano del sistema

Un actor invocado no es un callback anónimo: es una entidad con identidad propia dentro del sistema de actores de la máquina. Tiene su propia instantánea consultable, puede recibir eventos que le dirijas con sendTo y, según su lógica, puede devolverte eventos. Por eso hablamos de actor y no de mera promesa: la promesa es solo una de las lógicas posibles con las que puede animarse.

Referenciar al actor por su id habilita el diálogo en vivo. Desde una transición del padre puedes dirigirle un evento con sendTo, y desde una acción puedes leer su instantánea con getSnapshot para decidir según su progreso. Esa es la diferencia tangible entre un actor invocado y una promesa lanzada al vuelo: no es una caja cerrada que solo entrega un valor al terminar, sino un interlocutor con el que se conversa mientras vive.

import { sendTo } from 'xstate'

cargando: {
  invoke: {
    id: 'carga',
    src: 'cargarUsuario',
    input: ({ context }) => ({ userId: context.userId }),
  },
  on: {
    ABORTAR: { actions: sendTo('carga', { type: 'CANCELAR' }) },
  },
}

invoke frente a spawn

XState ofrece dos maneras de crear actores hijos, y la diferencia es precisamente a qué atan el ciclo de vida. invoke ata el actor a un estado: mientras el estado está activo el actor vive, y al salir muere. spawn (a través de la acción spawnChild o del helper spawn dentro de assign) ata el actor al contexto: el actor persiste a través de transiciones y solo se detiene cuando tú lo ordenas con stopChild o cuando la máquina entera para.

La regla práctica se deduce de la pregunta “¿cuánto debe vivir este efecto?”. Si su vida coincide con la de un estado —una petición que solo tiene sentido mientras cargas—, usa invoke. Si debe sobrevivir a varios estados —un socket compartido, una lista dinámica de tareas de fondo—, usa spawn. Volveremos a esta dicotomía con detalle al estudiar el ciclo de vida, pero conviene grabarla ya: invoke es declarativo y ligado al estado; spawn es imperativo y ligado al actor.

flowchart LR
subgraph invoke
  direction LR
  E1[entra al estado] --> V1[actor vive] --> S1[sale del estado] --> M1[actor muere]
end
subgraph spawn
  direction LR
  E2[un evento lo crea] --> V2[vive cruzando estados] --> S2[stopChild lo detiene]
end
style V1 fill:#a6e3a1,color:#11111b
style V2 fill:#fab387,color:#11111b