@chidchanun/bcp 0.2.15 → 0.2.16

package/docs/cache-platform-v2.md

@@ -0,0 +1,487 @@
+# Cache Platform v2
+
+BCP Framework `0.2.16` extends `bcp/cache` with provider-neutral asynchronous cache storage, distributed locking, cache-stampede protection, Redis-compatible adapters and metrics integration while preserving the existing request-cache and `cache()` APIs.
+
+## Compatibility
+
+The existing APIs remain available and keep their process-local behavior:
+
+```ts
+import {
+    cache,
+    dedupe,
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+```
+
+`cache()` is still useful for simple single-process data caching and `dedupe()` is still request-scoped work sharing.
+
+Use Cache Platform v2 when cached state must be shared across multiple application instances or when cache fill work needs distributed stampede protection.
+
+## Create a cache store
+
+```ts
+import {
+    createCacheStore,
+} from "bcp/cache";
+
+export const applicationCache =
+    createCacheStore();
+```
+
+Without an adapter, the store uses the built-in memory adapter.
+
+Basic operations:
+
+```ts
+await applicationCache.set(
+    "user:42",
+    {
+        id: 42,
+        name: "Bank",
+    },
+    {
+        ttlMs: 60_000,
+        tags: ["users"],
+        paths: ["/users/42"],
+    }
+);
+
+const user =
+    await applicationCache.get(
+        "user:42"
+    );
+
+await applicationCache.delete(
+    "user:42"
+);
+```
+
+## Cache adapter contract
+
+Shared cache providers implement `CacheAdapter`:
+
+```ts
+interface CacheAdapter {
+    get<T>(key: string):
+        Promise<CacheAdapterEntry<T> | null>;
+
+    set<T>(
+        key: string,
+        value: T,
+        options?: CacheAdapterSetOptions
+    ): Promise<void>;
+
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<number>;
+    revalidateTag(tag: string): Promise<number>;
+    revalidatePath(path: string): Promise<number>;
+    entries?(): Promise<number>;
+    close?(): Promise<void>;
+}
+```
+
+The built-in implementations are:
+
+```ts
+createMemoryCacheAdapter()
+createRedisCacheAdapter()
+```
+
+This contract allows another provider to be added without changing application cache usage.
+
+## TTL
+
+Cache Store v2 uses millisecond TTL values:
+
+```ts
+await applicationCache.set(
+    "dashboard:summary",
+    summary,
+    {
+        ttlMs: 30_000,
+    }
+);
+```
+
+`ttlMs: false` or an omitted TTL creates an entry without an application-level expiration.
+
+`ttlMs: 0` deletes the existing entry instead of storing a new one.
+
+The older `cache()` API continues to use `revalidate` in seconds for backward compatibility.
+
+## Tag invalidation
+
+```ts
+await applicationCache.set(
+    "user:42",
+    user,
+    {
+        tags: [
+            "users",
+            "tenant:7",
+        ],
+    }
+);
+
+await applicationCache.revalidateTag(
+    "users"
+);
+```
+
+The returned number is the count of matching entries removed by the adapter.
+
+## Path invalidation
+
+```ts
+await applicationCache.set(
+    "users-page",
+    data,
+    {
+        paths: [
+            "/dashboard/users",
+        ],
+    }
+);
+
+await applicationCache.revalidatePath(
+    "/dashboard"
+);
+```
+
+Path invalidation is hierarchical. Invalidating `/dashboard` also invalidates cached paths below `/dashboard/...`.
+
+## `getOrSet()`
+
+Use `getOrSet()` for cache-aside loading:
+
+```ts
+const user =
+    await applicationCache.getOrSet(
+        "user:42",
+        async () =>
+            databaseUser(42),
+        {
+            ttlMs: 60_000,
+            tags: ["users"],
+        }
+    );
+```
+
+Within one `CacheStore`, concurrent calls for the same key share one in-flight loader.
+
+```text
+Request A ----\
+Request B -----+--> one loader --> cache
+Request C ----/
+```
+
+This local singleflight behavior is available even without a distributed lock adapter.
+
+## Distributed stampede protection
+
+For multiple application instances, provide a shared `CacheLockAdapter`:
+
+```ts
+const applicationCache =
+    createCacheStore({
+        adapter: redisCache,
+        lock: redisLock,
+    });
+```
+
+The load flow becomes:
+
+```text
+Instance A cache miss
+        |
+        +--> acquire distributed lock
+        |        |
+        |        +--> double-check cache
+        |        +--> execute loader
+        |        +--> store result
+        |        +--> release lock
+        |
+Instance B cache miss
+        |
+        +--> lock contention
+                 |
+                 +--> poll shared cache
+                 +--> consume A's result
+```
+
+Default values:
+
+```text
+lockTtlMs      30000
+waitTimeoutMs   5000
+pollIntervalMs    25
+```
+
+Override them per operation:
+
+```ts
+await applicationCache.getOrSet(
+    "report:monthly",
+    buildReport,
+    {
+        lockTtlMs: 60_000,
+        waitTimeoutMs: 10_000,
+        pollIntervalMs: 50,
+    }
+);
+```
+
+## Lock heartbeat
+
+If the selected lock adapter implements `extend()`, BCP renews the acquired load lock while the loader is still active. The renewal interval is approximately one third of `lockTtlMs`.
+
+This reduces duplicate work when a legitimate load takes longer than the original lease.
+
+A process crash can still let the lease expire, which is intentional: another process must eventually be able to recover and refill the cache.
+
+## Lock timeout policy
+
+The default timeout behavior is availability-oriented. If a process waits for another lock owner but still cannot acquire the lock after the timeout, it executes the loader rather than blocking indefinitely.
+
+For workloads where duplicate computation is worse than a failed request:
+
+```ts
+await applicationCache.getOrSet(
+    "expensive-model",
+    buildModel,
+    {
+        onLockTimeout: "error",
+    }
+);
+```
+
+This throws instead of running an unlocked fallback loader.
+
+## Memory lock adapter
+
+Tests and single-process deployments can use:
+
+```ts
+import {
+    createMemoryCacheAdapter,
+    createMemoryCacheLockAdapter,
+} from "bcp/cache";
+
+const adapter =
+    createMemoryCacheAdapter();
+const lock =
+    createMemoryCacheLockAdapter();
+```
+
+Multiple `CacheStore` instances can share these objects during tests to exercise cross-store contention behavior deterministically.
+
+## Redis-compatible cache adapter
+
+BCP does not install or own a Redis library.
+
+Provide a minimal command client:
+
+```ts
+interface RedisCacheCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
+```
+
+Example adapter wiring:
+
+```ts
+import {
+    createCacheStore,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+} from "bcp/cache";
+
+const redisCache =
+    createRedisCacheAdapter({
+        client: redisClient,
+    });
+
+const redisLock =
+    createRedisCacheLockAdapter({
+        client: redisClient,
+    });
+
+export const cache =
+    createCacheStore({
+        adapter: redisCache,
+        lock: redisLock,
+    });
+```
+
+The default namespace is:
+
+```text
+bcp:{cache}
+```
+
+The `{cache}` hash tag keeps the reference adapter's related keys in one Redis Cluster slot for its Lua state transitions.
+
+When overriding the namespace for Redis Cluster, keep a hash tag, for example:
+
+```text
+my-app:{cache}
+```
+
+## Redis value serialization
+
+The reference Redis adapter stores serialized values inside cache records. The default serializer is JSON.
+
+Use custom serialization for values that JSON cannot safely represent:
+
+```ts
+createRedisCacheAdapter({
+    client: redisClient,
+    serialize(value) {
+        return customEncode(value);
+    },
+    deserialize(value) {
+        return customDecode(value);
+    },
+});
+```
+
+The serializer must return a string.
+
+## Redis connection ownership
+
+BCP never creates a Redis connection. The application owns:
+
+- connection URL and credentials
+- TLS
+- Sentinel/Cluster configuration
+- reconnect behavior
+- process shutdown
+
+An adapter can receive a close hook:
+
+```ts
+createRedisCacheAdapter({
+    client: redisClient,
+    close: async () => {
+        await redisClient.quit();
+    },
+});
+```
+
+If the cache and lock adapters share one Redis connection, avoid registering two independent close hooks for that same connection. Prefer application-owned coordinated shutdown.
+
+## Redis atomic transitions
+
+The reference cache adapter uses Lua for cache record/index mutations, tag invalidation and distributed lock compare-and-release / compare-and-renew operations.
+
+This prevents one lock owner from releasing or renewing a lock that has already expired and been acquired by another owner.
+
+Path invalidation first discovers registered path indexes and then performs a Lua cleanup over the matching sets. For extremely large path catalogs, a specialized provider can implement a more scalable indexing strategy behind the same `CacheAdapter` contract.
+
+## Metrics integration
+
+Cache Platform v2 can emit metrics to the existing BCP metrics registry:
+
+```ts
+import {
+    createCacheMetrics,
+    createCacheStore,
+} from "bcp/cache";
+import {
+    createMetricsRegistry,
+} from "bcp/observability";
+
+const metrics =
+    createMetricsRegistry();
+
+const cache =
+    createCacheStore({
+        metrics:
+            createCacheMetrics(
+                metrics
+            ),
+    });
+```
+
+The default metrics are:
+
+```text
+bcp_cache_operations_total{event="..."}
+bcp_cache_in_flight
+```
+
+Events include hits, misses, sets, deletes, invalidations, loader outcomes and lock contention/timeout activity.
+
+Use a custom prefix when multiple logical caches need separate metric families:
+
+```ts
+createCacheMetrics(
+    metrics,
+    {
+        prefix:
+            "bcp_session_cache",
+    }
+);
+```
+
+## Store statistics
+
+```ts
+const stats =
+    await cache.stats();
+```
+
+The snapshot includes:
+
+```text
+hits
+misses
+sets
+deletes
+invalidations
+loads
+loadErrors
+lockAcquired
+lockContentions
+lockTimeouts
+inFlight
+adapterEntries (when supported)
+```
+
+Statistics belong to the `CacheStore` process. `adapterEntries` can come from shared storage when the provider supports it.
+
+## Failure model
+
+A cache is an optimization, not the system of record.
+
+Recommended production rules:
+
+1. Keep durable application truth in the database/object store.
+2. Design loaders so cache loss can be recovered by recomputation.
+3. Choose `onLockTimeout` based on whether availability or duplicate-work avoidance matters more.
+4. Do not use distributed cache locks as a replacement for database transaction/uniqueness rules protecting business invariants.
+5. Treat Redis/cache outages separately from durable queues, workflows and outbox guarantees.
+
+## Closing the store
+
+```ts
+await cache.close();
+```
+
+`close()` clears local in-flight bookkeeping and calls configured adapter/lock lifecycle hooks.
+
+## Published runtime
+
+`0.2.16` prepares `bcp/cache` as compiled `cache.mjs` for the npm package. TypeScript source remains the type surface, while standalone Node imports execute the compiled runtime.
+
+## Related guides
+
+- [Caching](caching.md)
+- [Observability Platform v2](observability.md)
+- [Plugin & Module Platform](plugin-module-platform.md)
+- [Testing Platform](testing-platform.md)
+- [Production Hardening](production-hardening.md)

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.15",
+  "versionTarget": "0.2.16",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,7 +58,7 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, caching, security and production hardening.",
+      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, distributed caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
@@ -70,6 +70,7 @@
         { "route": "/docs/workflow-orchestration", "source": "workflow-orchestration.md", "title": "Workflow Orchestration" },
         { "route": "/docs/realtime-platform", "source": "realtime-platform.md", "title": "Realtime Platform" },
         { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
+        { "route": "/docs/cache-platform-v2", "source": "cache-platform-v2.md", "title": "Cache Platform v2" },
         { "route": "/docs/security", "source": "security.md", "title": "Security" },
         { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
       ]
@@ -116,7 +117,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15", "state": "unreleased" },
+    { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16", "state": "unreleased" },
+    { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15" },
     { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14" },
     { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13" },
     { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "releaseState": "unreleased",
-  "baseline": "plugin-module-platform",
+  "baseline": "cache-platform-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -148,6 +148,19 @@
     "pluginServiceRegistry": true,
     "pluginHookBus": true,
     "pluginLifecycleRollback": true,
+    "cachePlatformV2": true,
+    "cacheAdapterContract": true,
+    "memoryCacheAdapter": true,
+    "redisCacheAdapter": true,
+    "cacheLockAdapter": true,
+    "redisCacheLockAdapter": true,
+    "cacheStampedeProtection": true,
+    "cacheLockHeartbeats": true,
+    "cacheTtl": true,
+    "cacheTagInvalidation": true,
+    "cachePathInvalidation": true,
+    "cacheMetrics": true,
+    "compiledCacheRuntime": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -187,7 +200,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.14",
+    "previousBaseline": "0.2.15",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -212,7 +225,8 @@
     "realtimePlatform": "realtime-platform.md",
     "testingPlatform": "testing-platform.md",
     "pluginModulePlatform": "plugin-module-platform.md",
+    "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.15.md"
+    "releaseNotes": "releases/0.2.16.md"
   }
 }

package/docs/releases/0.2.16.md

@@ -0,0 +1,147 @@
+# BCP Framework 0.2.16
+
+**State:** unreleased
+
+## Cache Platform v2
+
+`0.2.16` upgrades the existing `bcp/cache` public entrypoint with provider-neutral asynchronous cache storage, distributed lock contracts, Redis-compatible reference adapters, cache-stampede protection and metrics integration.
+
+The existing `cache()`, `dedupe()`, `revalidateTag()` and `revalidatePath()` APIs remain available with their previous process-local behavior.
+
+## New public APIs
+
+```ts
+createCacheStore()
+createMemoryCacheAdapter()
+createMemoryCacheLockAdapter()
+createRedisCacheAdapter()
+createRedisCacheLockAdapter()
+createCacheMetrics()
+```
+
+New public contracts include:
+
+```text
+CacheAdapter
+CacheAdapterEntry
+CacheAdapterSetOptions
+CacheLockAdapter
+CacheStore
+CacheStoreOptions
+CacheStoreSetOptions
+CacheGetOrSetOptions
+CacheStoreStats
+CacheMetricsSink
+CacheMetricsRegistryLike
+RedisCacheCommandClient
+RedisCacheAdapterOptions
+RedisCacheLockAdapterOptions
+```
+
+## Cache-aside loading
+
+`CacheStore.getOrSet()` provides a framework-native cache-aside primitive.
+
+Within one process it deduplicates concurrent loaders for the same key. With a shared `CacheLockAdapter`, multiple BCP instances coordinate cache fills through distributed leases.
+
+## Distributed lock behavior
+
+The built-in lock implementations support:
+
+- acquire with owner identity and TTL
+- compare-and-release
+- optional compare-and-extend
+- heartbeat renewal while a loader is active
+- contention wait/poll against shared cache state
+- explicit timeout failure with `onLockTimeout: "error"`
+- availability-oriented unlocked fallback by default after timeout
+
+Distributed locks reduce duplicate cache fill work. They are not a substitute for database transactions or uniqueness constraints protecting business invariants.
+
+## Redis-compatible adapters
+
+BCP still does not depend on a Redis package.
+
+Applications provide a minimal command client:
+
+```ts
+interface RedisCacheCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
+```
+
+The default namespace is `bcp:{cache}` so related keys share a Redis Cluster hash slot.
+
+The reference adapter uses Lua for record/index changes, tag invalidation, lock release and lock renewal.
+
+Applications remain responsible for Redis authentication, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+
+## TTL and invalidation
+
+Cache Store v2 supports:
+
+- millisecond TTL via `ttlMs`
+- tag invalidation
+- hierarchical path invalidation
+- adapter-wide clear
+- optional provider entry counts
+
+The older `cache()` API continues to accept `revalidate` in seconds for compatibility.
+
+## Observability
+
+`createCacheMetrics()` adapts Cache Store events to `bcp/observability`'s existing `MetricsRegistry` contract.
+
+Default metric families:
+
+```text
+bcp_cache_operations_total{event="..."}
+bcp_cache_in_flight
+```
+
+## Published runtime
+
+The prepared npm package now compiles `bcp/cache` to:
+
+```text
+packages/client/src/cache.mjs
+```
+
+The prepared package export points runtime imports at this compiled file while preserving `cache.ts` as the public type source.
+
+## Testing
+
+The `0.2.16` suite adds coverage for:
+
+- TTL expiration
+- tag/path invalidation
+- store statistics
+- local in-flight deduplication
+- cross-store distributed stampede protection
+- lock timeout errors
+- BCP metrics registry integration
+- Redis command/namespace contract
+- compiled prepared-package runtime smoke
+
+## Compatibility
+
+`0.2.16` has no intentional breaking changes from `0.2.15`.
+
+Existing application calls using the original cache APIs do not need to migrate.
+
+## Release validation
+
+Before publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Tag and publish only the exact commit that passes the complete RC sequence.