En la práctica: onMutate y useOptimistic

Las tres lecciones previas construyeron el optimismo desde los principios: aplicar la predicción, revertirla si falla, reconciliarla con el servidor. Ahora bajamos al terreno donde esos principios se escriben de verdad, y descubrimos que el ecosistema ofrece dos encarnaciones muy distintas de la misma idea. TanStack Query la resuelve con un trío de retrollamadas —onMutate, onError, onSettled— que mapean uno a uno la disciplina que ya conoces. React 19, con su hook useOptimistic, la resuelve al revés: sin snapshot, sin rollback manual, con un estado optimista que existe solo mientras dura la acción asíncrona y se evapora cuando termina. No son dos sintaxis para lo mismo: son dos filosofías sobre qué es una predicción y cuánto debe durar.

TanStack Query: el trío onMutate, onError, onSettled

En TanStack Query, una mutación optimista se configura con tres retrollamadas del useMutation, y cada una es una de las fases que ya estudiaste. onMutate se ejecuta antes de lanzar la petición: ahí cancelas las revalidaciones en vuelo, tomas el snapshot y aplicas la predicción a la cache; lo que devuelvas se convierte en el contexto que reciben las demás. onError recibe ese contexto y restaura el snapshot: es el rollback. onSettled corre al final pase lo que pase, con éxito o con fallo, e invalida la query para reconciliar con el servidor.

useMutation({
  mutationFn: (texto: string) => api.crearTarea(texto),

  async onMutate(texto) {
    await qc.cancelQueries({ queryKey: ["tareas"] });      // cancelar
    const anterior = qc.getQueryData(["tareas"]);           // snapshot
    qc.setQueryData(["tareas"], (v) => [...v, { id: "temporal", texto }]);
    return { anterior };                                    // contexto -> onError
  },

  onError(_err, _texto, ctx) {
    qc.setQueryData(["tareas"], ctx.anterior);              // rollback
  },

  onSettled() {
    qc.invalidateQueries({ queryKey: ["tareas"] });         // reconciliar
  },
});

El diseño es una traducción literal de la teoría: onMutate es el orden canónico de la lección tres —cancelar, capturar, aplicar—; el valor que retorna viaja como context hasta onError para que el rollback tenga a mano el pasado; y onSettled garantiza la reconciliación sin importar el desenlace.

useOptimistic: el estado que se descarta solo

React 19 aborda el problema desde otra premisa. useOptimistic recibe el estado real y una función que describe cómo se ve con la predicción aplicada, y devuelve un valor optimista junto a una función para añadir predicciones. La clave está en su ciclo de vida: el valor optimista existe solo mientras una acción asíncrona —una transición— está pendiente. En cuanto la acción termina y el estado real se actualiza, React descarta la capa optimista y el valor real reaparece por sí solo. No escribes rollback: si la acción falla y el estado real no cambia, la predicción simplemente se desvanece y la base se reafirma.

function Comentarios({ comentarios, enviar }) {
  const [optimistas, agregar] = useOptimistic(
    comentarios,
    (estado, nuevo) => [...estado, { texto: nuevo, pendiente: true }],
  );

  async function accion(formData) {
    const texto = formData.get("texto");
    agregar(texto);              // capa optimista, visible durante la transicion
    await enviar(texto);         // al terminar, React descarta la capa
  }

  return (
    <form action={accion}>
      {optimistas.map((c, i) => (
        <p key={i} style={{ opacity: c.pendiente ? 0.5 : 1 }}>{c.texto}</p>
      ))}
      <input name="texto" />
    </form>
  );
}

Aquí no hay snapshot ni reversión explícita porque el modelo es otro: el estado optimista nunca fue durable. Era una superposición temporal sobre comentarios, la fuente de verdad, y al acabar la transición esa fuente vuelve a mandar sin que tengas que restaurarla a mano.

Conviene leer la firma del hook con cuidado, porque encierra su única restricción dura:

const [valorOptimista, agregarOptimista] = useOptimistic(estadoReal, reductor);
// agregarOptimista solo surte efecto dentro de una accion o de useTransition.
// Fuera de ese contexto, React no tiene ningun "pendiente" al que atar la
// capa optimista, y el cambio se ignora en la practica.

Dos filosofías, un problema

Las dos APIs resuelven el mismo problema con modelos mentales opuestos, y elegir bien exige entender la diferencia.

Como regla, useOptimistic brilla cuando la predicción acompaña a una acción concreta y local —enviar un formulario, mandar un mensaje— y no necesita perdurar. TanStack Query brilla cuando la predicción edita datos de servidor cacheados que muchas vistas comparten y que deben reconciliarse con precisión. No compiten tanto como cubren tramos distintos del mismo espectro.

El contraste se ve mejor comparando sus dos ciclos de vida lado a lado: uno reparte la responsabilidad en tres retrollamadas que tú escribes; el otro la resuelve atando la predicción a la vida de una transición.

flowchart TD
A[TanStack onMutate captura y predice] --> B[peticion viaja]
B --> C[onError revierte a mano]
B --> D[onSettled invalida y reconcilia]
E[React agregar dentro de la accion] --> F[capa visible mientras pendiente]
F --> G[la accion termina y la capa se descarta sola]
style C fill:#fab387,color:#11111b
style D fill:#89b4fa,color:#11111b
style G fill:#a6e3a1,color:#11111b