Guards: la transicion que pregunta antes de saltar

Hasta ahora nuestras transiciones eran incondicionales: llega el evento, la maquina salta. Pero los sistemas reales estan llenos de saltos que solo deben producirse bajo cierta condicion —retirar dinero solo si hay fondos, avanzar el asistente solo si el paso es valido, reintentar solo si quedan intentos—. Codificar esa condicion como un estado mas nos devolveria a la explosion combinatoria de la leccion 1. La herramienta correcta es el guard: un predicado que cuelga de la arista de transicion y decide, en el momento exacto del salto, si este ocurre. El guard es donde la memoria cuantitativa que guardamos en el context por fin influye en el control cualitativo, sin dejar de ser memoria. Es, literalmente, la maquina preguntando antes de saltar.

El guard: un predicado en la arista

Un guard es una funcion que recibe el context y el event y devuelve un booleano. XState la evalua justo antes de tomar la transicion: si devuelve verdadero, el salto procede —con sus actions y su cambio de estado—; si devuelve falso, la transicion se descarta como si no existiera. En XState v5 la propiedad se llama guard —en la v4 se llamaba cond, un cambio que conviene recordar al leer codigo antiguo—.

import { setup } from 'xstate'

const cajero = setup({
  types: {
    context: {} as { saldo: number; bloqueada: boolean },
    events: {} as { type: 'RETIRA'; monto: number },
  },
  guards: {
    hayFondos: ({ context, event }) => context.saldo >= event.monto,   // lee context y evento
  },
}).createMachine({
  context: { saldo: 100, bloqueada: false },
  initial: 'activo',
  states: {
    activo: {
      on: {
        RETIRA: [
          { target: 'entregando', guard: 'hayFondos' },   // candidata 1
          { target: 'rechazado' },                          // candidata 2: fallback
        ],
      },
    },
    entregando: {},
    rechazado: {},
  },
})

Aqui esta la resolucion de la tension de la leccion 1: el saldo es un dato cuantitativo y sigue viviendo en el context, no como estados saldo0, saldo1. La distincion cualitativa “hay fondos o no” no se materializa como memoria duplicada, sino que el guard hayFondos la calcula en el instante de transitar. El numero vive una sola vez; la cualidad se deduce cuando importa.

Transiciones candidatas y el fallthrough

Cuando una misma clave de evento tiene varias transiciones —un array— XState las trata como candidatas ordenadas. Las evalua de arriba abajo y toma la PRIMERA cuyo guard pase; una candidata sin guard pasa siempre y actua de fallback. Es la misma semantica que un if / else if / else: solo se ejecuta una rama, y el orden importa.

Hay un detalle facil de olvidar: si NINGUNA candidata pasa su guard y no hay fallback, el evento se ignora en silencio. La maquina no transita, no lanza error, no avisa. Es el comportamiento correcto —un evento no aplicable simplemente no aplica— pero explica muchos “por que no pasa nada al pulsar el boton”: el guard estaba devolviendo falso y no habia salida alternativa.

flowchart TD
A[activo] -->|RETIRA y hayFondos| B[entregando]
A -->|RETIRA sin fondos| C[rechazado]
B --> A
C --> A
style A fill:#89b4fa,color:#11111b
style B fill:#a6e3a1,color:#11111b
style C fill:#f38ba8,color:#11111b

Guards parametrizados y combinadores

Un guard escrito como funcion suelta captura su condicion en duro. XState v5 permite parametrizarlos para reutilizar la misma logica con distintos umbrales: el guard recibe un segundo argumento con sus params, y en el punto de uso pasas el objeto de parametros.

guards: {
  saldoMinimo: ({ context }, params: { min: number }) => context.saldo >= params.min,
}
// en la transicion, con parametros distintos segun el caso:
guard: { type: 'saldoMinimo', params: { min: 50 } }

Para condiciones compuestas, v5 ofrece los combinadores de orden superior and, or y not, que reciben nombres de guards o guards inline y devuelven un guard nuevo. Evitan enredar la logica booleana dentro de una sola funcion y la dejan legible y componible.

import { and, or, not } from 'xstate'

// retira solo si hay fondos, la cuenta no esta bloqueada, y ademas
// es horario habil O el monto es pequeno
guard: and([
  'hayFondos',
  not('cuentaBloqueada'),
  or(['horarioHabil', { type: 'saldoMinimo', params: { min: 0 } }]),
])

Existe ademas stateIn, un guard que comprueba en que estado esta la maquina —util con estados paralelos, del nivel de statecharts— sin que tengas que espejar esa informacion en el context.

Los guards no solo cuelgan de eventos: una transicion always —sin evento, evaluada de continuo tras cada cambio— usa un guard para saltar en cuanto la condicion se cumple, ideal para estados transitorios que deciden por si solos a donde ir.

// estado transitorio: decide su destino solo con guards, sin esperar evento
verificando: {
  always: [
    { target: 'admitido', guard: 'cumpleRequisitos' },
    { target: 'rechazado' },   // fallback si el guard falla
  ],
}

La pureza no es opcional

Un guard se evalua para DECIDIR, no para ACTUAR. Debe ser una funcion pura: sin efectos secundarios, sincrona, y determinista —la misma entrada da siempre la misma respuesta—.