@chidchanun/bcp 0.2.15 → 0.2.16

package/README.md

@@ -1,10 +1,10 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, plugin/module composition, observability, uploads, storage and standalone Node.js deployment.
+BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, plugin/module composition, distributed caching, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.15 — Plugin & Module Platform`
+> **Development target:** `0.2.16 — Cache Platform v2`
 >
-> `0.2.15` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.16` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
@@ -27,9 +27,9 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Realtime | Channels/rooms, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
 | Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
 | Plugins & modules | Dependency ordering, lifecycle hooks, config parsing, service registry and async extension hooks |
+| Caching | Legacy request/data cache plus Cache Platform v2 adapters, Redis-compatible cache/locks, stampede protection, TTL/tag/path invalidation and metrics |
 | Observability | Structured logs, metrics, Prometheus output and health/readiness checks |
 | Uploads & storage | Multipart streaming, Local/S3-compatible storage and signed URLs |
-| Caching | Response cache and revalidation primitives |
 | Configuration | Typed config/environment validation and diagnostics |
 | Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
 | Documentation | Manifest-driven docs, platform metadata and API reference |
@@ -69,6 +69,7 @@ Generated projects normally use one framework dependency:
 ## Core backend entrypoints
 
 ```ts
+import { createCacheStore } from "bcp/cache";
 import { db } from "bcp/database";
 import { createAuth } from "bcp/auth";
 import { createJobQueue } from "bcp/jobs";
@@ -446,6 +447,100 @@ If startup fails, already-started plugins are stopped in reverse order before th
 
 Read more: [Plugin & Module Platform](docs/plugin-module-platform.md)
 
+## Cache Platform v2 — 0.2.16
+
+`0.2.16` keeps the original `cache()` and `dedupe()` APIs while adding provider-neutral asynchronous cache stores for production multi-instance applications.
+
+Create a cache store:
+
+```ts
+import {
+    createCacheStore,
+} from "bcp/cache";
+
+export const applicationCache =
+    createCacheStore();
+```
+
+Cache-aside loading:
+
+```ts
+const user =
+    await applicationCache.getOrSet(
+        "user:42",
+        async () =>
+            loadUser(42),
+        {
+            ttlMs: 60_000,
+            tags: [
+                "users",
+            ],
+            paths: [
+                "/users/42",
+            ],
+        }
+    );
+```
+
+Within one store, concurrent misses share one loader automatically.
+
+For multiple application instances, use shared cache and lock adapters:
+
+```ts
+import {
+    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 Redis namespace is `bcp:{cache}`. BCP does not install or own a Redis library/connection.
+
+Distributed `getOrSet()` uses owner-scoped lock leases, heartbeat renewal when supported, double-check-after-lock, contention wait/poll and configurable lock-timeout behavior.
+
+Tag/path invalidation remains available through the new async store:
+
+```ts
+await cache.revalidateTag(
+    "users"
+);
+
+await cache.revalidatePath(
+    "/dashboard"
+);
+```
+
+Connect cache events to BCP metrics:
+
+```ts
+const cache =
+    createCacheStore({
+        metrics:
+            createCacheMetrics(
+                metricsRegistry
+            ),
+    });
+```
+
+Prepared npm packages compile `bcp/cache` to `cache.mjs` for standalone Node runtime use.
+
+Read more: [Cache Platform v2](docs/cache-platform-v2.md)
+
 ## Public entrypoints
 
 ```text
@@ -518,10 +613,13 @@ Browser / API / Realtime clients
  outbox       jobs       |
     \__________|_________/
            durable state
-
-Testing Platform exercises these server contracts without becoming part of browser runtime.
+              |
+       shared cache layer
+          Redis / other
 ```
 
+Cache is an optimization layer and must not replace durable application truth or transactional invariants.
+
 ## Packaging
 
 ```bash
@@ -547,7 +645,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.15`:
+Before publishing `0.2.16`:
 
 ```bash
 npm run typecheck
@@ -558,7 +656,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.15` adds unit and prepared-package smoke coverage for plugin dependency ordering, missing/cyclic dependencies, modules, config parsing, shared services, async hooks, lifecycle rollback, compiled `plugins.mjs` execution and browser boundary enforcement.
+`0.2.16` adds unit and prepared-package smoke coverage for TTL/tag/path invalidation, local singleflight, distributed lock contention, lock timeout behavior, Redis cache/lock command contracts, cache metrics and compiled `cache.mjs` execution.
 
 Do not tag or publish until the exact final release commit passes the full RC sequence.
 
@@ -588,12 +686,13 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.13` | Realtime Platform |
 | `0.2.14` | Testing Platform |
 | `0.2.15` | Plugin & Module Platform |
+| `0.2.16` | Cache Platform v2 |
 
 ## Roadmap
 
-`0.2.15` establishes reusable server-side extension composition while keeping BCP subsystem contracts provider-neutral and independently testable.
+`0.2.16` establishes provider-neutral shared caching and distributed cache-fill coordination while preserving the original process-local cache API.
 
-The next logical milestone is **`0.2.16 — Cache Platform v2`**, focused on distributed cache adapters, Redis-compatible caching, locking, stampede protection and production cache observability.
+The next logical milestone is **`0.2.17 — Observability Platform v3`**, focused on tracing, correlation across HTTP/jobs/workflows/events/realtime/cache, richer runtime metrics and exporter/provider integration.
 
 Native desktop/mobile compilation remains later roadmap work.
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.15 — Plugin & Module Platform`
+> **Documentation target:** BCP Framework `0.2.16 — Cache Platform v2`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -41,55 +41,61 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.13` | Realtime Platform |
 | `0.2.14` | Testing Platform |
 | `0.2.15` | Plugin & Module Platform |
+| `0.2.16` | Cache Platform v2 |
 
-## 0.2.15 — Plugin & Module Platform
+## 0.2.16 — Cache Platform v2
 
-`0.2.15` adds the server-only `bcp/plugins` public entrypoint.
+`0.2.16` extends the existing `bcp/cache` public entrypoint while keeping its original process-local APIs backward compatible.
 
-Primary APIs:
+Primary Cache Store v2 APIs:
 
 ```ts
 import {
-    createPluginHookBus,
-    createPluginHost,
-    createPluginServiceRegistry,
-    defineModule,
-    definePlugin,
-} from "bcp/plugins";
+    createCacheMetrics,
+    createCacheStore,
+    createMemoryCacheAdapter,
+    createMemoryCacheLockAdapter,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+} from "bcp/cache";
 ```
 
 Runtime model:
 
 ```text
-Plugin Host
-   |
-   +-- dependency graph
-   |      -> required / optional dependencies
-   |
-   +-- lifecycle
-   |      -> setup -> start -> stop -> dispose
-   |
-   +-- service registry
-   |      -> typed shared application services
-   |
-   +-- async hook bus
-          -> in-process extension points
+Application
+    |
+    v
+CacheStore
+    |
+    +-- CacheAdapter
+    |      +-- memory
+    |      +-- Redis-compatible
+    |
+    +-- CacheLockAdapter
+    |      +-- memory
+    |      +-- Redis-compatible
+    |
+    +-- local singleflight
+    +-- distributed cache-fill lease
+    +-- TTL / tags / paths
+    +-- metrics sink
 ```
 
-Startup follows topological dependency order. Stop/dispose runs in reverse order. A failed startup rolls back plugins that already started.
+`getOrSet()` deduplicates cache fills inside one process. With a shared lock adapter, multiple processes coordinate cache misses through owner-scoped leases, optional lock renewal and wait/poll behavior.
 
-Modules are named bundles of plugins; they do not create a separate lifecycle graph.
+The Redis reference adapter uses the default hash-tagged namespace `bcp:{cache}` and does not install or own a Redis client.
 
 New/updated sources:
 
 | Source | Purpose |
 | --- | --- |
-| `plugin-module-platform.md` | Plugin definitions, modules, dependency order, lifecycle, config, services and hooks |
-| `api-reference.md` | `bcp/plugins` public APIs |
-| `platform-manifest.json` | Plugin capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/plugins` source/guide ownership |
-| `docs-web-manifest.json` | Plugin docs navigation and `0.2.15` release route |
-| `releases/0.2.15.md` | Plugin & Module Platform release notes |
+| `cache-platform-v2.md` | Adapter contracts, Redis cache/locks, stampede protection, TTL/invalidation and metrics |
+| `api-reference.md` | `bcp/cache` Cache Platform v2 APIs |
+| `platform-manifest.json` | Cache v2 capability flags |
+| `api-manifest.json` | Updated `bcp/cache` source/guide ownership |
+| `docs-web-manifest.json` | Cache v2 docs navigation and `0.2.16` release route |
+| `releases/0.2.16.md` | Cache Platform v2 release notes |
 
 ## Update rule
 
@@ -117,8 +123,9 @@ When framework behavior or public surface changes:
 | `/docs/realtime-platform` | `realtime-platform.md` |
 | `/docs/testing-platform` | `testing-platform.md` |
 | `/docs/plugin-module-platform` | `plugin-module-platform.md` |
+| `/docs/cache-platform-v2` | `cache-platform-v2.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.15` | `releases/0.2.15.md` |
+| `/releases/0.2.16` | `releases/0.2.16.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -149,7 +156,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.15`:
+Before publishing `0.2.16`:
 
 ```bash
 npm run typecheck
@@ -160,6 +167,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Plugin Platform validation covers dependency ordering, missing/cyclic dependencies, module composition, typed config parsing, service sharing, async hooks, reverse shutdown, startup rollback, server-only boundaries, compiled `plugins.mjs` package execution and docs/platform/API parity.
+Cache Platform v2 validation covers TTL/tag/path invalidation, local singleflight, cross-store distributed locking, lock timeout behavior, Redis command contracts, metrics integration, compiled `cache.mjs` package execution and docs/platform/API parity.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -26,8 +26,8 @@
       "source": "packages/client/src/cache.ts",
       "environment": "server-preferred",
       "route": "/docs/api-reference#bcp-cache",
-      "summary": "Cache, deduplication, statistics and path/tag revalidation primitives.",
-      "guides": ["/docs/caching"]
+      "summary": "Backward-compatible request/data caching plus Cache Platform v2 adapters, Redis-compatible distributed cache and locks, stampede protection, TTL/tag/path invalidation and metrics integration.",
+      "guides": ["/docs/caching", "/docs/cache-platform-v2", "/docs/observability"]
     },
     {
       "package": "bcp/config",
@@ -123,7 +123,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-observability",
       "summary": "In-process metrics, Prometheus exposition, request metrics middleware and health/readiness checks.",
-      "guides": ["/docs/observability", "/docs/development-logging"]
+      "guides": ["/docs/observability", "/docs/development-logging", "/docs/cache-platform-v2"]
     },
     {
       "package": "bcp/server",

package/docs/api-reference.md

@@ -26,9 +26,66 @@ Related guide: [Hydration](hydration.md).
 
 ## `bcp/cache`
 
-Caching, deduplication, statistics and path/tag revalidation primitives.
+Caching APIs include the original process-local request/data cache plus Cache Platform v2 provider contracts for shared production caches.
 
-Related guide: [Caching](caching.md).
+Legacy-compatible exports remain:
+
+```ts
+import {
+    cache,
+    clearCache,
+    dedupe,
+    getCacheStats,
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+```
+
+Cache Platform v2 adds:
+
+```ts
+import {
+    createCacheMetrics,
+    createCacheStore,
+    createMemoryCacheAdapter,
+    createMemoryCacheLockAdapter,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+    type CacheAdapter,
+    type CacheAdapterEntry,
+    type CacheAdapterSetOptions,
+    type CacheGetOrSetOptions,
+    type CacheLockAdapter,
+    type CacheMetricsRegistryLike,
+    type CacheMetricsSink,
+    type CacheStore,
+    type CacheStoreEvent,
+    type CacheStoreOptions,
+    type CacheStoreSetOptions,
+    type CacheStoreStats,
+    type MemoryCacheAdapter,
+    type MemoryCacheLockAdapter,
+    type RedisCacheAdapter,
+    type RedisCacheAdapterOptions,
+    type RedisCacheCommandClient,
+    type RedisCacheLockAdapter,
+    type RedisCacheLockAdapterOptions,
+} from "bcp/cache";
+```
+
+`createCacheStore()` exposes async `get()`, `set()`, `delete()`, `clear()`, `revalidateTag()`, `revalidatePath()`, `getOrSet()`, `stats()` and `close()` operations.
+
+`getOrSet()` always provides local singleflight deduplication. When a `CacheLockAdapter` is supplied, cache fills can also coordinate across multiple application instances with owner-scoped leases, optional renewal and configurable contention timeout behavior.
+
+`createRedisCacheAdapter()` and `createRedisCacheLockAdapter()` use a minimal `sendCommand()` client contract. BCP does not install or own a Redis library/connection. The default namespace is `bcp:{cache}` for Redis Cluster hash-slot locality.
+
+Cache Store v2 uses millisecond TTL (`ttlMs`), while the original `cache()` API keeps its existing `revalidate`-seconds contract.
+
+`createCacheMetrics()` adapts cache events to the existing BCP `MetricsRegistry` shape without coupling the cache package directly to a specific exporter.
+
+Prepared npm packages compile the runtime entrypoint to `packages/client/src/cache.mjs`.
+
+Related guides: [Caching](caching.md), [Cache Platform v2](cache-platform-v2.md), [Observability Platform v2](observability.md).
 
 ## `bcp/config`
 
@@ -358,7 +415,9 @@ Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configur
 
 Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.
 
-Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
+`Cache Platform v2` can connect to this registry through `createCacheMetrics()` from `bcp/cache`.
+
+Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md), [Cache Platform v2](cache-platform-v2.md).
 
 ## `bcp/server`