Skip to content
Mongez — production TypeScript packages Mongez

Cache

One cache API, swappable drivers. Pick a backend at boot — localStorage, sessionStorage, in-memory map, opt-in IndexedDB, or any of those with encryption layered on — then call cache.set / cache.get / cache.remove / cache.clear everywhere else. Every storage-touching method is async. TTL, key prefixing, and default-fallbacks built in. Pairs cleanly with @mongez/atom’s persist slot.

Highlighted features

One async API, seven drivers

Plain + encrypted variants for localStorage / sessionStorage / IndexedDB, plus a runtime in-memory driver. Configure once; swap drivers without touching call sites.

Per-entry TTL

await cache.set(“token”, value, 60 * 15) — entries expire on read after their TTL. Or set a default for every key via configuration.

Encryption-at-rest

EncryptedLocalStorageDriver / EncryptedSessionStorageDriver / EncryptedIndexedDBDriver run values through your encrypt/decrypt pair before writing. Sensitive cache values stay opaque on disk.

Opt-in IndexedDB

IndexedDBDriver / EncryptedIndexedDBDriver for structured values and quotas beyond ~5MB. Never wired up by default — construct one explicitly.

Key prefixing

prefix: “shop-” namespaces every key so multiple apps on the same domain can’t collide. Set once at config time.

Pairs with @mongez/atom

Any driver satisfies the async PersistAdapter shape — drop it into an atom’s persist slot and the atom hydrates from cache + writes through on update.

Install

Terminal window
npm install @mongez/cache

Requires Node >=20. @mongez/encryption (^2.0.0) is an optional peer — install only when using the Encrypted* drivers.

Quick peek

import cache, { PlainLocalStorageDriver, setCacheConfigurations } from "@mongez/cache";


setCacheConfigurations({
  driver: new PlainLocalStorageDriver(),
  prefix: "shop-",          // namespace every key
  expiresAfter: 60 * 60,    // optional default TTL: 1 hour
});


await cache.set("user", { id: 1, name: "Hasan" });
await cache.set("token", "abc123", 60 * 15);   // override the default TTL
await cache.get("user");                        // { id: 1, name: "Hasan" }

Pick a backend at boot, then use the same async API everywhere.

Available drivers

DriverPersistenceNotes
PlainLocalStorageDriverCross-sessionJSON-serialised; supports TTL envelope
PlainSessionStorageDriverTab-lifetimeSame contract as local-storage variant
EncryptedLocalStorageDriverCross-sessionEncrypt/decrypt before writing
EncryptedSessionStorageDriverTab-lifetimeEncrypted sessionStorage variant
RunTimeDriverIn-memory (lost on reload)SSR-safe; no Web Storage dependency
IndexedDBDriver (opt-in)Cross-sessionStructured clone (no JSON pass); larger quota
EncryptedIndexedDBDriver (opt-in)Cross-sessionIndexedDB + encrypted envelope

All drivers implement the same async CacheDriverInterface — set / get / has / remove / clear / keys / getAll.

Key pitfalls

  • setCacheConfigurations must be called before first use. The singleton’s driver is undefined until you call it; cache.set(...) before configuring throws.
  • Every storage-touching method returns a Promise. Even the synchronous-under-the-hood drivers (Web Storage, RunTimeDriver) resolve immediately rather than returning the value directly — await is required as of 2.0.0.
  • Web Storage drivers throw on the server (no localStorage in Node). Gate driver selection with typeof window === "undefined" and fall back to RunTimeDriver for SSR paths.
  • RunTimeDriver instances are not shared. Two instances have independent stores; no global in-memory registry.
  • IndexedDB is never the default. Nothing constructs IndexedDBDriver for you — opt in explicitly via setCacheConfigurations({ driver: new IndexedDBDriver() }).

Where to go next