Componer con final y output: el patrón de subflujo

Todo lo anterior converge en un único patrón, y es el que sostiene cualquier sistema de estados grande que se mantenga legible. Una máquina declara qué necesita para empezar y qué produce al terminar; otra la invoca desde un estado concreto, le entrega lo primero y espera lo segundo. Eso es un subflujo, y la palabra importante es contrato: en cuanto existen input y output, la máquina hija tiene una firma, y una firma es lo que permite usarla sin conocer su interior, probarla por separado, sustituirla por otra equivalente y razonar sobre el padre sin abrir al hijo. Sin ese contrato tendrías dos máquinas acopladas que se manosean el contexto mutuamente y que hay que entender a la vez; con él tienes composición del mismo tipo que llevas usando desde que aprendiste a escribir funciones. La diferencia con una función es que el subflujo tarda, puede cancelarse a mitad y sigue vivo mientras el padre también lo está, y esas tres diferencias son exactamente las que hacen falta para modelar procesos reales.

El subflujo y su contrato

Una máquina invocable se escribe igual que cualquier otra, con dos añadidos que la convierten en unidad reutilizable: declara el tipo de su entrada y produce un resultado al terminar. En XState v5 esto se expresa con setup para los tipos y con input en el contexto inicial.

import { setup, assign } from 'xstate'

const verificacion = setup({
  types: {
    input: {} as { email: string },
    context: {} as { email: string; intentos: number },
    output: {} as { verificado: boolean; email: string },
  },
}).createMachine({
  id: 'verificacion',
  context: ({ input }) => ({ email: input.email, intentos: 0 }),
  initial: 'esperandoCodigo',
  states: {
    esperandoCodigo: {
      on: {
        CODIGO_OK: 'verificado',
        CODIGO_MAL: {
          target: 'esperandoCodigo',
          actions: assign({ intentos: ({ context }) => context.intentos + 1 }),
        },
        RENDIRSE: 'abandonado',
      },
    },
    verificado: {
      type: 'final',
      output: ({ context }) => ({ verificado: true, email: context.email }),
    },
    abandonado: {
      type: 'final',
      output: ({ context }) => ({ verificado: false, email: context.email }),
    },
  },
})

Léelo como una firma y la analogía se vuelve literal: recibe un correo, devuelve si quedó verificado. Todo lo de en medio —cuántos intentos, qué eventos, qué estados intermedios— es interior privado del subflujo, y el padre no debe conocerlo ni depender de ello. Esa privacidad no es una recomendación de estilo, es la propiedad que hace que el subflujo se pueda modificar sin auditar a quien lo usa.

Invocar, esperar y recoger

El padre invoca el subflujo desde el estado donde tiene sentido esperarlo. La invocación declara la fuente, la entrada calculada a partir del contexto del padre y las dos reacciones posibles.

import { setup, assign } from 'xstate'

const alta = setup({
  actors: { verificacion },
}).createMachine({
  id: 'alta',
  initial: 'datos',
  context: { email: '', verificado: false },
  states: {
    datos: {
      on: { ENVIAR: 'verificando' },
    },
    verificando: {
      invoke: {
        src: 'verificacion',
        input: ({ context }) => ({ email: context.email }),
        onDone: {
          target: 'resultado',
          actions: assign({ verificado: ({ event }) => event.output.verificado }),
        },
        onError: 'errorTecnico',
      },
      on: { CANCELAR: 'datos' },
    },
    resultado: {},
    errorTecnico: {},
  },
})

Fíjate en la asimetría de las dos salidas. onDone responde a que el subflujo terminó, sea cual sea su desenlace: verificado o abandonado son ambos finales legítimos y ambos llegan por aquí, discriminados por el output. onError responde a que el subflujo falló, es decir, a que algo se rompió de una manera que el modelo no contemplaba. Confundirlos lleva a modelar como error lo que era un desenlace previsto, y a partir de ahí el padre trata como avería lo que el producto considera normal.

flowchart TD
A[padre en estado verificando] -->|input desde su contexto| B[actor hijo arranca]
B --> C{desenlace}
C -->|final verificado| D[evento done con output]
C -->|final abandonado| D
C -->|excepcion| E[evento error]
D --> F[padre asigna y transiciona]
E --> G[padre va a error tecnico]
style B fill:#89dceb,color:#11111b
style D fill:#a6e3a1,color:#11111b
style E fill:#f38ba8,color:#11111b

Cuándo extraer y cuándo no

Todo compuesto puede convertirse en subflujo, y esa facilidad es un peligro. La extracción tiene un coste real —una frontera más que cruzar, un contrato que mantener, un actor más que observar al depurar— y solo se paga cuando algo lo justifica. Estas señales lo justifican; su ausencia recomienda dejar el compuesto donde está.

En contra pesan dos situaciones, y la segunda es la que más se equivoca. La primera es el subflujo diminuto: dos estados y una transición no merecen una frontera, y extraerlos añade indirección sin ganar nada. La segunda es la relación que necesita conversación continua: si el padre tiene que enviarle eventos al hijo constantemente y el hijo tiene que informar al padre mientras trabaja, la forma correcta no es la invocación con onDone sino la comunicación entre actores, con envíos explícitos en ambos sentidos. La pista que las separa es cuántas veces se cruza la frontera: si es una vez al empezar y otra al acabar, es un subflujo; si es continuamente, son dos actores conversando y modelarlo como llamada con retorno te obligará a deformar el diseño para que quepa.