first commit

docs/persistence/cache/cache-storage/src/registry-augment/registry-augment.md

@@ -0,0 +1,63 @@
+# registry-augment
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Augments the `CacheProviderRegistry` type exported by `@suaveplan/cache` with a `storage` entry, and side-effect-registers `StorageCache` as the implementation behind that key on the shared `CacheFactory`. Importing this module — directly or transitively via the package root — is enough; the registration is idempotent and survives repeated imports or duplicate package versions resolving to the same singleton registry.
+
+## Features
+
+- TypeScript-side module augmentation makes `createCache("storage", config)` type-safe — the registry key is part of `CacheProviderType`, and the config parameter is inferred from `StorageCacheOptions<T>` (via the registry slot).
+- Idempotent runtime registration — guarded by both an internal `registered` flag and a `hasCacheProvider("storage")` query against the live registry, so double-import never throws or overwrites.
+- Side-effect import — the `registry-augment.ts` module is listed in `"sideEffects"` in `package.json` so bundlers preserve the registration call when the rest of the package is tree-shaken.
+
+## Usage: Basic Example
+
+```ts
+// Side-effect import: registers the "storage" provider.
+import "@suaveplan/cache-storage";
+
+import { createCache } from "@suaveplan/cache";
+import { MemoryStorage } from "@suaveplan/storage/memory";
+
+const cache = createCache("storage", { storage: new MemoryStorage() });
+```
+
+## Usage: Advanced Example
+
+```ts
+// Manually drive registration — useful in tests that need to control the
+// order of provider availability or want to confirm idempotency.
+import {
+  hasCacheProvider,
+  unregisterCacheProvider,
+} from "@suaveplan/cache";
+import { registerStorageProvider } from "@suaveplan/cache-storage";
+
+unregisterCacheProvider("storage");
+registerStorageProvider();
+console.log(hasCacheProvider("storage")); // true
+```
+
+## API Reference
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `registerStorageProvider()` | function | Idempotently calls `registerCacheProvider("storage", StorageCache)`. Safe to invoke repeatedly. |
+
+The module also performs module augmentation:
+
+```ts
+declare module "@suaveplan/cache" {
+  interface CacheProviderRegistry {
+    storage: typeof StorageCache;
+  }
+}
+```
+
+## Implementation Notes
+
+The `registered` module-local flag is set even when the registry already contained the provider (e.g. because another package version registered it first). That ensures the second branch is exercised at most once per module instance and that subsequent calls hit the fast path. The function is exported so test suites can drive it explicitly after a `clearCacheProviders()` call without re-importing the package.