first commit

docs/persistence/cache/cache-storage/README.md

@@ -0,0 +1,88 @@
+# @suaveplan/cache-storage - AbstractCache backend that bridges any @suaveplan/storage AbstractStorage into a typed cache via a 32-byte fixed-width TTL header and pluggable Codec<T> (JSON default, identity for Uint8Array).
+
+`AbstractCache<T>` backend that bridges any `@suaveplan/storage` `AbstractStorage` into a typed cache via a 32-byte fixed-width TTL header and pluggable `Codec<T>` (JSON default, identity for `Uint8Array`).
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [identity](./src/codec/identity.md) — `IdentityCodec` is the `Codec<Uint8Array>` implementation that passes bytes through without encoding overhead. Use it w…
+- [json](./src/codec/json.md) — `JsonCodec<T>` is the default codec for `StorageCache`. It serialises arbitrary JSON-compatible values to UTF-8 bytes v…
+- [errors](./src/errors/errors.md) — Defines the structured error surface for `@suaveplan/cache-storage`. Every failure path inside the package — corrupt bl…
+  - [errors](./src/errors/errors.md) — Defines the structured error surface for `@suaveplan/cache-storage`. Every failure path inside the package — corrupt bl…
+- [header](./src/header/header.md) — Defines the 32-byte fixed-width metadata header that `StorageCache` prepends to every cached value. The header carries…
+  - [header](./src/header/header.md) — Defines the 32-byte fixed-width metadata header that `StorageCache` prepends to every cached value. The header carries…
+- [registry-augment](./src/registry-augment/registry-augment.md) — Augments the `CacheProviderRegistry` type exported by `@suaveplan/cache` with a `storage` entry, and side-effect-regist…
+  - [registry-augment](./src/registry-augment/registry-augment.md) — Augments the `CacheProviderRegistry` type exported by `@suaveplan/cache` with a `storage` entry, and side-effect-regist…
+- [storage-cache](./src/storage-cache/storage-cache.md) — `StorageCache<T>` extends `AbstractCache<T>` from `@suaveplan/cache` and turns any `AbstractStorage` (from `@suaveplan/…
+  - [storage-cache](./src/storage-cache/storage-cache.md) — `StorageCache<T>` extends `AbstractCache<T>` from `@suaveplan/cache` and turns any `AbstractStorage` (from `@suaveplan/…
+<!-- end:auto-docs -->
+
+## Summary
+
+`@suaveplan/cache-storage` is the universal cache backend for the cache family. It composes any byte-oriented storage adapter — `MemoryStorage`, `storage-browser-localstorage`, `storage-browser-indexeddb`, `storage-browser-opfs`, `storage-file`, `storage-s3`, `storage-cdn-*` — into a typed cache with TTL, lifecycle events, namespacing, and structured errors. The package subsumes the upstream `cache-browser` package by composition: pick the storage adapter that matches your environment, and the cache surface is identical to `MemoryCache`. Side-effect import auto-registers `StorageCache` as the `"storage"` provider on `CacheFactory`, so `createCache("storage", { storage })` works after a single import.
+
+## Installation
+
+```bash
+bun add @suaveplan/cache-storage
+```
+
+## Quick Start
+
+```ts
+import { StorageCache } from "@suaveplan/cache-storage";
+import { MemoryStorage } from "@suaveplan/storage/memory";
+
+const cache = new StorageCache<{ id: string; email: string }>({
+  storage: new MemoryStorage(),
+  defaultTtl: 5 * 60_000,
+});
+
+await cache.set("user:1", { id: "1", email: "alice@example.com" });
+const user = await cache.get("user:1");
+```
+
+## Modules
+
+- [errors](./src/errors/errors.md) — `CACHE_STORAGE_CODES`, `StorageCacheError`.
+- [header](./src/header/header.md) — 32-byte fixed-width metadata header codec.
+- [codec/identity](./src/codec/identity.md) — `IdentityCodec` for `Uint8Array` values.
+- [codec/json](./src/codec/json.md) — `JsonCodec<T>` default codec.
+- [storage-cache](./src/storage-cache/storage-cache.md) — `StorageCache<T>` class.
+- [registry-augment](./src/registry-augment/registry-augment.md) — `CacheProviderRegistry` augmentation + auto-registration.
+
+## Browser-side caching (replaces `cache-browser`)
+
+```ts
+import { StorageCache } from "@suaveplan/cache-storage";
+import { LocalStorageStorage } from "@suaveplan/storage-browser-localstorage";
+
+const cache = new StorageCache<string>({
+  storage: new LocalStorageStorage(),
+  namespace: "ui:preferences",
+  defaultTtl: 7 * 24 * 60 * 60_000,
+});
+```
+
+The same pattern works over `storage-browser-indexeddb` (larger payloads) and `storage-browser-opfs` (file-grade durability).
+
+## Factory registration
+
+```ts
+import "@suaveplan/cache-storage"; // side-effect: register provider
+import { createCache } from "@suaveplan/cache";
+import { MemoryStorage } from "@suaveplan/storage/memory";
+
+const cache = createCache("storage", { storage: new MemoryStorage() });
+```
+
+## Dependencies
+
+| Dependency | Purpose |
+| --- | --- |
+| `@suaveplan/cache` | `AbstractCache<T>`, `CacheFactory`, `CacheProviderRegistry`, `CacheEvents`, `CacheSetOptions`. |
+| `@suaveplan/error` | `defineCodes`, `SuaveplanError`. |
+| `@suaveplan/storage` | `AbstractStorage` contract. |
+| `@suaveplan/types` | `EventBusLike`. |
+| `tslib` | TypeScript helpers. |
+