onDone, onError e input: el diálogo con el actor

Un actor invocado no es un cálculo que ocurre en el vacío: es una conversación con la máquina que lo hospeda. Esa conversación tiene una entrada y dos salidas. La entrada es input, el argumento con el que el actor nace, extraído del contexto en el momento exacto de su creación. Las salidas son onDone y onError: dos transiciones que la máquina toma según el actor culmine con éxito o se rompa. La clave que se suele pasar por alto es que ni el resultado ni el error llegan por un canal mágico: llegan como eventos sintéticos que XState fabrica y encola, con una forma y un nombre precisos. Tratar la finalización de un actor como lo que realmente es —un evento más en la máquina, indistinguible en su mecánica de un clic del usuario— es lo que permite razonar sobre el asincronismo con el mismo rigor que sobre cualquier otra transición.

El resultado es un evento, no un retorno

En programación imperativa, una función asíncrona devuelve un valor y tú lo recibes en el punto de la llamada. En una máquina de estado no hay punto de llamada: hay estados y transiciones. Por eso XState no te “devuelve” el resultado de un actor; lo convierte en un evento y lo inyecta en la máquina. Cuando un fromPromise resuelve, el runtime encola un evento cuyo tipo es xstate.done.actor.<id> y cuya carga es el valor resuelto. onDone no es más que azúcar para escribir una transición que escucha ese evento.

// esto:
cargando: {
  invoke: { id: 'carga', src: 'cargarUsuario', onDone: 'exito' }
}
// es equivalente, en esencia, a esto:
cargando: {
  invoke: { id: 'carga', src: 'cargarUsuario' },
  on: { 'xstate.done.actor.carga': 'exito' }
}

La consecuencia práctica es profunda: la finalización de un actor participa del mismo motor de transiciones que todo lo demás. Puede tener guardas, puede tener acciones, puede competir con otras transiciones del estado. No es un mecanismo aparte; es un evento con un nombre reservado.

La forma de los eventos sintéticos

Saber qué contiene cada evento es lo que te permite extraer el resultado sin adivinar. El evento de éxito lleva el valor en output; el de error, la causa en error. XState v5 tipa ambos si declaraste bien los actors en setup, de modo que event.output tiene el tipo del valor resuelto por la promesa.

import { assign } from 'xstate'

cargando: {
  invoke: {
    id: 'carga',
    src: 'cargarUsuario',
    input: ({ context }) => ({ id: context.userId }),
    onDone: {
      target: 'exito',
      actions: assign({ usuario: ({ event }) => event.output }),
    },
    onError: {
      target: 'fallo',
      actions: assign({ error: ({ event }) => event.error }),
    },
  },
}

Un apunte de tipos que ahorra sorpresas: event.error es de tipo unknown, porque en JavaScript se puede lanzar cualquier valor y no solo un Error. Antes de leer un .message conviene estrechar el tipo o normalizar el error en la propia acción. event.output, en cambio, sí llega tipado con el valor que tu lógica promete devolver, siempre que registraras el actor en setup.actors con sus tipos declarados.

sequenceDiagram
participant M as maquina
participant A as actor invocado
M->>A: entra en cargando y crea el actor con input
A-->>A: ejecuta la promesa
alt resuelve
  A->>M: evento done con output
  M->>M: onError no aplica y transiciona a exito
else rechaza
  A->>M: evento error con error
  M->>M: transiciona a fallo
end

input: el argumento congelado en la creación

Si onDone y onError son la salida, input es la entrada. Es una función que recibe el contexto y el evento que provocó la transición hacia el estado, y devuelve el argumento con el que el actor nace. El matiz decisivo es temporal: input se evalúa UNA sola vez, en el instante en que el actor se crea —es decir, al entrar en el estado—. No es reactivo. Si el contexto cambia después, el actor ya nació con el valor que había en ese momento y no se entera de la mutación.

input: ({ context, event }) => ({
  id: context.userId,
  intento: context.intentos + 1,
  disparadoPor: event.type,
})

Esta instantaneidad es una virtud, no una limitación: garantiza que el actor opera sobre una foto coherente del estado, inmune a mutaciones concurrentes durante su ejecución. Si necesitas que el actor reaccione a cambios posteriores, ese es justamente el caso que input no cubre: entonces quieres enviarle eventos con sendTo, no recalcular input. Confundir ambos mecanismos —esperar que input se reevalúe— es un error clásico de quien llega desde modelos reactivos.

Diseñar el flujo de resultado en el grafo

Como onDone y onError son transiciones plenas, puedes tejer con ellas flujos ricos que serían enrevesados con promesas encadenadas. Una guarda en onDone bifurca según el contenido del resultado; una transición de error hacia un estado que reintenta con retroceso exponencial modela la resiliencia de forma declarativa; un resultado puede a su vez desencadenar la invocación del siguiente actor, componiendo una secuencia asíncrona como una cadena de estados.

onDone: [
  { target: 'vacio', guard: ({ event }) => event.output.length === 0 },
  { target: 'conDatos', actions: assign({ items: ({ event }) => event.output }) },
],

Ese fragmento decide el destino según el resultado: si la lista vino vacía va a un estado, si trajo datos va a otro. La lógica de ramificación que en código imperativo serían condicionales dispersos tras el await aquí es estructura visible del grafo, verificable de un vistazo.

La composición secuencial surge con la misma naturalidad. Si el resultado de un actor es la entrada del siguiente, encadenas estados: el onDone del primero guarda su output en el contexto y transiciona al estado que invoca al segundo, cuyo input lee ese contexto. Lo que en promesas sería un then tras otro se convierte en una ruta de estados donde cada paso es inspeccionable y cada fallo intermedio tiene su propio onError y su propio destino.

validando: {
  invoke: {
    src: 'validar',
    input: ({ context }) => ({ datos: context.borrador }),
    onDone: {
      target: 'guardando',
      actions: assign({ validado: ({ event }) => event.output }),
    },
    onError: 'invalido',
  },
},
guardando: {
  invoke: {
    src: 'guardar',
    input: ({ context }) => ({ registro: context.validado }),
    onDone: 'guardado',
    onError: 'errorAlGuardar',
  },
},