Hidratación al arrancar

Un store en memoria nace en un solo acto: le das un estado inicial y ya está vivo. Un store persistente no tiene ese lujo, porque su verdadero estado inicial no está en tu código sino en el disco, escrito por una sesión anterior que ya no existe. Arrancarlo es un ritual en dos tiempos: primero exhumar la fotografía que dejó esa sesión pasada, luego insuflarle vida fusionándola con los valores por defecto de la versión actual. A ese ritual lo llamamos hidratación, y su nombre no es casual: el estado serializado es un polvo deshidratado, inerte y ligero, que solo vuelve a ser estado vivo cuando se reconstituye dentro de un store en ejecución. La operación parece trivial —leer y asignar— pero esconde dos abismos. El primero es la fusión: si reemplazas en vez de mezclar, cualquier campo nuevo que tu código espera y que la foto vieja no tenía llegará como undefined y romperá en silencio. El segundo es el tiempo: si el medio es asíncrono, tu aplicación pintará su primer fotograma antes de que la hidratación termine, y renderizará contra un estado vacío que un parpadeo después cambiará bajo los pies del usuario.

Los dos sentidos de la persistencia

Persistir no es una operación, son dos que se turnan. Deshidratar es el sentido de salida: se toma una instantánea del estado vivo, se serializa y se escribe en el medio durable. Rehidratar es el sentido de entrada: se lee esa instantánea, se deserializa y se inyecta en un store que acaba de nacer. La app pasa la vida entera deshidratando —cada cambio se persiste— y rehidrata una sola vez, al arranque. Esa asimetría explica por qué el bug vive casi siempre en la rehidratación: es el paso que ocurre una vez y bajo condiciones difíciles de reproducir.

El corazón del patrón rehydrate es una palabra: fusión. El estado persistido no reemplaza al inicial, lo enriquece. Arrancas con los valores por defecto de la versión actual y encima aplicas lo que la sesión anterior guardó. Así, si tu código añadió un campo nuevo que la foto vieja no conocía, ese campo conserva su valor por defecto en lugar de aparecer como undefined.

const PORDEFECTO = { tema: 'claro', idioma: 'es', panelAbierto: false }

function rehidratar() {
  const crudo = localStorage.getItem('ajustes')
  if (!crudo) return PORDEFECTO
  const guardado = JSON.parse(crudo)
  return { ...PORDEFECTO, ...guardado } // fusion: defaults primero, guardado despues
}

const store = crearStore(rehidratar()) // el store nace ya hidratado

El ciclo completo, escribir y leer

En la práctica no hidratas a mano cada campo: montas un ciclo que lee una vez al arrancar y escribe cada vez que el estado cambia. La escritura se suscribe a los cambios del store, y como esos cambios pueden llegar en ráfagas, se atenúa con un debounce para no martillear el disco en cada pulsación de tecla.

function persistir(store, clave, pordefecto) {
  const inicial = { ...pordefecto, ...leer(clave) } // rehydrate
  store.setState(inicial)

  let temporizador
  store.subscribe((estado) => {           // dehydrate en cada cambio
    clearTimeout(temporizador)
    temporizador = setTimeout(() => {
      localStorage.setItem(clave, JSON.stringify(estado))
    }, 300)                               // debounce: escribe tras la calma
  })
}

El debounce introduce un riesgo sutil: si el usuario cierra la pestaña dentro de la ventana de espera, la última escritura pendiente se pierde. La cura es vaciar el temporizador cuando la página se va, escuchando pagehide o visibilitychange y forzando una escritura síncrona final. Es de los pocos momentos en que se justifica un setItem fuera del ciclo normal.

addEventListener('pagehide', () => {          // la pestana esta a punto de morir
  clearTimeout(temporizador)                  // cancela el debounce pendiente
  localStorage.setItem(clave, JSON.stringify(store.getState())) // vuelca ya
})

Este es exactamente el patrón que empaquetan los middlewares que ya conoces. El persist de Zustand, redux-persist o el persistAtom de Jotai no hacen magia distinta: rehidratan al construir el store y deshidratan en cada suscripción, con la fusión y el debounce incorporados. Verlos como una automatización de este ciclo, y no como una caja negra, te permite depurarlos cuando fallan.

flowchart LR
D[medio durable] -->|leer una vez| R[deserializar]
R -->|fusionar con defaults| S[store vivo]
S -->|cada cambio| W[serializar]
W -->|escribir con debounce| D
style S fill:#a6e3a1,color:#11111b
style R fill:#89b4fa,color:#11111b

Cuando la hidratación llega tarde

Todo lo anterior asume un medio síncrono. Con localStorage la rehidratación termina antes de que el primer render ocurra, así que el store nunca se ve vacío. Con IndexedDB la historia cambia por completo: leer devuelve una promesa, la app pinta su primer fotograma mientras la lectura sigue en vuelo, y el store nace con los valores por defecto. Un instante después la promesa resuelve, el store salta al estado guardado, y el usuario ve un parpadeo: el tema claro por defecto que de golpe se vuelve oscuro, el carrito vacío que de repente tiene tres artículos.

La solución es una compuerta. Mantienes una bandera hidratado en falso hasta que la lectura asíncrona resuelve, y hasta entonces no renderizas la interfaz real sino un esqueleto o un espacio neutro. Solo cuando la hidratación completa levantas la compuerta y dejas que la vista se pinte contra un estado ya definitivo.

const store = crearStore({ ...PORDEFECTO, hidratado: false })

get('estado').then((guardado) => {                 // IndexedDB, asincrono
  store.setState({ ...PORDEFECTO, ...guardado, hidratado: true })
})

// En la vista: no pintes nada real hasta que la compuerta se abra.
// if (!estado.hidratado) return <Esqueleto />

Una alternativa a esconder toda la interfaz tras un esqueleto es hidratar por capas: renderiza de inmediato el armazón que no depende del estado persistido —la navegación, el encabezado— y aplica la compuerta solo al fragmento que sí lo necesita. Así el usuario ve algo útil al instante y solo la zona dependiente del disco espera a la hidratación. La compuerta debe ser tan pequeña como el estado que protege, nunca envolver la aplicación entera por comodidad.

No dispares efectos durante la hidratación

Hay una costura más, fina y traicionera, que casi nadie ve hasta que la sufre. Cuando rehidratas asignando el estado guardado con un setState, el store no distingue esa asignación de un cambio provocado por el usuario: notifica a todos sus suscriptores como si el dato acabara de cambiar en vivo. Si tenías un efecto escuchando ese fragmento —una llamada de analítica, una sincronización con el servidor, una notificación—, se disparará al arrancar, reaccionando a una restauración como si fuera una acción.

El resultado son bugs desconcertantes: un evento de analítica que se registra en cada carga sin que el usuario toque nada, o una petición de guardado que se dispara justo tras leer del disco. La cura es hacer que la hidratación sea un evento distinguible del cambio genuino. La vía limpia es inicializar el store con el valor ya en la construcción, de forma síncrona, para que no exista ningún evento de cambio que notificar. Cuando el medio es asíncrono y no queda más remedio que asignar después, marca la asignación para que los efectos la ignoren.

// MAL: hidratar via setState notifica a los suscriptores como un cambio real.
store.subscribe((s) => analitica.registrar('cambio_tema', s.tema)) // se dispara al hidratar

// BIEN: inicializa en la construccion, sincrono, sin evento de cambio.
const store = crearStore(rehidratar())

// Si es forzosamente asincrono, marca la hidratacion y guardala en los efectos.
store.setState({ ...guardado, _hidratando: true })
// dentro del efecto:  if (s._hidratando) return