StackPractices
beginner Por Mathias Paulenko

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ónMejor herramienta
Tokens, credenciales, datos personalessessionStorage, memoria o cookies httpOnly — cualquier script del origen puede leer localStorage
Datos de más de unos cientos de KBIndexedDB — localStorage toca techo en ~5-10 MB y bloquea el hilo principal
Datos que necesitan transacciones o índicesIndexedDB
Caché cuya corrección depende del servidorCabeceras HTTP de caché / service worker — el reloj del cliente puede ir mal
Escrituras multi-pestaña que deben mantenerse sincronizadasEl 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

Mermaid flowchart LR diagram

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) y set("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.expiry llega como undefined, Date.now() > undefined es false y la entrada se trata como fresca para siempre mientras devuelve item.value en undefined. Un typeof item.expiry === "number" en get() convierte esas entradas ajenas en misses limpios que cleanup() puede borrar.
  • JSON decide qué puedes guardar: un Date vuelve como string ISO, y Map, Set, undefined y funciones se pierden o quedan mutilados por JSON.stringify. Quédate con datos planos —objetos, arrays, números, strings, booleanos— o serializa los tipos ricos tú mismo.
  • Pon prefijo a todo (app:user en lugar de user) porque mantiene la limpieza barata, evita colisiones con otro código del origen y deja que los eventos storage filtren 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 un Map en 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 storage solo 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, BroadcastChannel es la API más limpia, aunque no te avisa cuando otra pestaña borra una clave como sí lo hace storage.

Variantes

EnfoqueComplejidadCaracterísticasCuándo
Wrapper TTL básicoBajaSet/get/remove con expiraciónCaché simple, prototipos
Clase TTLStorageMediaReintento de cuota, limpieza, prefijo, respaldo en memoriaApps en producción
Patrón SWRMediaSirve stale + refresco en segundo planoCaché de respuestas de API
Sync con evento storageMediaInvalidación entre pestañasApps multi-pestaña
sessionStorage + TTLBajaLos mismos wrappers, muere con la pestañaCaché 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 eventos storage dependen de ello.
  • Envuelve setItem en try/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.
  • setItem sin try/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.parse sobre 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.