Máquina y TanStack Query: la división del trabajo

Aceptado que un flujo con pasos merece una máquina y que un recurso remoto merece una cache, queda el problema interesante: casi todo flujo real necesita datos de servidor a mitad de camino. La tentación de resolverlo eligiendo un único bando —o todo en la máquina, o todo en la librería— produce arquitecturas que sufren por lados opuestos. La solución no es elegir, es repartir, y el reparto tiene una línea nítida que se puede enunciar en una frase: la máquina decide cuándo y en qué orden ocurren las cosas, TanStack Query decide qué dato es este, si sigue fresco y quién más lo está mirando. Todo lo que sigue es el desarrollo técnico de esa frase y, sobre todo, de lo que ocurre cuando alguien la ignora.

Quién manda sobre qué

La división del trabajo se vuelve mecánica en cuanto clasificas cada decisión según de qué depende su respuesta. Si depende de dónde está el usuario en el procedimiento, manda la máquina. Si depende de qué recurso es y de cuándo se leyó por última vez, manda la cache.

La última fila es la interesante y la que más equipos resuelven mal. Tras una escritura con éxito, saber qué quedó obsoleto es conocimiento del dominio, y el dominio lo modela la máquina; pero ejecutar esa obsolescencia —marcar claves, avisar a los observadores, decidir si refrescar ya o al próximo montaje— es trabajo de la cache. La máquina emite la orden, la librería la cumple. Cuando la máquina intenta además cumplirla, empieza el anti-patrón que cierra este nivel.

El puente principal: la máquina invoca a la cache

El patrón que resuelve la mayoría de los casos es también el más simple: el actor invocado por la máquina no llama a fetch, llama a la cache. Así la entrada al estado sigue disparando la lectura —la máquina conserva el mando del cuándo— pero la deduplicación, la frescura y la compartición siguen siendo de la librería.

import { QueryClient } from '@tanstack/query-core'
import { setup, fromPromise, assign } from 'xstate'

export const qc = new QueryClient()

const leerPerfil = fromPromise(({ input, signal }: { input: { id: string }; signal: AbortSignal }) =>
  qc.fetchQuery({
    queryKey: ['perfil', input.id],
    queryFn: () => fetch(`/api/perfil/${input.id}`, { signal }).then((r) => r.json()),
    staleTime: 30_000,
  })
)

Dos detalles hacen que este puente sea correcto y no una simple indirección. El primero es signal: XState cancela el actor al salir del estado y ese aborto debe llegar a la petición real, o tendrás peticiones huérfanas resolviendo contra un flujo que ya avanzó. El segundo es staleTime: si el dato de esa clave sigue fresco, fetchQuery resuelve desde memoria sin tocar la red, de modo que un flujo que revisita el mismo paso no repite trabajo. La máquina no se entera de esa optimización, y esa ignorancia es exactamente la propiedad que buscas.

const maquina = setup({
  types: { context: {} as { id: string; borrador: Borrador | null } },
  actors: { leerPerfil },
  actions: {
    invalidarPerfil: ({ context }) => {
      qc.invalidateQueries({ queryKey: ['perfil', context.id] })
    },
  },
}).createMachine({
  initial: 'revisando',
  context: { id: '', borrador: null },
  states: {
    revisando: {
      invoke: { src: 'leerPerfil', input: ({ context }) => ({ id: context.id }), onDone: 'editando', onError: 'fallo' },
    },
    editando: { on: { GUARDAR: 'guardando' } },
    guardando: {
      invoke: { src: 'guardarPerfil', onDone: { target: 'listo', actions: 'invalidarPerfil' }, onError: 'fallo' },
    },
    listo: { type: 'final' },
    fallo: { on: { REINTENTAR: 'revisando' } },
  },
})

Observa lo que el contexto guarda y lo que no. Guarda id, que es identidad y le pertenece al flujo, y borrador, que es estado de cliente en curso y no existe todavía en el servidor. No guarda el perfil leído: ese dato vive bajo su clave y cualquier componente lo obtiene con una consulta, sin pasar por la máquina ni por props.

Los otros puentes y sus costes

El actor que invoca a la cache resuelve el caso de lectura puntual, pero hay dos situaciones donde no basta: cuando la máquina debe reaccionar a cambios posteriores del dato y cuando la máquina vive en la UI y prefieres no acoplarla al cliente de consultas. Las dos primeras tarjetas son esos puentes alternativos; las dos últimas, las piezas que los mantienen sanos.

import { fromCallback } from 'xstate'
import { QueryObserver } from '@tanstack/query-core'

const observarPedido = fromCallback(({ input, sendBack }: any) => {
  const observer = new QueryObserver(qc, { queryKey: ['pedido', input.id] })
  return observer.subscribe((r) => {
    if (r.isSuccess) sendBack({ type: 'PEDIDO_ACTUALIZADO', datos: r.data })
    if (r.isError) sendBack({ type: 'PEDIDO_FALLO', error: r.error })
  })
})

El actor observador convierte la cache en una fuente de eventos, que es la forma en que una máquina sabe escuchar. Es el puente adecuado cuando el flujo debe responder a cambios que no provocó —una revalidación en foco que descubre que el pedido ya fue pagado en otro dispositivo—, y es también el más caro: cada actualización entra como evento y debes decidir en qué estados es legal recibirla. Un evento de datos que llega en mitad de un paso crítico y no está declarado en ese estado se ignora, y ese silencio es una decisión de diseño que conviene tomar a propósito.

sequenceDiagram
participant U as usuario
participant M as maquina
participant Q as cache de datos
participant S as servidor
U->>M: evento CONFIRMAR
M->>Q: pedir la clave del recurso
alt clave fresca
  Q-->>M: dato desde memoria sin red
else clave obsoleta
  Q->>S: peticion con signal
  S-->>Q: respuesta
  Q-->>M: dato revalidado
end
M->>M: transicion al paso siguiente
M->>Q: orden de invalidar claves afectadas