suaveplan/packages/persistence/storage/storage-plugin-cache/README.md

@suaveplan/storage-plugin-cache - Read-through cache decorator for AbstractStorage. Wraps any @suaveplan/storage with an injectable AbstractCache; hit/miss/populate on get, invalidate-on-write/setPartial/delete/clear, namespaced isolation, full OTel surface, cache failures swallow with stats.

Read-through cache decorator for AbstractStorage. Wraps any @suaveplan/storage instance with an injectable AbstractCache<Uint8Array>; hit/miss/populate on get, invalidate on every set / setPartial / delete / clear. Namespaced isolation so two wrappers can share one cache. Full OpenTelemetry surface (storage_cache.* counters, entry_bytes histogram, per-op spans). Cache failures swallow with stats so a flaky cache never breaks a read.

This is the structural inverse of @suaveplan/cache-storage, which turns any AbstractStorage into a cache backend. Here we turn any AbstractCache into a front of a storage.

Documentation tree

• cached-storage — CachedStorage is a read-through cache decorator that extends AbstractStorage from @suaveplan/storage. It wraps an…
  • cached-storage.clear — This module owns the CachedStorage.clear path. The wrapper SHALL first delegate to inner.clear(signal) (so the sour…
  • cached-storage.context — This module defines the CachedStorageContext shape that the per-method helper files (cached-storage.get.ts, `cached…
  • cached-storage.delete — This module owns the delete-through path of CachedStorage.delete. The wrapper forwards the deletion to the inner stor…
  • cached-storage.get — This module owns the read-through path of CachedStorage.get(key, signal?). The implementation first consults the inje…
  • cached-storage — CachedStorage is a read-through cache decorator that extends AbstractStorage from @suaveplan/storage. It wraps an…
  • cached-storage.passthrough — This module owns the passthrough surface of CachedStorage — every abstract method on AbstractStorage that does NOT…
  • cached-storage.signal — This helper centralises the wrapper's policy for a pre-aborted AbortSignal: every public method that takes a signal M…
  • cached-storage.write — This module owns the write-through path of CachedStorage.set and CachedStorage.setPartial. Both ops invoke the inne…
• error-codes — This module owns the canonical registry of error codes raised by @suaveplan/storage-plugin-cache. The package deliber…
  • error-codes — This module owns the canonical registry of error codes raised by @suaveplan/storage-plugin-cache. The package deliber…
• factory — This module exports the cachedStorage(inner, options) factory — a thin convenience over `new CachedStorage(inner, opt…
  • factory — This module exports the cachedStorage(inner, options) factory — a thin convenience over `new CachedStorage(inner, opt…
• otel — This module wires the OpenTelemetry meter and tracer used by every CachedStorage instance. The wrapper emits five cou…
  • otel — This module wires the OpenTelemetry meter and tracer used by every CachedStorage instance. The wrapper emits five cou…

Modules

• ./error-codes — STORAGE_CACHE_CODES (INVALID_OPTIONS, INNER_MISSING), CachedStorageError.
• ./types — CachedStorageOptions, CachedStorageStats, ResolvedCachedStorageOptions, CachedStorageErrorOp.
• ./cached-storage — CachedStorage extends AbstractStorage, per-method helpers split across .get.ts, .write.ts, .delete.ts, .clear.ts, .passthrough.ts, .signal.ts.
• ./factory — cachedStorage(inner, options): CachedStorage factory.
• ./otel — meter + tracer wiring, recordHit / recordMiss / recordPopulate / recordInvalidate / recordError, setStorageCacheMeterProvider, resetInstruments.

Quick start

import { cachedStorage } from "@suaveplan/storage-plugin-cache";
import { MemoryCache } from "@suaveplan/cache";
import { createHttpStorage } from "@suaveplan/storage-http";

const inner = createHttpStorage({ baseUrl: "https://cdn.example.com/" });
const cache = new MemoryCache<Uint8Array>();
const storage = cachedStorage(inner, { cache, namespace: "media" });

const bytes = await storage.get("clip.mov");          // miss → inner → populate
const again = await storage.get("clip.mov");          // hit (no inner call)
await storage.set("clip.mov", new Uint8Array([1]));   // inner.set + invalidate

Composition recipes

1. Memory cache in front of HTTPS (hot keys)

import { cachedStorage } from "@suaveplan/storage-plugin-cache";
import { MemoryCache } from "@suaveplan/cache";
import { createHttpStorage } from "@suaveplan/storage-http";

const inner = createHttpStorage({ baseUrl: "https://cdn.example.com/" });
const cache = new MemoryCache<Uint8Array>();
const storage = cachedStorage(inner, { cache, namespace: "media" });

2. File-backed cache in front of HTTPS (cross-process durable)

import { cachedStorage } from "@suaveplan/storage-plugin-cache";
import { createCache } from "@suaveplan/cache";
import { createNodeFsStorage } from "@suaveplan/storage-file";
import { createHttpStorage } from "@suaveplan/storage-http";

const inner = createHttpStorage({ baseUrl: "https://cdn.example.com/" });
const fileBackend = createNodeFsStorage({ rootDir: "/var/cache/cdn" });
const cache = createCache("storage", { storage: fileBackend });
const storage = cachedStorage(inner, { cache, namespace: "cdn-prod" });

3. CDN with namespace isolation

// Two wrappers sharing one cache instance, distinct namespaces,
// distinct inner storages — neither wrapper sees the other's entries
// on get, and `wrapperA.clear()` does not evict wrapperB's entries.
const cache = new MemoryCache<Uint8Array>();
const wrapperA = cachedStorage(innerA, { cache, namespace: "a" });
const wrapperB = cachedStorage(innerB, { cache, namespace: "b" });

4. Redis cache in front of S3 (cross-process shared)

import { createRedisCache } from "@suaveplan/cache-redis";

const inner = new S3Storage({ /* … */ });
const cache = createRedisCache({ client, prefix: "media-cache:" });
const storage = cachedStorage(inner, { cache, namespace: "media" });

5. Stale-while-revalidate via cache.wrap()

const storage = cachedStorage(inner, { cache });

// Expose the underlying cache for direct wrap()-based SWR:
const bytes = await storage.cache.wrap(
 `storage::clip.mov`,
 () => storage.inner.get("clip.mov"),
 { staleAge: 60_000 },
);

6. Composed with storage-uri / drive — the wrapper is just an AbstractStorage

import { createStorageUriResolver, fileUriPlugin } from "@suaveplan/storage-uri";

const cachedFile = cachedStorage(
 createNodeFsStorage({ rootDir: "/var/media" }),
 { cache },
);
const resolver = createStorageUriResolver([
 fileUriPlugin({ rootDir: "/var/media", storage: cachedFile }),
]);

Options

Option	Default	Notes
cache	(required)	An AbstractCache<Uint8Array> instance — MemoryCache, StorageCache, createRedisCache, etc.
namespace	"storage"	Prefix applied to every cache key (${namespace}::${key}). Distinct namespaces isolate two wrappers on a shared cache.
invalidateOnWrite	true	When false, set/setPartial do NOT evict the cache entry — application owns the invalidation.
invalidateOnDelete	true	When false, delete does NOT evict.
invalidateOnClear	true	When false, clear does NOT walk the cache's namespace.
shouldCache(key, bytes)	bytes.byteLength <= maxEntryBytes	Predicate gating cache population on miss.
maxEntryBytes	16 * 1024 * 1024 (16 MiB)	Used by the default shouldCache. Matches drive-mesh-protocol's frame ceiling and drive-plugin-cache's entry ceiling.
logger	undefined	LoggerLike used to warn when clear() can't enumerate the cache.

Relationship to siblings

• @suaveplan/cache-storage — the structural inverse: turns any AbstractStorage into a cache backend. Use that one when you want to plug a file/S3/redis storage into the createCache("storage") factory. Use this one when you want to put a cache in front of a storage to accelerate get.
• add-drive-plugin-cache — the drive-tier twin: caches reassembled plaintext at the drive middleware layer. Same option shape, same OTel naming, same error-swallow contract. Use the drive wrapper for plaintext-after-chunk-reassembly, use this one for the raw storage bytes underneath.
• Future cacheUriPlugin — a planned URI-tier wrapper that composes with @suaveplan/storage-uri to cache across URI schemes. This package's invalidation surface intentionally stops at the storage tier; URI-level caching belongs there.

Errors

Code	When
STORAGE_CACHE.INNER_MISSING	Constructor / factory called with nullish inner.
STORAGE_CACHE.INVALID_OPTIONS	Constructor / factory called without a valid cache (missing, wrong shape, missing get/set/delete).

Every other failure mode flows through with its original namespaced code (STORAGE.*, STORAGE_HTTP.*, CACHE.*).

Cache failures never propagate

A cache.get / cache.set / cache.delete rejection is logged through the OTel storage_cache.errors_total{namespace, op} counter and bumped on getCacheStats().errors, but the wrapper's own surface NEVER throws because the cache misbehaved. A failed cache.get falls through to inner.get; a failed cache.set still returns the inner-read bytes; a failed cache.delete on invalidation still returns the inner-write/delete result.