89 lines
5.0 KiB
Markdown
89 lines
5.0 KiB
Markdown
# @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. |
|
|
|