Implementaciones nombradas: actions y guards con nombre propio

Una acción escrita directamente dentro de una transición funciona perfectamente y es, en casi todos los sentidos que importan, invisible. No aparece con etiqueta en el diagrama, no se puede sustituir por un doble en un test, no se puede reutilizar en la transición de al lado y no figura en ninguna lista que alguien pueda leer para saber qué efectos provoca esta máquina. Darle un nombre y declararla en setup cambia su categoría ontológica: deja de ser código incrustado y pasa a ser un símbolo del vocabulario, con todo lo que un símbolo permite —referenciarlo, contarlo, dibujarlo, reemplazarlo—. Esta lección desarrolla ese acto de nombrar hasta sus últimas consecuencias, incluida la más elegante: cuando una implementación recibe por parámetro exactamente lo que necesita, deja de importarle qué evento la disparó, y la incomodidad que dejamos abierta en la lección anterior se disuelve sin engañar al compilador ni una sola vez.

Qué compra un nombre

Las implementaciones de setup reciben siempre dos argumentos. El primero es un objeto con context, event y self; el segundo, los parámetros que la transición decida pasarle. Los guards tienen la misma firma y devuelven un booleano; las actions no devuelven nada y son el único sitio donde se permiten efectos.

Parámetros: la implementación deja de mirar el evento

Recuerda la asimetría de la lección anterior: una implementación nombrada recibe la unión completa de eventos, porque setup se evalúa antes de que la máquina exista. La salida no es comprobar event.type dentro de cada action, y mucho menos silenciar el tipo: es que la action no necesite el evento. La transición, que sí conoce su evento, calcula los parámetros y se los entrega ya extraídos.

import { setup, assign, and, not } from 'xstate'

type Articulo = { id: string; precio: number }

const carrito = setup({
  types: {
    context: {} as { articulos: Articulo[]; limite: number },
    events: {} as
      | { type: 'ANADIR'; articulo: Articulo }
      | { type: 'QUITAR'; id: string }
      | { type: 'PAGAR' },
  },
  actions: {
    // no menciona el evento: recibe el articulo como parametro
    anadirArticulo: assign({
      articulos: ({ context }, params: { articulo: Articulo }) => [
        ...context.articulos,
        params.articulo,
      ],
    }),
    registrar: (_, params: { etiqueta: string }) => console.log(params.etiqueta),
  },
  guards: {
    cabeUnoMas: ({ context }) => context.articulos.length < context.limite,
    superaMinimo: ({ context }, params: { minimo: number }) =>
      context.articulos.reduce((s, a) => s + a.precio, 0) >= params.minimo,
    carritoVacio: ({ context }) => context.articulos.length === 0,
  },
}).createMachine({
  context: { articulos: [], limite: 10 },
  initial: 'comprando',
  states: {
    comprando: {
      on: {
        ANADIR: {
          guard: 'cabeUnoMas',
          // aqui event SI esta estrechado: params se calcula en el sitio que lo sabe
          actions: [
            { type: 'anadirArticulo', params: ({ event }) => ({ articulo: event.articulo }) },
            { type: 'registrar', params: { etiqueta: 'articulo anadido' } },
          ],
        },
        PAGAR: {
          guard: and([not('carritoVacio'), { type: 'superaMinimo', params: { minimo: 20 } }]),
          target: 'pagando',
        },
      },
    },
    pagando: {},
  },
})

El reparto de responsabilidades es exacto y merece detenerse en él. El estrechamiento ocurre donde es posible —en la transición, que conoce su evento— y el desacoplamiento ocurre donde es útil —en la implementación, que así sirve para cualquier origen—. Ni un casting, ni una comprobación redundante, y de propina anadirArticulo es ahora reutilizable desde una transición disparada por un evento completamente distinto.

flowchart LR
T[transicion: conoce su evento] -->|calcula params| A[action nombrada]
T -->|referencia por nombre| A
S[setup: implementa la logica] --> A
A --> E[efecto o assign]
P[provide en un test] -.sustituye.-> A
style T fill:#89b4fa,color:#11111b
style S fill:#cba6f7,color:#11111b
style P fill:#a6e3a1,color:#11111b

Componer, orquestar y sustituir

Los guards nombrados se combinan sin escribir booleanos a mano. and y or toman listas, not niega, y stateIn pregunta por el estado actual de otra región, que es la herramienta canónica para coordinar regiones paralelas sin duplicar información en el context. Todos aceptan tanto un nombre suelto como un objeto con type y params, de modo que la composición no obliga a renunciar a la parametrización.

Para las secuencias condicionales de acciones, la v5 retira pure y choose y los reemplaza por una sola primitiva más expresiva. enqueueActions recibe una función que puede consultar guards con check e ir encolando acciones con enqueue, incluidas variantes como enqueue.assign, enqueue.raise, enqueue.sendTo y enqueue.spawnChild.

import { enqueueActions } from 'xstate'

const conOrquestacion = setup({
  types: { context: {} as { articulos: Articulo[]; limite: number }, events: {} as { type: 'PAGAR' } },
  guards: { casiLleno: ({ context }) => context.articulos.length >= context.limite - 1 },
  actions: {
    avisar: (_, params: { texto: string }) => console.log(params.texto),
    prepararPago: enqueueActions(({ check, enqueue }) => {
      if (check('casiLleno')) enqueue({ type: 'avisar', params: { texto: 'carrito casi lleno' } })
      enqueue.assign({ articulos: [] })
      enqueue.raise({ type: 'PAGAR' })
    }),
  },
})

Y como todo lo anterior tiene nombre, todo lo anterior es sustituible. provide devuelve una máquina nueva, idéntica en estructura, con las implementaciones que indiques reemplazadas: el grafo no cambia, solo cambia el relleno de los símbolos.

const carritoBajoTest = carrito.provide({
  actions: { registrar: () => {} },            // efecto silenciado
  guards: { superaMinimo: () => true },        // umbral neutralizado
})