Actions: entry, exit y la frontera del efecto

Una maquina que solo cambia de estado seria muda: sabria en que modo esta pero no haria nada al respecto. Las actions son su forma de actuar —contar una apertura, avisar al usuario, arrancar un temporizador, enfocar un campo—. XState las organiza en dos ejes que conviene no confundir. El primero es CUANDO se disparan: al entrar en un estado con entry, al salir con exit, o al recorrer una arista con las actions de transicion. El segundo, mas sutil y mas importante, es QUE CLASE de action es: unas son puras y solo tocan la memoria interna de la maquina —como el assign que ya conoces—; otras son efectos que salen al mundo y no vuelven. Trazar esa segunda frontera con nitidez es lo que separa una maquina que puedes testear en aislamiento de una maraña de llamadas imposible de reproducir.

Tres momentos: entry, exit y transicion

Una action puede colgar de tres sitios. En entry, se ejecuta cada vez que la maquina ENTRA en ese estado, venga de donde venga. En exit, cada vez que lo ABANDONA. Y en la clave de un evento, se ejecuta al TOMAR esa transicion concreta. Los tres aceptan una action o una lista de ellas.

import { setup, assign } from 'xstate'

const puerta = setup({
  types: {
    context: {} as { aperturas: number },
    events: {} as { type: 'ABRE' } | { type: 'CIERRA' },
  },
  actions: {
    contarApertura: assign({ aperturas: ({ context }) => context.aperturas + 1 }), // pura
    avisar: (_, params: { texto: string }) => console.log(params.texto),           // efecto
  },
}).createMachine({
  context: { aperturas: 0 },
  initial: 'cerrada',
  states: {
    cerrada: {
      on: { ABRE: { target: 'abierta', actions: 'contarApertura' } },  // action de transicion
    },
    abierta: {
      entry: { type: 'avisar', params: { texto: 'puerta abierta' } },  // al entrar
      exit: { type: 'avisar', params: { texto: 'puerta cerrada' } },   // al salir
      on: { CIERRA: 'cerrada' },
    },
  },
})

La eleccion del momento no es estetica, es semantica. Una action en entry se ejecuta sin importar por que arista llegaste al estado —ideal para lo que SIEMPRE debe pasar al estar en ese modo—. Una action de transicion solo corre por ESA arista —ideal para lo que depende del camino concreto—. Si algo debe ocurrir al entrar a cargando da igual desde donde, es entry; si algo depende de que vengas de error y no de inactivo, es action de transicion.

Un matiz util: una transicion hacia el MISMO estado vuelve a disparar exit y entry si es externa, mientras que una transicion interna no lo hace. Esto te da control fino: si quieres que reentrar en un modo reinicie sus efectos —recontar, reenfocar—, usa una transicion externa a si mismo; si solo quieres tocar el context sin remontar nada, usa una interna. La misma flecha, dos semanticas, segun cruce o no la frontera del estado.

Conviene fijar el habito desde el principio: para cada efecto, preguntate no solo QUE hace, sino en que MOMENTO del ciclo de vida del estado debe ocurrir. La mayoria de los bugs de interfaces reactivas nacen de poner en entry algo que dependia del camino y debia ir en la arista, o de olvidar en exit la limpieza de lo que entry habia montado. Pensar en terminos de momento, y no solo de accion, desactiva ambas trampas de raiz.

El orden dentro de una transicion

Cuando un evento provoca un salto de un estado a otro, XState ejecuta las actions en un orden fijo y garantizado. Primero evalua el guard de la leccion 3; si pasa, ejecuta las exit del estado que se abandona, luego las actions de la transicion, y por ultimo las entry del estado al que se llega. Dentro de cada grupo, el orden es el que declaraste —recuerda la linealidad de v5 de la leccion 2—.

sequenceDiagram
participant G as guard
participant S as estado origen
participant T as arista
participant D as estado destino
G->>G: evalua la condicion primero
S->>S: ejecuta exit del origen
T->>T: ejecuta actions de la transicion
D->>D: ejecuta entry del destino

Este orden importa cuando las actions comparten context. Si el exit del origen limpia un dato y el entry del destino lo lee, veras el dato ya limpio, porque exit corre antes. Conocer la secuencia exit, transicion, entry elimina una fuente entera de bugs de “por que este valor ya estaba cambiado cuando lo lei”.

// el orden exit -> transicion -> entry es observable en la consola
states: {
  a: {
    exit: () => console.log('1 exit de a'),
    on: { IR: { target: 'b', actions: () => console.log('2 action de transicion') } },
  },
  b: { entry: () => console.log('3 entry de b') },
}
// enviar IR estando en a imprime, en este orden exacto: 1, 2, 3

Que este orden sea una garantia del modelo, y no un accidente de implementacion, es lo que te deja predecir el comportamiento sin ejecutarlo: dado un estado, un evento y las actions declaradas, la secuencia es siempre la misma. La reactividad ingenua de los signals no ofrecia esta certeza sobre CUANDO corre cada efecto; una maquina si, porque su ciclo de vida esta escrito en la propia definicion.

Action pura frente a efecto

Aqui esta el eje profundo. Una action pura solo modifica el estado interno de la maquina de forma determinista y queda registrada en el snapshot: assign reescribe el context, raise inyecta un evento interno que se procesara a continuacion. Un efecto es cualquier funcion que impacta el mundo exterior —imprimir, pedir por red, tocar el DOM, disparar analitica— y que la maquina lanza sin esperar respuesta: fire and forget.

actions: [
  assign({ aperturas: ({ context }) => context.aperturas + 1 }), // PURA: cambia el context
  ({ context }) => trackAnalytics(context.aperturas),            // EFECTO: sale al mundo
]

La diferencia no es de sintaxis sino de consecuencias. El interprete de XState calcula PRIMERO el proximo snapshot aplicando las actions puras —el nuevo value y el nuevo context— y solo DESPUES dispara los efectos. Por eso el snapshot resultante es funcion pura del estado, el context y el evento: los efectos no lo alteran, solo salpican hacia fuera. Esta separacion es la que permite, como veremos en la leccion 5, calcular una transicion sin ejecutar sus efectos.

La consecuencia practica es una regla de oro para depurar y testear: si algo debe quedar registrado en el estado y sobrevivir al evento, tiene que ser una action pura; si solo debe ocurrir de cara al exterior y no cambia lo que la maquina ES, es un efecto. Cuando dudes, preguntate si su resultado deberia aparecer en el snapshot: si la respuesta es si, es pura; si da igual porque ya salio al mundo, es un efecto.