mongez-cache

Build custom cache backends by extending `BaseCacheEngine` — IndexedDB, cookies, remote stores — and override `convertValue` / `parseValue` or `set` / `get` when the envelope shape needs to change. TRIGGER when: code declares `class X extends BaseCacheEngine` or imports `BaseCacheEngine` from `@mongez/cache`; user asks "how do I build a custom cache driver", "how do I back the cache with IndexedDB / cookies", or "how do I override the `{data, expiresAt}` envelope / serialization"; `import { BaseCacheEngine } from "@mongez/cache"`. SKIP: picking among the shipped drivers — use `mongez-cache-drivers`; in-memory runtime driver — use `mongez-cache-runtime`; encrypted drivers — use `mongez-cache-encryption`; everyday `cache.set` / `cache.get` usage — use `mongez-cache-basic-usage`.

Reference for `EncryptedLocalStorageDriver` and `EncryptedSessionStorageDriver` — class signatures, wiring an encrypt/decrypt pair via `setCacheConfigurations`, key rotation through `getCacheConfig("encryption")`, bringing-your-own encryptor, TTL via the `{data, expiresAt}` envelope, and legacy-cypher compatibility. TRIGGER when: code imports `EncryptedLocalStorageDriver` or `EncryptedSessionStorageDriver` from `@mongez/cache`; user asks "how do encrypted cache drivers work", "what's the encryption pair contract", or "how does TTL work on encrypted entries"; `import { EncryptedLocalStorageDriver } from "@mongez/cache"`. SKIP: full step-by-step encrypted setup with `@mongez/encryption` and atom adapters — use `mongez-cache-encrypted-cache`; plain (unencrypted) drivers — use `mongez-cache-local-storage` / `mongez-cache-session-storage`; daily `cache.set` / `cache.get` usage — use `mongez-cache-basic-usage`.

Reference for `PlainLocalStorageDriver` — `window.localStorage` backend, `{data, expiresAt}` JSON envelope, TTL behavior, corruption recovery, prefix handling, SSR caveats, and localStorage quota gotchas. TRIGGER when: code calls `new PlainLocalStorageDriver()` or imports `PlainLocalStorageDriver` from `@mongez/cache`; user asks "how do I persist cache across reloads", "what's the on-disk format for `@mongez/cache`", or "how do I handle the localStorage quota / SSR"; `import { PlainLocalStorageDriver } from "@mongez/cache"`. SKIP: tab-scoped storage — use `mongez-cache-session-storage`; in-memory ephemeral cache — use `mongez-cache-runtime`; encrypted-at-rest variant — use `mongez-cache-encryption` or `mongez-cache-encrypted-cache`; choosing among all drivers at once — use `mongez-cache-drivers`.

Reference for the `CacheManager` facade, the default `cache` singleton, and config helpers — `setCacheConfigurations`, `getCacheConfigurations`, `getCacheConfig`, `setDriver` / `getDriver`, `setPrefixKey`, plus building sibling managers with distinct prefixes / backends. TRIGGER when: code imports `cache` (default), `CacheManager`, `setCacheConfigurations`, `getCacheConfigurations`, or `getCacheConfig` from `@mongez/cache`; user asks "how do I bootstrap `@mongez/cache`", "how do I hot-swap the driver", or "how do I have two cache managers side by side"; `import cache, { CacheManager } from "@mongez/cache"`. SKIP: per-driver options (`PlainLocalStorageDriver` etc.) — use `mongez-cache-drivers`; daily `cache.set` / `cache.get` / `cache.has` calls — use `mongez-cache-basic-usage`; encrypted setup — use `mongez-cache-encryption` / `mongez-cache-encrypted-cache`; building a custom backend — use `mongez-cache-custom-drivers`.

Idiomatic composition recipes — boot-time `setCacheConfigurations`, multi-app prefix namespacing, short-TTL caches for derived data, encrypted-token storage, sibling `CacheManager` instances, SSR fallback to `RunTimeDriver`, persisting `@mongez/atom` via a `cacheAdapter`, mixing plain + encrypted adapters per atom, and wrapping the cache to emit write events. TRIGGER when: user asks "show me an end-to-end `@mongez/cache` example", "how do I persist `@mongez/atom` atoms with `@mongez/cache`", "how do I namespace multiple apps on one domain", "how do I subscribe to cache writes", or "how do I do SSR with `@mongez/cache`"; pull-in pattern: `import { createAtom } from "@mongez/atom"` alongside `import cache from "@mongez/cache"`. SKIP: bare API surface of a single function or driver — use `mongez-cache-basic-usage`, `mongez-cache-manager`, or the per-driver skills; building a brand-new driver — use `mongez-cache-custom-drivers`; first-time discovery of the package — use `mongez-cache-overview`.

Reference for `RunTimeDriver` — the in-memory `Record<string, {value, expiresAt?}>` driver used for tests, SSR fallback, and ephemeral page-lifetime state, including its overridden `getItem` / `setItem` / `convertValue` / `parseValue` and the `has(missingKey)` semantics. TRIGGER when: code calls `new RunTimeDriver()` or imports `RunTimeDriver` from `@mongez/cache`; user asks "how do I get an in-memory cache for tests", "how do I make cache SSR-safe in Node", or "how does `has()` behave for missing keys"; `import { RunTimeDriver } from "@mongez/cache"`. SKIP: localStorage-backed persistence — use `mongez-cache-local-storage`; tab-scoped storage — use `mongez-cache-session-storage`; encrypted drivers — use `mongez-cache-encryption`; building a brand-new backend — use `mongez-cache-custom-drivers`.

Pitch, install, mental model, and the full public surface of `@mongez/cache` — the `cache` singleton, `CacheManager`, `BaseCacheEngine`, the plain / encrypted / runtime drivers, configuration helpers (`setCacheConfigurations`, `getCacheConfigurations`, `getCacheConfig`), and `CacheDriverInterface` / `CacheManagerInterface` / `CacheConfigurations` types. TRIGGER when: a new file pulls in `@mongez/cache` for the first time or runs `yarn add @mongez/cache`; user asks "what is `@mongez/cache`", "should I use this over raw `localStorage`", or "what drivers ship with `@mongez/cache`"; `import cache, { ... } from "@mongez/cache"`. SKIP: deep dives on a specific driver — use `mongez-cache-local-storage`, `mongez-cache-session-storage`, `mongez-cache-runtime`, or `mongez-cache-encryption`; bootstrap / configuration mechanics — use `mongez-cache-manager` or `mongez-cache-drivers`; copy-paste recipes — use `mongez-cache-recipes`.

Using the `cache` singleton — `set`, `get`, `remove`, `clear`, `has`, per-call/global TTL, key prefixing, and the `@mongez/atom` `persist` adapter pattern. TRIGGER when: code calls `cache.set`, `cache.get`, `cache.has`, `cache.remove`, `cache.clear`, `getCacheConfigurations`, or `getCacheConfig` from `@mongez/cache`; user asks "how do I write/read/expire/remove a cache entry" or "how do I wire `@mongez/cache` into `@mongez/atom`'s `persist` slot"; `import cache, { setCacheConfigurations } from "@mongez/cache"`. SKIP: configuring or swapping drivers themselves — use `mongez-cache-drivers` or `mongez-cache-manager`; encrypted at-rest reads/writes — use `mongez-cache-encrypted-cache` or `mongez-cache-encryption`; building a custom backend — use `mongez-cache-custom-drivers`.

Configure each shipped `@mongez/cache` driver — `PlainLocalStorageDriver`, `PlainSessionStorageDriver`, `RunTimeDriver` — with `setCacheConfigurations`, including prefix, global TTL, custom serialization (`valueConverter` / `valueParer`), and SSR-safe selection. TRIGGER when: code calls `setCacheConfigurations`, `new PlainLocalStorageDriver`, `new PlainSessionStorageDriver`, `new RunTimeDriver`, `setValueConverter`, or `setValueParser` from `@mongez/cache`; user asks "how do I pick a cache driver", "how do I set a prefix or default TTL", or "how do I make cache SSR-safe"; `import { setCacheConfigurations, ... } from "@mongez/cache"`. SKIP: encrypted driver setup (`EncryptedLocalStorageDriver` / `EncryptedSessionStorageDriver`) — use `mongez-cache-encryption` or `mongez-cache-encrypted-cache`; extending `BaseCacheEngine` for IndexedDB/cookies — use `mongez-cache-custom-drivers`; daily `cache.set` / `cache.get` usage — use `mongez-cache-basic-usage`.

End-to-end setup for `EncryptedLocalStorageDriver` and `EncryptedSessionStorageDriver` — wiring `@mongez/encryption` (or a custom encrypt/decrypt pair), key rotation, prefix, TTL behavior, and persisting `@mongez/atom` with encrypted storage at rest. TRIGGER when: code imports `EncryptedLocalStorageDriver` or `EncryptedSessionStorageDriver` from `@mongez/cache`, or passes `encryption: { encrypt, decrypt }` to `setCacheConfigurations`; user asks "how do I encrypt cached tokens / PII", "how do I integrate `@mongez/encryption` with `@mongez/cache`", or "how do I rotate the cache encryption key"; `import { encrypt, decrypt } from "@mongez/encryption"` alongside cache imports. SKIP: pure driver reference (signatures, known TTL bug) — use `mongez-cache-encryption`; plain (unencrypted) localStorage / sessionStorage drivers — use `mongez-cache-local-storage` / `mongez-cache-session-storage`; daily `cache.set` / `cache.get` usage — use `mongez-cache-basic-usage`.

Reference for `PlainSessionStorageDriver` — tab-scoped `window.sessionStorage` backend with the same envelope, TTL, prefix, and corruption-recovery semantics as the localStorage driver; data survives refresh but not tab close. TRIGGER when: code calls `new PlainSessionStorageDriver()` or imports `PlainSessionStorageDriver` from `@mongez/cache`; user asks "how do I cache scroll position / draft form data per tab", "how do I make a wizard remember progress through refreshes only", or "how do I use sessionStorage with `@mongez/cache`"; `import { PlainSessionStorageDriver } from "@mongez/cache"`. SKIP: cross-session persistence — use `mongez-cache-local-storage`; in-memory only cache — use `mongez-cache-runtime`; encrypted variant of session storage — use `mongez-cache-encryption` or `mongez-cache-encrypted-cache`; choosing among all drivers — use `mongez-cache-drivers`.