onDone y output: reaccionar al final y devolver un resultado

Marcar un estado como terminal declara que algo acabó, pero por sí solo no comunica nada hacia arriba ni entrega ningún resultado; es una afirmación sin destinatario. Los dos mecanismos que completan la figura son complementarios y se usan casi siempre juntos. El primero es onDone, una transición que no responde a ningún evento que tú envíes sino a un evento sintético que el propio motor emite en el instante en que una región alcanza su final o un actor invocado se detiene con éxito; es el canal por el que un subproceso avisa a su contenedor. El segundo es output, el valor que ese final produce y que viaja dentro del evento sintético hasta quien escucha. Juntos convierten la relación entre un proceso y su subproceso en algo que ya sabes leer: una llamada que devuelve. Y una vez tienes llamadas que devuelven, tienes composición, que es lo único que hace falta para construir sistemas grandes sin que se conviertan en una máquina única e ilegible.

El evento que no puedes enviar

onDone no aparece bajo on sino como clave propia del estado, y esa colocación es una pista deliberada: no es un evento del dominio. El motor emite un evento sintético cuando una región termina, y su forma depende de quién terminó.

La distinción entre done.state y done.invoke importa porque son dos formas distintas de contener un subproceso. La primera es contención estructural: el subproceso es una parte del árbol de estados, corre en el mismo actor y no tiene identidad propia. La segunda es contención por delegación: el subproceso es otro actor con su ciclo de vida, su contexto y su cola de eventos. El onDone uniforma ambas ante quien escucha —el padre reacciona igual— y esa uniformidad es lo que te permite empezar con un compuesto y extraerlo más tarde a una máquina invocada sin reescribir la lógica del padre.

output: el valor de retorno

Una máquina que termina puede devolver algo, y ese algo se declara con output. Hay dos lugares donde aparece la propiedad y confundirlos es la fuente habitual de resultados que llegan vacíos.

import { createMachine } from 'xstate'

const checkout = createMachine({
  id: 'checkout',
  initial: 'carrito',
  context: { total: 0, referencia: '' },
  states: {
    carrito: { on: { PAGAR: 'cobrando' } },
    cobrando: {
      on: { COBRADO: 'exito', RECHAZADO: 'rechazo' },
    },
    exito: {
      type: 'final',
      output: ({ context }) => ({ ok: true, referencia: context.referencia }),
    },
    rechazo: {
      type: 'final',
      output: { ok: false, motivo: 'rechazado por el emisor' },
    },
  },
  output: ({ context }) => ({ referencia: context.referencia }),
})

El output de un estado final describe qué produce ese desenlace concreto y viaja dentro del evento sintético; es lo que permite que dos finales distintos entreguen resultados distintos. El output de la máquina raíz describe qué devuelve el actor entero, y se evalúa cuando la máquina alcanza un final de nivel superior; recibe el contexto y el evento que provocó la terminación, de modo que puede reenviar el resultado del final concreto o calcular uno propio. Ambos aceptan una función o un valor estático, y ambos se resuelven una sola vez, en el momento exacto de terminar.

Del lado del que escucha, el resultado se lee en el evento. Una transición onDone puede llevar acciones, y esas acciones reciben el evento sintético con el resultado dentro, típicamente para guardarlo en el contexto del padre antes de continuar.

import { assign, createMachine } from 'xstate'

const tienda = createMachine({
  id: 'tienda',
  initial: 'comprando',
  context: { ultimoPedido: null },
  states: {
    comprando: {
      initial: 'checkout',
      states: {
        checkout: { on: { FIN: 'hecho' } },
        hecho: { type: 'final', output: ({ context }) => context },
      },
      onDone: {
        target: 'resumen',
        actions: assign({ ultimoPedido: ({ event }) => event.output }),
      },
    },
    resumen: {},
  },
})

Del final al await

Un actor con final es, sin metáfora de por medio, un cómputo asíncrono con resultado. La equivalencia es tan exacta que la librería la expone directamente: toPromise devuelve una promesa que se resuelve con el output en cuanto el actor alcanza done.

import { createActor, toPromise } from 'xstate'

const actor = createActor(checkout).start()
const resultado = await toPromise(actor)
// resultado es lo que devolvio el output de la raiz
console.log(resultado.referencia)

La consecuencia práctica es que una máquina con final se integra en código asíncrono corriente sin ceremonia: puedes esperarla, componerla con otras promesas o pasarla a cualquier utilidad que acepte una tarea. La consecuencia conceptual es más interesante: una máquina que nunca termina no puede tener promesa asociada, porque una promesa sin resolución posible no significaría nada. Terminar no es un detalle del ciclo de vida, es el requisito para que la máquina tenga un tipo de retorno.

flowchart TD
A[hijo alcanza estado final] --> B[motor calcula el output del final]
B --> C[emite evento sintetico done]
C --> D[padre dispara su onDone]
D --> E[acciones leen event output]
E --> F[padre transiciona y continua]
style A fill:#f9e2af,color:#11111b
style C fill:#89dceb,color:#11111b
style F fill:#a6e3a1,color:#11111b