El actor como unidad central en XState v5

En XState v4 la máquina de estados era el centro y los actores eran un añadido para casos avanzados. La v5 invierte la jerarquía: ahora el actor es la unidad primaria y la máquina es apenas una de las formas que un actor puede tomar. Una promesa es un actor. Un callback es un actor. Un stream es un actor. Esta unificación no es cosmética: significa que todo en tu sistema —desde una petición HTTP hasta un statechart de mil estados— se crea, se arranca, se observa y se detiene exactamente igual. Aprendes un protocolo y lo usas para todo.

Lógica frente a actor: la clase y la instancia

La distinción más importante del nivel es también la más fácil de pasar por alto. La lógica del actor es una definición: describe cómo se comporta un actor, qué eventos entiende y cómo evoluciona su estado. Es pura y reutilizable, como un plano. El actor es la instancia viva: una ejecución concreta de ese plano, con su propio buzón, su propio estado actual y su propio ciclo de vida. Un plano puede dar lugar a muchos actores, igual que una clase da lugar a muchos objetos.

import { createActor, createMachine, fromPromise } from "xstate"

// Una maquina es una FORMA de logica de actor: un plano, no un actor vivo.
const semaforo = createMachine({
  id: "semaforo",
  initial: "verde",
  states: {
    verde: { on: { CAMBIAR: "amarillo" } },
    amarillo: { on: { CAMBIAR: "rojo" } },
    rojo: { on: { CAMBIAR: "verde" } },
  },
})

// Una promesa tambien es logica de actor: otro plano, misma categoria.
const cargarUsuario = fromPromise(async ({ input }) => {
  const res = await fetch(`/api/usuario/${input.id}`)
  return res.json()
})

Ni semaforo ni cargarUsuario están vivos todavía. Son descripciones inertes. Para darles vida hace falta instanciarlas, y ahí es donde entra el segundo concepto. Confundir el plano con la instancia es el error de novato que produce bugs desconcertantes: reutilizar una lógica en dos actores es sano y esperado; intentar tratar la lógica como si tuviera estado propio no tiene sentido, porque el estado vive en la instancia.

createActor: el protocolo común

createActor toma cualquier lógica y devuelve un actor: una entidad viva que respeta al pie de la letra los tres verbos de Hewitt. Todos los actores, sin importar de qué lógica nazcan, exponen la misma interfaz mínima. Esa uniformidad es la que permite tratar una promesa y un statechart con el mismo código.

const actor = createActor(semaforo)

actor.subscribe((snapshot) => {          // observar: reacciona a cada cambio
  console.log("estado actual:", snapshot.value)
})

actor.start()                            // arrancar: ahora esta vivo y escucha
actor.send({ type: "CAMBIAR" })          // enviar: depositas un evento en su buzon
const snap = actor.getSnapshot()         // leer: consultas su estado sin tocarlo
actor.stop()                             // detener: cierra su ciclo de vida

Cuatro operaciones cubren todo el trato con un actor. start lo pone en marcha; send deposita un evento en su buzón, siempre de forma asíncrona respecto al procesamiento; getSnapshot devuelve una foto inmutable de su estado en este instante; subscribe registra un observador que recibirá cada nueva snapshot. Nunca lees ni escribes el interior del actor directamente: hablas con él por su superficie, exactamente como el modelo de Hewitt exige.

Toda lógica es un actor

Aquí se ve la potencia de la unificación. XState ofrece un constructor por cada forma habitual de lógica asíncrona, y todos producen lógica de actor intercambiable: la misma que consumen createActor, spawn e invoke.

flowchart TD
L1[fromPromise] --> CA[createActor]
L2[fromCallback] --> CA
L3[fromObservable] --> CA
L4[createMachine] --> CA
CA --> AC[actor con start send getSnapshot subscribe]
style CA fill:#cba6f7,color:#11111b
style AC fill:#a6e3a1,color:#11111b

import { fromCallback, fromTransition } from "xstate"

// fromCallback: un reloj que emite un TIC cada segundo hacia quien lo escuche.
const reloj = fromCallback(({ sendBack }) => {
  const id = setInterval(() => sendBack({ type: "TIC" }), 1000)
  return () => clearInterval(id)         // limpieza al detener el actor
})

// fromTransition: un contador que es solo un reducer puro.
const contador = fromTransition(
  (estado, evento) => {
    if (evento.type === "SUMAR") return { total: estado.total + 1 }
    return estado
  },
  { total: 0 },                          // estado inicial
)

Cada constructor cubre un patrón asíncrono distinto, pero todos desembocan en la misma categoría. La tabla resume cuándo alcanza cada uno y cómo termina su ciclo de vida, porque elegir mal el constructor es la fuente más común de actores que nunca se detienen o que se detienen antes de tiempo.

Que un reducer puro y un statechart jerárquico sean ambos “lógica de actor” no es un detalle de implementación: es lo que permite empezar simple y crecer sin cambiar de paradigma. Modelas un contador con fromTransition; si mañana necesita estados y guardas, lo asciendes a createMachine sin tocar cómo lo instancias, lo observas ni lo comunicas con el resto. El molde que lo rodea no se entera del cambio.

Observar un actor de promesa deja ver el protocolo en acción: la misma snapshot que en una máquina describe un value, aquí describe el progreso de la carga hasta terminar con su salida o su error. El código que la observa es idéntico al que observaría un semáforo.

const actor = createActor(cargarUsuario, { input: { id: 42 } })

actor.subscribe((snap) => {
  if (snap.status === "active") console.log("cargando...")
  if (snap.status === "done") console.log("listo:", snap.output)
  if (snap.status === "error") console.log("fallo:", snap.error)
})

actor.start()   // dispara la promesa; las snapshots van llegando solas