Middleware: persist, immer, devtools y el orden correcto

El núcleo de Zustand cabe en unos pocos cientos de líneas porque casi todo lo interesante vive fuera de él, en middleware que no pagas hasta que los pides. Pero esa modularidad tiene una letra pequeña que la mayoría descubre depurando: los middleware no son adornos independientes que se apilan en cualquier orden, son transformaciones que reescriben set, get y la API del store antes de pasárselos al siguiente, y por tanto componen como funciones, no como configuración. Quién envuelve a quién determina qué ve cada uno: si devtools queda por dentro de persist, no verá la rehidratación; si immer queda por fuera, el borrador llegará a quien no sabe qué hacer con él. Esta lección explica la mecánica para que el orden deje de ser superstición copiada de un ejemplo.

Qué es realmente un middleware

Un middleware es una función que recibe el inicializador del store y devuelve otro inicializador. Cuando create ejecute el resultado, ese envoltorio recibirá los set, get y api originales, podrá sustituirlos por versiones propias y llamará al inicializador interno con los suyos. immer reemplaza set por uno que acepta una función mutadora; devtools reemplaza set por uno que además emite un evento a la extensión; persist no toca set pero se suscribe al store y añade métodos a api; subscribeWithSelector sustituye api.subscribe por una versión con más parámetros.

// la forma esencial: envolver el inicializador y decidir que set recibe el de dentro
const registrar = (f) => (set, get, api) =>
  f(
    (...args) => {
      console.log('antes', get())
      set(...args)
      console.log('despues', get())
    },
    get,
    api,
  )

export const useCarrito = create<Carrito>()(registrar((set) => ({ /* ... */ })))

flowchart TD
A[devtools capa externa] --> B[persist capa intermedia]
B --> C[immer capa interna]
C --> D[inicializador con estado y acciones]
D -->|set mutador| C
C -->|set inmutable| B
B -->|escribe en el almacen| A
style A fill:#89b4fa,color:#11111b
style C fill:#a6e3a1,color:#11111b

De ahí sale la regla de composición. immer va lo más adentro posible, porque su trabajo es traducir la escritura del inicializador; todo lo que quede por fuera debe recibir ya un objeto normal. devtools va lo más afuera posible, porque su trabajo es observar, y quiere ver también los cambios que originan los demás, incluida la rehidratación de persist. La pila canónica es por tanto devtools envolviendo a persist envolviendo a immer.

import { create } from 'zustand'
import { devtools, persist, createJSONStorage } from 'zustand/middleware'
import { immer } from 'zustand/middleware/immer'

export const useCarrito = create<Carrito>()(
  devtools(
    persist(
      immer((set) => ({
        lineas: [],
        anadir: (l) => set((s) => { s.lineas.push(l) }),   // borrador de immer
      })),
      { name: 'carrito', storage: createJSONStorage(() => localStorage) },
    ),
    { name: 'carrito', enabled: import.meta.env.DEV },
  ),
)

persist: no es guardar, es un ciclo de vida

persist parece un interruptor y es en realidad una máquina de estados con cuatro decisiones que hay que tomar a conciencia. La primera es qué se guarda: por defecto, el estado entero, funciones incluidas, que al serializarse a JSON simplemente desaparecen. Casi siempre quieres partialize para elegir explícitamente las claves persistibles y dejar fuera lo efímero y lo derivado. La segunda es dónde: storage acepta cualquier almacén con la forma esperada, envuelto en createJSONStorage, lo que permite usar sessionStorage, IndexedDB o un almacén asíncrono en móvil. La tercera es cómo evoluciona: version más migrate convierten los datos viejos guardados en el navegador de un usuario que no ha vuelto en seis meses, y sin ellos un cambio de forma del estado provoca una rehidratación silenciosamente corrupta. La cuarta es cuándo: la hidratación es asíncrona en general, y hay una ventana en la que el store tiene el estado inicial y no el guardado.

persist(inicializador, {
  name: 'carrito',
  version: 2,
  partialize: (s) => ({ lineas: s.lineas, cupon: s.cupon }),   // nada de funciones
  migrate: (guardado, version) => {
    if (version < 2) return { ...guardado, cupon: null }        // la clave es nueva
    return guardado
  },
  onRehydrateStorage: () => (estado, error) => {
    if (error) console.error('rehidratacion fallida', error)
  },
})

immer, devtools y subscribeWithSelector

Con immer desaparece la propagación manual que hacía ilegibles los estados anidados, pero conviene recordar qué se paga: el borrador es un proxy, y mutarlo tiene un coste superior al de una propagación trivial. Para un estado plano no aporta nada; para uno con tres niveles y colecciones, es la diferencia entre código que se lee y código que se descifra.

devtools merece una precisión que casi nadie usa: el tercer argumento de set nombra la acción en el panel. Sin él, el registro es una lista interminable de entradas anónimas y la herramienta pierde la mitad de su valor.

anadir: (l) => set((s) => { s.lineas.push(l) }, false, 'carrito/anadirLinea')

subscribeWithSelector transforma subscribe de un oyente global a uno con la misma granularidad que tienen los componentes, y añade algo que el hook no tiene: el oyente recibe el valor nuevo y el anterior, lo que permite reaccionar a transiciones y no solo a estados.

const off = useCarrito.subscribe(
  (s) => s.cupon,
  (nuevo, anterior) => registrarAnalitica(anterior, nuevo),
  { equalityFn: Object.is, fireImmediately: false },
)

El coste en el sistema de tipos

La composición de middleware es la razón por la que create se escribe curvada. Cada middleware declara un mutador en el tipo del store, y esos mutadores viajan en una tupla que TypeScript necesita inferir junto con el estado. Con la forma no curvada la inferencia falla; con la curvada, el estado se fija a mano y los mutadores se infieren solos.

El problema reaparece al extraer el inicializador a una variable o a un archivo aparte, algo obligatorio en cuanto usas slices. Ahí ya no hay inferencia posible y hay que declarar los mutadores explícitamente en StateCreator, cuyo tercer parámetro genérico es la tupla de mutadores aplicados por dentro.

import type { StateCreator } from 'zustand'

// el mutador de immer declarado a mano: sin esto, set no acepta el borrador
type ConImmer = [['zustand/immer', never]]

const crearCarrito: StateCreator<Carrito, ConImmer, [], Carrito> = (set) => ({
  lineas: [],
  anadir: (l) => set((s) => { s.lineas.push(l) }),
})