assign: mutar el context sin mutarlo

En la leccion anterior separamos el context —la memoria cuantitativa— de los estados finitos. Queda la pregunta operativa: como cambia ese context. La respuesta de XState es tajante y a primera vista extrana: nunca lo tocas directamente. No hay un context.cuenta += 1 dentro de una maquina. En su lugar declaras una action especial, assign, que describe COMO calcular el proximo context a partir del actual y del evento que llego. La maquina no ejecuta esa mutacion cuando la escribes; la guarda como dato y la aplica el interprete, produciendo siempre un objeto nuevo. Entender por que la actualizacion es declarativa e inmutable —y no una asignacion imperativa— es entender por que una maquina se puede rebobinar, testear y serializar.

assign: la unica puerta al context

assign es una action, es decir, un efecto declarado que la maquina asocia a una transicion. Su cometido unico es reemplazar el context. Recibe el context actual y el event que disparo la transicion —con todo su payload— y entrega los cambios; el interprete se encarga de fusionarlos en un objeto nuevo.

import { setup, assign } from 'xstate'

const contador = setup({
  types: {
    context: {} as { cuenta: number; historial: number[] },
    events: {} as { type: 'SUMA'; por: number } | { type: 'RESET' },
  },
}).createMachine({
  context: { cuenta: 0, historial: [] },
  on: {
    SUMA: {
      actions: assign(({ context, event }) => ({
        cuenta: context.cuenta + event.por,               // lee el payload del evento
        historial: [...context.historial, context.cuenta], // copia, no muta
      })),
    },
    RESET: { actions: assign({ cuenta: 0, historial: [] }) },
  },
})

Fijate en tres hechos. Primero, el evento SUMA transporta un dato, por, y assign lo lee: el context se actualiza en funcion de lo que ocurrio. Segundo, historial se reconstruye con un spread, jamas con un push sobre el array existente. Tercero, assign no cambia el estado finito: aqui la transicion es interna —se queda en el mismo estado— y solo reescribe la memoria.

Las dos formas: por propiedad y por funcion

assign acepta dos sintaxis equivalentes en potencia pero distintas en ergonomia. La forma por funcion recibe el context y el event y devuelve un objeto con las claves a cambiar; es la mas legible cuando varias propiedades dependen entre si o del evento. La forma por objeto recibe un mapa de propiedad a asignador, donde cada valor puede ser una constante o una funcion ({ context, event }) => valor; brilla cuando cada campo se calcula por separado.

// forma por objeto: un asignador independiente por propiedad
actions: assign({
  cuenta: ({ context, event }) => context.cuenta + event.por,
  historial: ({ context }) => [...context.historial, context.cuenta],
})

En ambas formas devuelves SOLO las claves que cambian; XState conserva el resto del context intacto. No necesitas repetir las propiedades que no tocas: la fusion es superficial y respeta lo que no mencionas.

Inmutabilidad: por que no mutas a mano

La regla de oro es que el asignador debe DEVOLVER un context nuevo, nunca modificar el que recibe. Escribir context.cuenta += 1 dentro de un asignador es un error silencioso: rompe la comparacion por referencia de la que dependen la deteccion de cambios, el memo de los selectores y las herramientas de depuracion.

La inmutabilidad tiene un premio concreto: como cada evento produce un context nuevo y distinto por referencia, puedes guardar la secuencia de contexts y rebobinar el sistema a cualquier punto, exactamente como un depurador con viaje en el tiempo. Un context que se mutara en el sitio destruiria ese historial, porque todas las referencias apuntarian al ultimo valor.

Cuando el context anida objetos o arrays, la copia debe llegar hasta el nivel que cambias: reescribes el camino y compartes el resto, la tecnica de structural sharing que ya viste en el nivel de inmutabilidad.

// actualizar un campo anidado sin mutar: copia el camino, comparte el resto
assign(({ context, event }) => ({
  usuario: { ...context.usuario, nombre: event.nombre },   // objeto nuevo arriba
  etiquetas: context.etiquetas,                             // referencia intacta abajo
}))

El orden de ejecucion: la correccion de la v5

Aqui la version 5 arregla el error mas famoso de la version 4. En XState v4, todas las assign de una transicion se aplicaban ANTES que cualquier otra action, sin importar el orden en que las hubieras escrito; esto rompia la intuicion y generaba bugs sutiles. En XState v5 las actions se ejecutan en el orden en que las declaras, y cada assign ve el context ya actualizado por las anteriores.

actions: [
  assign({ cuenta: ({ context }) => context.cuenta + 1 }),   // cuenta pasa a 1
  assign({ doble: ({ context }) => context.cuenta * 2 }),    // ve cuenta 1 -> doble 2
  ({ context }) => console.log(context.cuenta, context.doble), // efecto: imprime 1 2
]

En v4 esa misma secuencia imprimia el context viejo porque los assign se adelantaban; en v5 el flujo es lineal y predecible: cada paso observa el resultado del anterior. Esta linealidad es lo que permite razonar sobre una transicion como una tuberia de transformaciones.

sequenceDiagram
participant EV as evento SUMA por 5
participant M as maquina
participant CTX as context
EV->>M: llega con payload por 5
M->>CTX: assign lee cuenta 0 y por 5
CTX-->>M: devuelve context nuevo cuenta 5
M->>CTX: siguiente action ve cuenta 5
M-->>EV: snapshot final con context 5

Esta garantia de orden convierte una transicion en algo que puedes leer como un guion: primero esto, luego aquello, y cada linea ve el resultado de la anterior. Sin ella, razonar sobre varias assign juntas seria adivinar; con ella, es leer de arriba abajo. Esa legibilidad convierte a la maquina en documentacion viva de su propia logica: el orden que lees es exactamente el orden que corre. Pocas partes de un stack de estado te regalan esa correspondencia literal entre lo que se lee y lo que se ejecuta.