LocalStorage con Expiración TTL en JavaScript
Almacena datos en localStorage con expiración TTL: limpieza perezosa, manejo de cuota, stale-while-revalidate y sincronización entre pestañas
Visión General
localStorage guarda lo que escribas hasta que alguien lo borre; no trae expiración incorporada. Este recurso lo envuelve con soporte TTL (time-to-live) para que las entradas envejezcan solas: set/get con timestamp de expiración, limpieza perezosa al leer, manejo de cuota, una variante stale-while-revalidate para caché de API y sincronización entre pestañas.
Para caché guiada por el servidor el navegador ya tiene las cabeceras HTTP. Este recurso es para la caché del lado del cliente que controlas tú: respuestas de API que no quieres volver a pedir en cada carga, feature flags, estado de un asistente que debería morir al cabo de una hora.
Cuándo Usar
- Caché del lado del cliente con expiración automática (respuestas de API, configuración, feature flags)
- Preferencias de usuario o estado de UI que debería reiniciarse tras un tiempo
- Una app offline-first que necesita lecturas stale-while-revalidate
- Almacenamiento tipo sesión que sobreviva recargas pero no para siempre
Y cuándo NO usarlo:
| Situación | Mejor herramienta |
|---|---|
| Tokens, credenciales, datos personales | sessionStorage, memoria o cookies httpOnly — cualquier script del origen puede leer localStorage |
| Datos de más de unos cientos de KB | IndexedDB — localStorage toca techo en ~5-10 MB y bloquea el hilo principal |
| Datos que necesitan transacciones o índices | IndexedDB |
| Caché cuya corrección depende del servidor | Cabeceras HTTP de caché / service worker — el reloj del cliente puede ir mal |
| Escrituras multi-pestaña que deben mantenerse sincronizadas | El evento storage ayuda, pero para estado compartido un servidor o un diseño con BroadcastChannel es más limpio |
Solución
1. localStorage básico con TTL
const storage = {
prefix: "ttl:",
set(key, value, ttlMs = 60000) {
const item = {
value,
expiry: Date.now() + ttlMs
};
localStorage.setItem(this.prefix + key, JSON.stringify(item));
},
get(key) {
const raw = localStorage.getItem(this.prefix + key);
if (!raw) return null;
try {
const item = JSON.parse(raw);
if (Date.now() > item.expiry) {
localStorage.removeItem(this.prefix + key);
return null;
}
return item.value;
} catch (err) {
localStorage.removeItem(this.prefix + key);
return null;
}
},
remove(key) {
localStorage.removeItem(this.prefix + key);
},
clear() {
// Solo NUESTRAS claves — localStorage.clear() borraría todo el origen
Object.keys(localStorage)
.filter(k => k.startsWith(this.prefix))
.forEach(k => localStorage.removeItem(k));
}
};
// Uso: cachear por 5 minutos
storage.set("api-data", { users: [1, 2, 3] }, 5 * 60 * 1000);
const data = storage.get("api-data");
console.log(data);
Dos cosas que ya importan en esta versión mínima: el try/catch al parsear (otro código, o un deploy anterior, puede haber dejado datos que no son JSON bajo tus claves) y el clear() acotado. Un localStorage.clear() a secas borra todo en el origen: otras partes de la app, otras librerías, todo.
2. Wrapper de storage con limpieza y manejo de cuota
class TTLStorage {
constructor(prefix = "ttl:") {
this.prefix = prefix;
// Respaldo en memoria: modo privado / storage deshabilitado
this.memoryFallback = new Map();
this.available = this.checkAvailable();
}
checkAvailable() {
try {
const probe = this.prefix + "__probe__";
localStorage.setItem(probe, "1");
localStorage.removeItem(probe);
return true;
} catch (err) {
return false;
}
}
set(key, value, ttlMs = 300000) {
const item = {
value: JSON.stringify(value),
expiry: Date.now() + ttlMs,
created: Date.now()
};
if (!this.available) {
this.memoryFallback.set(this.prefix + key, item);
return true;
}
try {
localStorage.setItem(this.prefix + key, JSON.stringify(item));
return true;
} catch (err) {
if (err.name === "QuotaExceededError") {
this.cleanup();
try {
localStorage.setItem(this.prefix + key, JSON.stringify(item));
return true;
} catch (err2) {
console.error("Cuota de almacenamiento excedida incluso tras limpiar");
return false;
}
}
console.error("Error al guardar:", err);
return false;
}
}
get(key, fallback = null) {
const fullKey = this.prefix + key;
if (!this.available) {
const item = this.memoryFallback.get(fullKey);
if (!item) return fallback;
return Date.now() > item.expiry ? fallback : JSON.parse(item.value);
}
const raw = localStorage.getItem(fullKey);
if (!raw) return fallback;
try {
const item = JSON.parse(raw);
if (Date.now() > item.expiry) {
localStorage.removeItem(fullKey);
return fallback;
}
return JSON.parse(item.value);
} catch (err) {
localStorage.removeItem(fullKey);
return fallback;
}
}
has(key) {
return this.get(key, Symbol.for("ttl:miss")) !== Symbol.for("ttl:miss");
}
remove(key) {
if (this.available) localStorage.removeItem(this.prefix + key);
this.memoryFallback.delete(this.prefix + key);
}
cleanup() {
if (!this.available) return;
for (const key of Object.keys(localStorage)) {
if (!key.startsWith(this.prefix)) continue;
const raw = localStorage.getItem(key);
if (!raw) continue;
try {
const item = JSON.parse(raw);
if (Date.now() > item.expiry) {
localStorage.removeItem(key);
}
} catch (err) {
localStorage.removeItem(key);
}
}
}
clearAll() {
for (const key of Object.keys(localStorage)) {
if (key.startsWith(this.prefix)) localStorage.removeItem(key);
}
this.memoryFallback.clear();
}
size() {
return Object.keys(localStorage)
.filter(k => k.startsWith(this.prefix)).length;
}
}
const cache = new TTLStorage("app:");
// Cachear respuesta de API por 10 minutos
cache.set("users", [{ id: 1, name: "Alice" }], 10 * 60 * 1000);
const users = cache.get("users", []);
3. Stale-while-revalidate para respuestas de API
class SWRStorage {
constructor(prefix = "swr:") {
this.prefix = prefix;
}
set(key, value, ttlMs = 60000, staleMs = 300000) {
const item = {
value: JSON.stringify(value),
expiry: Date.now() + ttlMs,
staleUntil: Date.now() + ttlMs + staleMs
};
localStorage.setItem(this.prefix + key, JSON.stringify(item));
}
get(key) {
const raw = localStorage.getItem(this.prefix + key);
if (!raw) return { data: null, stale: false, expired: true };
try {
const item = JSON.parse(raw);
const now = Date.now();
if (now > item.staleUntil) {
localStorage.removeItem(this.prefix + key);
return { data: null, stale: false, expired: true };
}
if (now > item.expiry) {
return { data: JSON.parse(item.value), stale: true, expired: false };
}
return { data: JSON.parse(item.value), stale: false, expired: false };
} catch (err) {
localStorage.removeItem(this.prefix + key);
return { data: null, stale: false, expired: true };
}
}
}
const swr = new SWRStorage();
swr.set("config", { theme: "dark" }, 60000, 300000);
async function getConfig() {
const { data, stale, expired } = swr.get("config");
if (expired) {
const fresh = await fetch("/api/config").then(r => r.json());
swr.set("config", fresh, 60000, 300000);
return fresh;
}
if (stale) {
// Servir lo que hay, refrescar en segundo plano
fetch("/api/config")
.then(r => r.json())
.then(fresh => swr.set("config", fresh, 60000, 300000));
return data;
}
return data;
}
El usuario ve la configuración de la sesión anterior al instante mientras una copia fresca carga a sus espaldas; ese es el patrón cache-aside aplicado al almacenamiento del navegador, y la versión del lado del servidor funciona igual.
SWRStorage es minimalista a propósito — en producción hereda las mismas defensas que TTLStorage: el probe de disponibilidad, el respaldo en memoria y un cleanup() acotado a su propio prefijo.
4. Sincronización entre pestañas con el evento storage
// Cualquier pestaña que escriba o borre una clave avisa a las demás.
window.addEventListener("storage", (event) => {
if (!event.key || !event.key.startsWith("app:")) return;
if (event.newValue === null) {
console.log(`La clave ${event.key} se borró en otra pestaña`);
return;
}
try {
const item = JSON.parse(event.newValue);
if (item.expiry && Date.now() > item.expiry) return; // escritura expirada, ignorar
console.log(`La clave ${event.key} se actualizó en otra pestaña:`, item.value);
} catch (err) {
// No es de las nuestras
}
});
El evento storage solo salta en las otras pestañas (la que escribió no recibe nada), así que es la herramienta correcta para sincronizar estado, no para reaccionar a tus propias escrituras.
5. Limpieza periódica acotada a tu prefijo
function cleanupExpiredEntries(prefix = "ttl:") {
for (const key of Object.keys(localStorage)) {
if (!key.startsWith(prefix)) continue; // nunca tocar claves ajenas
const raw = localStorage.getItem(key);
if (!raw) continue;
try {
const item = JSON.parse(raw);
if (item.expiry && Date.now() > item.expiry) {
localStorage.removeItem(key);
}
} catch (err) {
// Entrada corrupta o ajena bajo nuestro prefijo — fuera
localStorage.removeItem(key);
}
}
}
window.addEventListener("DOMContentLoaded", () => cleanupExpiredEntries("app:"));
Olvida la versión con setInterval salvo que la página pase horas abierta de verdad (un dashboard, un kiosco); en cargas normales la limpieza perezosa dentro de get() ya hace el trabajo.
Cómo Funciona
El truco está en el envoltorio de metadatos: en lugar de guardar el valor a secas, guardas { value, expiry }. Cada lectura compara Date.now() con expiry, y si ya pasó la entrada se borra sola y reporta un miss. Es expiración perezosa: nada escanea el storage hasta que una lectura o un cleanup() explícito lo toca.
Algunos detalles que importan en producción:
- Doble serialización: la clase convierte el valor a JSON dentro del envoltorio, así que
set("n", 0)yset("x", null)sobreviven el viaje de ida y vuelta sin chocar con tu lógica de fallback. - Valida el payload que lees. Si un deploy anterior —u otra librería del mismo origen— escribió un valor a secas bajo tus claves,
item.expiryllega comoundefined,Date.now() > undefinedesfalsey la entrada se trata como fresca para siempre mientras devuelveitem.valueenundefined. Untypeof item.expiry === "number"enget()convierte esas entradas ajenas en misses limpios quecleanup()puede borrar. - JSON decide qué puedes guardar: un
Datevuelve como string ISO, yMap,Set,undefinedy funciones se pierden o quedan mutilados porJSON.stringify. Quédate con datos planos —objetos, arrays, números, strings, booleanos— o serializa los tipos ricos tú mismo. - Pon prefijo a todo (
app:useren lugar deuser) porque mantiene la limpieza barata, evita colisiones con otro código del origen y deja que los eventosstoragefiltren rápido. - Prueba una vez y confía en la bandera:
checkAvailable()escribe y borra una clave de prueba al construirse. Cuando falla, la clase cambia en silencio el storage por unMapen memoria, así que la caché sigue funcionando mientras viva la página y solo deja de sobrevivir a una recarga. Es el intercambio correcto para el modo privado: persistencia degradada antes que una feature rota. - Ojo con el reloj:
Date.now()sigue el reloj del sistema del usuario, así que si lo adelanta las entradas expiran antes y si lo atrasa viven más. Para “30 minutos de tiempo real transcurrido” no hay arreglo dentro de localStorage; mantén los TTL lo bastante cortos para que la deriva no duela. - Los eventos
storagesolo saltan entre pestañas, así que las escrituras de la pestaña A llegan a las pestañas B y C, lo que viene bien para invalidar una entrada de caché compartida. Si necesitas mensajería rica entre pestañas y no solo invalidación,BroadcastChanneles la API más limpia, aunque no te avisa cuando otra pestaña borra una clave como sí lo hacestorage.
Variantes
| Enfoque | Complejidad | Características | Cuándo |
|---|---|---|---|
| Wrapper TTL básico | Baja | Set/get/remove con expiración | Caché simple, prototipos |
| Clase TTLStorage | Media | Reintento de cuota, limpieza, prefijo, respaldo en memoria | Apps en producción |
| Patrón SWR | Media | Sirve stale + refresco en segundo plano | Caché de respuestas de API |
Sync con evento storage | Media | Invalidación entre pestañas | Apps multi-pestaña |
| sessionStorage + TTL | Baja | Los mismos wrappers, muere con la pestaña | Caché por sesión |
Para sessionStorage, cambia localStorage por sessionStorage en cualquiera de los wrappers; la API es idéntica y solo cambia la vida útil.
Buenas prácticas
- Guarda siempre un timestamp
expiry; un valor a secas persiste para siempre. - Pon prefijo a las claves; la limpieza, el
clear()y los eventosstoragedependen de ello. - Envuelve
setItementry/catch: el modo privado y la cuota llena lanzan error. - Expira perezosamente al leer; añade
cleanup()al cargar solo en apps que acumulan muchas claves. - Nunca guardes tokens ni datos personales; cualquier script del origen (incluidos los inyectados) puede leer localStorage.
- Mantén los TTL realistas, ya que un TTL de 30 días es una caché que en la práctica nunca expira.
- Prefiere SWR para datos que la UI puede pintar viejos; prefiere TTL duro para lo que no debe verse desactualizado.
Errores Comunes
localStorage.clear()como reset. Borra todas las claves del origen; tu feature acaba de borrar los datos de otra. Limpia solo tu prefijo.setItemsintry/catch. El modo privado de Safari y la cuota llena lanzan error; sin manejar, la escritura rompe la feature.- Guardar el valor sin metadatos. Dentro de seis meses no vas a distinguir una entrada de caché de un typo.
- Parsear sin fallback.
JSON.parsesobre una entrada corrupta lanza error; borra la clave y sigue. - Limpiar por todo el origen. Un bucle de limpieza que ignora prefijos va a parsear (y borrar) claves que no son suyas.
- Tratar la expiración como garantía. La entrada sigue en disco hasta que algo la lee o corre la limpieza; expirada no es lo mismo que borrada.
Lecturas Relacionadas
Preguntas frecuentes
¿Cuántos datos puedo guardar en localStorage?
La mayoría de los navegadores permite 5-10 MB por origen, y el límite cuenta caracteres UTF-16, no bytes, así que el JSON cargado de emojis cuesta el doble. Maneja QuotaExceededError y mantén las entradas de caché pequeñas; cualquier cosa más voluminosa va a IndexedDB.
¿Debería usar localStorage o sessionStorage?
localStorage para lo que debe sobrevivir a la pestaña (respuestas cacheadas, preferencias). sessionStorage para lo ligado a la visita (borradores de formularios, estado de un asistente puntual). Los wrappers TTL de aquí funcionan con ambos; es cambiar una línea.
¿Qué pasa en modo de navegación privada?
Safari históricamente lanzaba QuotaExceededError en cada escritura; los navegadores modernos permiten una cuota pequeña. En cualquier caso, asume que las escrituras pueden fallar; el patrón checkAvailable() + Map en memoria de arriba mantiene la app funcionando, solo pierdes persistencia.
¿Puedo usar IndexedDB en su lugar?
Sí, y pasados unos cientos de KB deberías. IndexedDB te da queries de verdad, transacciones y cientos de MB; a cambio aceptas una API asíncrona y bastante más código. localStorage-con-TTL es el tamaño correcto para caché clave-valor simple.
¿Una entrada expirada se borra automáticamente?
No. La expiración perezosa significa que la entrada se borra la próxima vez que get() la toca (o cuando corre cleanup()). Si necesitas garantías duras de que un dato no quede en disco, localStorage es el almacén equivocado; ese dato no debería escribirse en el cliente.
¿Cómo mantengo las pestañas sincronizadas cuando expira una clave?
Escuchando el evento storage (ejemplo 4): cuando la pestaña A borra o sobrescribe una clave, todas las demás pestañas abiertas reciben el evento y pueden soltar su copia en memoria o re-renderizar.
Recursos Relacionados
Patrón Cache-Aside
Carga datos en el caché bajo demanda desde el almacenamiento principal. Un patrón de caché que da a la aplicación control total sobre qué y cuándo cachear.
RecipeService Worker Offline Caching para PWA en JavaScript
Sirve tu aplicación web sin conexión con Service Workers y la Cache API: precaché, estrategias de caché en runtime y página de respaldo.
RecipeCache multi-nivel con L1 en memoria y L2 en Redis
Reduce los round-trips a Redis en claves calientes: L1 en memoria para lecturas en microsegundos, L2 en Redis para estado compartido e invalidación por pub/sub entre instancias
GuideGuía Completa de Invalidación de Caché
Estrategias de invalidación de caché: TTL, invalidación por eventos, claves versionadas, purgado por tags, write-through, multi-nivel y consistencia.
GuideGuía Completa de Caching a Nivel Aplicación
Cachés en memoria, distribuidas e híbridas en la capa de aplicación: LRU, TTL, estrategias multi-tier, dimensionado y patrones de invalidación.
RecipeConfigurar headers HTTP Cache-Control para APIs y assets
Establece headers Cache-Control, ETag y Last-Modified para controlar la caché de navegadores y CDN en respuestas de API y assets estáticos