redux-persist y el middleware persist: qué guardan realmente

Las dos herramientas que dominan la persistencia en este ecosistema resuelven un problema idéntico con arquitecturas casi opuestas, y esa diferencia no es estética: determina qué puedes observar, qué puedes interceptar y qué falla en silencio. redux-persist se coloca en el único punto de extensión que Redux ofrece para reescribir estado, el reductor, y por eso su rehidratación es una acción como cualquier otra, visible en las herramientas de desarrollo y componible con el resto del sistema. El middleware persist de Zustand se coloca donde Zustand pone todo, envolviendo el inicializador, y por eso su rehidratación no es un evento del sistema sino una llamada a métodos que el propio middleware añade al store. Detrás de esa divergencia hay una coincidencia que importa más que la diferencia: ambos escriben en cada cambio, ambos serializan a texto plano y ambos guardan bastante menos de lo que su usuario cree.

redux-persist: un reductor que envuelve a otro

La pieza central es persistReducer, que recibe una configuración y tu reductor raíz y devuelve otro reductor con el mismo aspecto por fuera. Ese envoltorio hace tres cosas. Intercepta la acción REHYDRATE, que transporta el estado leído del almacén, y en lugar de pasarla al reductor de dentro la resuelve él mismo fundiendo lo guardado con lo que había. Marca cada estado resultante con una clave interna de metadatos donde registra la versión y si la rehidratación ya ocurrió. Y se suscribe al store para escribir el estado nuevo en el almacén después de cada actualización.

import { persistStore, persistReducer } from 'redux-persist'
import storage from 'redux-persist/lib/storage'

const config = {
  key: 'raiz',
  version: 1,
  storage,
  whitelist: ['preferencias', 'ui'],   // lista por inclusion, no por exclusion
}

export const store = configureStore({
  reducer: persistReducer(config, reductorRaiz),
  middleware: (d) =>
    d({ serializableCheck: { ignoredActions: ['persist/PERSIST', 'persist/REHYDRATE'] } }),
})

export const persistor = persistStore(store)

La segunda pieza, persistStore, es la que arranca el ciclo: despacha PERSIST, lanza la lectura del almacén y, cuando llega el contenido, despacha REHYDRATE con él. Que la rehidratación sea una acción tiene una consecuencia excelente y una molestia. La consecuencia es que aparece en el registro de las herramientas de desarrollo, puede viajarse en el tiempo y puede ser observada por cualquier otro reductor o middleware que quiera reaccionar a ella. La molestia es que su carga útil no siempre es serializable y que la comprobación que Redux Toolkit trae activada por defecto protestará hasta que la excluyas explícitamente.

El middleware persist de Zustand: una suscripción con ceremonia

En Zustand no hay reductor que interceptar, así que persist hace lo que hace todo middleware de la librería: envuelve el inicializador. Al ejecutarse, lee el almacén, funde el resultado con el estado inicial y llama a setState; después se suscribe para escribir en cada cambio. La configuración cubre las mismas cuatro decisiones que en Redux —qué, dónde, cómo se funde y cómo evoluciona— con nombres distintos, y añade algo que Redux no ofrece de fábrica: una API imperativa colgada del propio store para gobernar el momento de la hidratación.

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

export const usePreferencias = create<Preferencias>()(
  persist(
    (set) => ({ tema: 'claro', idioma: 'es', cambiarTema: (t) => set({ tema: t }) }),
    {
      name: 'preferencias',
      storage: createJSONStorage(() => localStorage),
      partialize: (s) => ({ tema: s.tema, idioma: s.idioma }),
      merge: (guardado, actual) => ({ ...actual, ...(guardado as object) }),
    },
  ),
)

// API imperativa que anade el middleware
usePreferencias.persist.hasHydrated()
usePreferencias.persist.rehydrate()
usePreferencias.persist.clearStorage()

sequenceDiagram
participant U as interaccion
participant S as store
participant M as middleware persist
participant A as almacen del navegador
U->>S: set con el estado nuevo
S->>M: notifica el cambio
M->>M: aplica partialize
M->>M: convierte a texto plano
M->>A: escribe bajo la clave name
Note over M,A: ocurre en cada cambio, sin agrupacion

Qué se guarda de verdad

El punto ciego compartido por ambas herramientas es que ninguna guarda tu estado: guardan la proyección de tu estado sobre un formato de texto que no sabe representar la mayoría de las cosas interesantes de un lenguaje dinámico. Las funciones desaparecen sin error, lo que en Zustand es especialmente traicionero porque las acciones viven dentro del mismo objeto que los datos. Una fecha vuelve convertida en texto y cualquier método que le invoques después fallará. Un conjunto y un mapa vuelven como objetos vacíos, porque el formato no conoce ninguno de los dos. Un valor no numérico o infinito vuelve como nulo. Y un valor indefinido en una propiedad hace que la propiedad simplemente no exista al volver.

// Un almacen que agrupa escrituras: la misma forma, con retardo.
const conRetardo = (base: Storage, ms = 400): Storage => {
  let pendiente: ReturnType<typeof setTimeout> | undefined
  return {
    ...base,
    setItem: (k, v) => {
      clearTimeout(pendiente)
      pendiente = setTimeout(() => base.setItem(k, v), ms)
    },
  }
}

Reconciliar: la decisión que nadie configura y todos padecen

Cuando el contenido del almacén llega, hay dos objetos sobre la mesa: el estado inicial que define el código de hoy y el estado guardado que escribió el código de ayer. Fundirlos no es una operación obvia, y la estrategia por defecto de ambas herramientas —una fusión superficial de primer nivel— tiene una propiedad que conviene entender: las claves nuevas que el código de hoy define y el almacén no contiene sobreviven, pero solo en el primer nivel. Si una rebanada anidada gana un campo nuevo, la fusión superficial reemplaza la rebanada entera por la versión guardada y el campo nuevo desaparece, con su valor inicial perdido y un valor indefinido en su lugar.

// Fusion profunda solo donde hace falta, y explicita.
merge: (guardado, actual) => {
  const g = guardado as Partial<Estado>
  return {
    ...actual,
    ...g,
    tabla: { ...actual.tabla, ...(g.tabla ?? {}) },   // sin esto se pierde lo nuevo
  }
},

redux-persist nombra estas estrategias explícitamente: fusión automática de primer nivel, fusión automática de segundo nivel y sustitución dura, que descarta el estado inicial por completo. Elegir mal produce el error más desconcertante de este nivel, porque el síntoma —un campo indefinido en un estado que el código declara con valor— aparece solo en los usuarios que ya tenían datos guardados y nunca en la máquina de quien programa, que suele limpiar el almacén sin darse cuenta mientras trabaja.