Estados finales y onDone: cuándo termina una máquina

Un interruptor no termina nunca: alterna indefinidamente. Pero muchos procesos sí tienen un final —un pago se completa, un asistente de varios pasos concluye, una descarga acaba—. La teoría de autómatas siempre lo contempló: la quíntupla incluye un conjunto de estados finales, los estados en los que la máquina acepta y se detiene. XState lo expresa marcando un estado con type: 'final'. Cuando la máquina raíz alcanza un estado final, su actor se detiene: no procesará más eventos, su ciclo de vida ha concluido. Y cuando el que termina es un estado compuesto, su padre puede reaccionar con onDone. Esa capacidad de terminar y de avisar de que se ha terminado es la que convierte una máquina en una pieza componible dentro de otra mayor.

El estado final: F en la quíntupla

Un estado type: 'final' es un estado sin salida: no declara on porque, una vez dentro, no hay a dónde ir. Es la letra F de la quíntupla —el conjunto de estados de aceptación— hecha configuración. Cuando el estado final está en el nivel raíz de la máquina, alcanzarlo significa que el autómata completo ha terminado.

import { createMachine } from 'xstate'

const pago = createMachine({
  id: 'pago',
  initial: 'formulario',
  states: {
    formulario: {
      on: { ENVIAR: 'procesando' },
    },
    procesando: {
      on: { OK: 'completado', FALLO: 'formulario' },
    },
    completado: {
      type: 'final',
    },
  },
})

Cuando el actor de esta máquina llega a completado, deja de estar activo. Enviarle más eventos no produce nada: la máquina ha aceptado su entrada y se ha detenido. Modelar el final de forma explícita es tan valioso como modelar los estados intermedios, porque distingue “esperando” de “terminado”, dos situaciones que las banderas booleanas suelen confundir en un mismo hecho = true. En el diagrama, un estado final se dibuja distinto —con doble contorno—, de modo que la terminación salta a la vista tanto en el código como en su representación visual.

stateDiagram-v2
[*] --> formulario
formulario --> procesando: ENVIAR
procesando --> completado: OK
procesando --> formulario: FALLO
completado --> [*]

Hay una lectura teórica que ilumina el concepto. En la teoría de autómatas, los estados finales son los estados de aceptación: la máquina lee una secuencia de símbolos y se dice que la ACEPTA si termina en uno de ellos. Traducido a XState, la secuencia de eventos que llevó al actor a un estado final es una secuencia aceptada —una historia válida y completa del proceso—. Un pago que termina en completado es una secuencia de eventos que el modelo reconoce como un pago bien formado, y esa es, literalmente, la noción de aceptación de la que hablan los cursos de lenguajes formales.

Esta lectura explica también por qué un estado final no tiene on: aceptar es detenerse. Si un estado de aceptación pudiera seguir transicionando, no marcaría el final de nada; sería un estado intermedio más. La ausencia de salidas no es una limitación que soportamos, es la definición misma de terminar.

onDone: reaccionar a que un subproceso termine

El estado final cobra todo su poder dentro de un estado compuesto. Cuando la submáquina de un estado compuesto alcanza SU estado final, ese estado compuesto se considera “hecho”, y eso dispara una transición especial declarada en el padre: onDone. Es el mecanismo por el que un subproceso completo le comunica a su contenedor que ha concluido, sin que el contenedor tenga que vigilar los detalles internos.

const flujo = createMachine({
  id: 'flujo',
  initial: 'trabajando',
  states: {
    trabajando: {
      initial: 'paso1',
      states: {
        paso1: { on: { SIGUIENTE: 'paso2' } },
        paso2: { on: { SIGUIENTE: 'fin' } },
        fin: { type: 'final' },
      },
      onDone: 'terminado',
    },
    terminado: {
      type: 'final',
    },
  },
})

Cuando el subestado fin se alcanza, el estado compuesto trabajando termina y su onDone transiciona a terminado. El padre no escucha ningún evento externo: reacciona a la finalización de su hijo. Esto es composición estructural —una máquina que espera a que otra, contenida en ella, acabe—, y es la semilla del patrón de máquinas invocadas que verás más adelante, donde el hijo es una máquina entera ejecutándose como actor propio y su onDone entrega, además, el resultado que produjo.

El actor terminado y su output

Un estado final puede producir un valor de salida. La máquina declara output —una función que recibe el contexto y devuelve el resultado— y ese valor queda disponible en el snapshot cuando el actor termina. El status del snapshot es la señal canónica del ciclo de vida: vale active mientras corre y pasa a done al alcanzar un final de raíz.

import { createActor, createMachine } from 'xstate'

const pedido = createMachine({
  id: 'pedido',
  initial: 'abierto',
  context: { total: 42 },
  states: {
    abierto: { on: { CONFIRMAR: 'cerrado' } },
    cerrado: { type: 'final' },
  },
  output: ({ context }) => ({ total: context.total }),
})

const actor = createActor(pedido).start()
actor.send({ type: 'CONFIRMAR' })

const snapshot = actor.getSnapshot()
snapshot.status   // 'done'
snapshot.output   // { total: 42 }

La distinción entre active y done no es cosmética: es la diferencia entre una máquina que aún puede cambiar y una cuyo comportamiento ha quedado sellado. Un actor done es inmutable de hecho —ya no responde a eventos— y su output es su valor de retorno, exactamente como una función que ha retornado. Modelar el final permite tratar toda una máquina como un cómputo con resultado, no solo como un bucle reactivo, y ese resultado es lo que la máquina de arriba recibirá cuando la invoque.

De hecho, un actor con final puede tratarse como una promesa. En v5, toPromise(actor) devuelve una promesa que se resuelve con el output en cuanto el actor llega a done. La equivalencia es exacta —una máquina con estado final es un cómputo asíncrono con resultado—, y por eso puedes esperar sobre una máquina con await igual que sobre cualquier otra tarea, integrándola en código asíncrono sin ceremonia. Una máquina que nunca termina no tiene promesa asociada, porque una promesa sin resolución posible no significaría nada.