Invocar máquinas: composición jerárquica de statecharts

Hasta aquí un actor invocado envolvía una promesa, un flujo o un callback: cosas que no eran, en sí mismas, máquinas de estado. Pero XState v5 unifica el modelo hasta sus últimas consecuencias con una igualdad de una sola línea: una máquina es una lógica de actor. Esto significa que todo lo que sabes hacer con fromPromise lo puedes hacer con una máquina entera —invocarla, pasarle input, escuchar su onDone— porque a ojos del padre no hay diferencia entre invocar una promesa y invocar un statechart completo. La consecuencia es la composición jerárquica: sistemas grandes descritos como máquinas que invocan máquinas, cada una responsable de un subproblema acotado, comunicándose por un protocolo explícito de eventos y salidas. Es la misma disciplina que llevó a la arquitectura de microservicios, pero aplicada dentro de tu aplicación, y sin ninguna de las penalidades de la red.

Una máquina es un actor

La clave conceptual es que createMachine no produce algo esencialmente distinto de lo que produce fromPromise: ambos devuelven una lógica de actor, un valor que createActor puede animar y que invoke puede hospedar. Por eso puedes registrar una máquina hija en setup.actors y referenciarla desde src exactamente igual que cualquier otra lógica.

import { setup } from 'xstate'
import { maquinaPago } from './pago'

const maquinaCheckout = setup({
  actors: { pago: maquinaPago },
}).createMachine({
  id: 'checkout',
  initial: 'pagando',
  states: {
    pagando: {
      invoke: {
        id: 'pago',
        src: 'pago',
        input: ({ context }) => ({ total: context.total, moneda: context.moneda }),
        onDone: { target: 'confirmado', actions: 'guardarRecibo' },
        onError: 'rechazado',
      },
    },
    confirmado: { type: 'final' },
    rechazado: {},
  },
})

Desde checkout, la máquina de pago es una caja negra: entra un input, sale un output, y en medio ocurre toda una vida de estados —validando, autorizando, capturando— que al padre no le incumbe. Esa opacidad es exactamente lo que hace escalable la composición: el padre razona sobre el contrato, no sobre las tripas del hijo.

output: cómo una máquina devuelve un resultado

Una promesa resuelve con un valor; una máquina, para “resolver”, debe alcanzar un estado final de su nivel raíz. En ese momento evalúa su campo output, y ese valor es el que viaja al padre como event.output de la transición onDone. Definir output es, literalmente, escribir el return de la máquina vista como función.

import { setup, assign } from 'xstate'

export const maquinaPago = setup({
  types: {
    input: {} as { total: number; moneda: string },
    context: {} as { total: number; moneda: string; idTransaccion: string | null },
  },
}).createMachine({
  id: 'pago',
  context: ({ input }) => ({ ...input, idTransaccion: null }),
  initial: 'autorizando',
  states: {
    autorizando: {
      on: {
        AUTORIZADO: {
          target: 'capturado',
          actions: assign({ idTransaccion: ({ event }) => event.id }),
        },
        DENEGADO: 'fallido',
      },
    },
    capturado: { type: 'final' },
    fallido: { type: 'final' },
  },
  output: ({ context }) => ({ idTransaccion: context.idTransaccion }),
})

Observa cómo el context inicial del hijo se construye a partir de su input: es el patrón canónico para sembrar una máquina hija con los datos que el padre le entrega. Y nota que output se evalúa al llegar a cualquier final de nivel raíz, sea el de éxito o el de fallo; si necesitas distinguirlos, codifícalo en el propio output o usa estados finales con datos distintos.

Comunicación bidireccional: sendTo, sendParent y onSnapshot

La invocación no es solo entrada y salida: mientras ambos viven, padre e hijo pueden hablar. El padre dirige eventos al hijo con sendTo, apuntando al id del actor invocado. El hijo devuelve eventos al padre con la acción sendParent. Y si el padre quiere observar el estado interno del hijo sin esperar a que termine, declara onSnapshot, que se dispara con cada cambio de instantánea del hijo.

import { sendTo, assign } from 'xstate'

pagando: {
  invoke: {
    id: 'pago',
    src: 'pago',
    input: ({ context }) => ({ total: context.total, moneda: context.moneda }),
    onSnapshot: {
      actions: assign({
        estadoPago: ({ event }) => event.snapshot.value,
      }),
    },
    onDone: 'confirmado',
  },
  on: {
    CANCELAR_PAGO: { actions: sendTo('pago', { type: 'CANCELAR' }) },
  },
}

flowchart TD
P[padre checkout] -->|input y sendTo| H[hijo pago]
H -->|output en onDone| P
H -->|sendParent y onSnapshot| P
subgraph hijo
  H --> A[autorizando]
  A --> C[capturado final]
  A --> F[fallido final]
end
style P fill:#cba6f7,color:#11111b
style H fill:#89b4fa,color:#11111b

Trazar bien la frontera padre-hijo

Componer máquinas no es gratis: cada frontera es un contrato que hay que diseñar. Una buena descomposición asigna al hijo un subproblema con un principio y un final nítidos —un asistente de varios pasos, un flujo de pago, una subida de archivo— cuyo resultado el padre necesita pero cuyo detalle interno no. Una mala descomposición parte una lógica cohesionada en dos máquinas que no paran de mandarse eventos para coordinarse: síntoma de que ambas eran, en realidad, una sola.