@chidchanun/bcp 0.2.14 → 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, 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.14 — Testing Platform`
+> **Development target:** `0.2.16 — Cache Platform v2`
 >
-> `0.2.14` 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
 
@@ -25,10 +25,11 @@ BCP Framework is a React full-stack framework for file-based routing, SSR, SPA n
 | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
 | Events | Transactional outbox, SQL persistence, dispatcher leases, retries, event bus and durable queue handoff |
 | Realtime | Channels/rooms, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
-| Testing | Request/route/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test harnesses |
+| 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 |
@@ -68,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";
@@ -75,6 +77,7 @@ import { createWorkflow } from "bcp/workflow";
 import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
 import { createTestApp } from "bcp/testing";
+import { createPluginHost } from "bcp/plugins";
 import { createMetricsRegistry } from "bcp/observability";
 ```
 
@@ -369,6 +372,175 @@ readSseEvents()
 
 Read more: [Testing Platform](docs/testing-platform.md)
 
+## Plugin & Module Platform — 0.2.15
+
+`0.2.15` adds the server-only `bcp/plugins` entrypoint for reusable application/framework extensions.
+
+Define plugins with explicit dependencies:
+
+```ts
+import {
+    createPluginHost,
+    definePlugin,
+} from "bcp/plugins";
+
+const databasePlugin =
+    definePlugin({
+        name: "database",
+        setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
+        },
+        start() {
+            return db.connect();
+        },
+        stop() {
+            return db.disconnect();
+        },
+    });
+
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+
+const host =
+    createPluginHost({
+        plugins: [
+            jobsPlugin,
+            databasePlugin,
+        ],
+    });
+
+await host.start();
+```
+
+Dependency order is resolved automatically. Startup follows dependency order while stop/dispose runs in reverse order.
+
+Modules group reusable plugin sets:
+
+```ts
+import {
+    defineModule,
+} from "bcp/plugins";
+
+const backendModule =
+    defineModule({
+        name: "backend",
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+        ],
+    });
+```
+
+Plugin configuration can be parsed at setup time and overridden through `createPluginHost({ configs })`.
+
+Plugins share a service registry and awaited in-process hook bus through `context.services` and `context.hooks`.
+
+If startup fails, already-started plugins are stopped in reverse order before the lifecycle error is propagated.
+
+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
@@ -385,6 +557,7 @@ bcp/workflow
 bcp/events
 bcp/realtime
 bcp/testing
+bcp/plugins
 bcp/observability
 bcp/server
 bcp/server-only
@@ -433,17 +606,20 @@ Browser / API / Realtime clients
               |
       security + auth
               |
-       application APIs
+          Plugin Host
        /      |       \
  database  workflows  realtime
     |          |         ^
  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
@@ -469,7 +645,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.14`:
+Before publishing `0.2.16`:
 
 ```bash
 npm run typecheck
@@ -480,7 +656,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.14` adds unit and prepared-package smoke coverage for request/route handling, cookies, signed auth sessions, rollback transactions, middleware execution, jobs, workflows, outbox delivery, realtime sockets, SSE parsing, public runtime compilation 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.
 
@@ -509,12 +685,14 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.12` | Transactional Outbox & Events |
 | `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.14` establishes framework-native testing for the current BCP application/runtime stack without coupling the framework to a specific test runner.
+`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.15 — Plugin & Module Platform`**, focused on reusable framework modules, lifecycle hooks, configuration extension, package metadata and plugin discovery/registration while keeping the current public entrypoints stable.
+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.14 — Testing Platform`
+> **Documentation target:** BCP Framework `0.2.16 — Cache Platform v2`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -40,63 +40,62 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.12` | Transactional Outbox & Events |
 | `0.2.13` | Realtime Platform |
 | `0.2.14` | Testing Platform |
+| `0.2.15` | Plugin & Module Platform |
+| `0.2.16` | Cache Platform v2 |
 
-## 0.2.14 — Testing Platform
+## 0.2.16 — Cache Platform v2
 
-`0.2.14` adds the server-only `bcp/testing` 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 {
-    createFakeClock,
-    createJobTestHarness,
-    createOutboxTestHarness,
-    createRealtimeTestHarness,
-    createRealtimeTestSocket,
-    createRouteTestHandler,
-    createSequenceIdFactory,
-    createTestApp,
-    createTestAuthSession,
-    createWorkflowTestHarness,
-    expectResponse,
-    readSseEvents,
-    runTestMiddleware,
-    withTestTransaction,
-} from "bcp/testing";
+    createCacheMetrics,
+    createCacheStore,
+    createMemoryCacheAdapter,
+    createMemoryCacheLockAdapter,
+    createRedisCacheAdapter,
+    createRedisCacheLockAdapter,
+} from "bcp/cache";
 ```
 
-Testing model:
+Runtime model:
 
 ```text
-node:test / Vitest / Jest / other runner
-                |
-                v
-            bcp/testing
-                |
-     +----------+-----------+
-     |          |           |
- Request     Database   Infrastructure
- Route       rollback   jobs/workflow
- Response      tx       outbox/realtime
- Auth                    SSE/socket
- Middleware
+Application
+    |
+    v
+CacheStore
+    |
+    +-- CacheAdapter
+    |      +-- memory
+    |      +-- Redis-compatible
+    |
+    +-- CacheLockAdapter
+    |      +-- memory
+    |      +-- Redis-compatible
+    |
+    +-- local singleflight
+    +-- distributed cache-fill lease
+    +-- TTL / tags / paths
+    +-- metrics sink
 ```
 
-The helpers use existing BCP runtime contracts rather than defining a parallel mock framework. Signed auth sessions use the production session token implementation; middleware tests execute the real onion pipeline; job/workflow/outbox/realtime harnesses wrap their actual platform APIs.
+`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.
 
-BCP does not add a Jest or Vitest dependency.
+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 |
 | --- | --- |
-| `testing-platform.md` | Request, auth, database, middleware, jobs, workflow, outbox, realtime and SSE testing |
-| `api-reference.md` | `bcp/testing` public APIs |
-| `platform-manifest.json` | Testing capability flags and public entrypoint |
-| `api-manifest.json` | `bcp/testing` source/guide ownership |
-| `docs-web-manifest.json` | Testing docs navigation and `0.2.14` release route |
-| `releases/0.2.14.md` | Testing 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
 
@@ -123,8 +122,10 @@ When framework behavior or public surface changes:
 | `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
 | `/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.14` | `releases/0.2.14.md` |
+| `/releases/0.2.16` | `releases/0.2.16.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -144,6 +145,7 @@ bcp/workflow
 bcp/events
 bcp/realtime
 bcp/testing
+bcp/plugins
 bcp/observability
 bcp/server
 bcp/server-only
@@ -154,7 +156,7 @@ The API-manifest entrypoint set must match the platform public-entrypoint set ex
 
 ## Release validation
 
-Before publishing `0.2.14`:
+Before publishing `0.2.16`:
 
 ```bash
 npm run typecheck
@@ -165,6 +167,6 @@ npm run test:package
 npm run rc:check
 ```
 
-Testing Platform validation covers request/route behavior, cookie persistence, signed auth sessions, rollback transactions, middleware execution, deterministic clocks/IDs, job/workflow/outbox/realtime harnesses, SSE parsing, server-only boundaries, compiled `testing.mjs` 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.14",
+  "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",
@@ -106,16 +106,24 @@
       "source": "packages/client/src/testing.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-testing",
-      "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
+      "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, page/server execution, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
       "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform"]
     },
+    {
+      "package": "bcp/plugins",
+      "source": "packages/client/src/plugins.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-plugins",
+      "summary": "Plugin and module composition with dependency ordering, lifecycle hooks, typed config parsing, shared services and asynchronous extension hooks.",
+      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability"]
+    },
     {
       "package": "bcp/observability",
       "source": "packages/client/src/observability.ts",
       "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`
 
@@ -308,11 +365,59 @@ The package is server-only; the client boundary validator rejects `bcp/testing`
 
 Related guides: [Testing Platform](testing-platform.md), [Authentication](authentication.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Workflow Orchestration](workflow-orchestration.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md).
 
+## `bcp/plugins`
+
+Server-only Plugin & Module Platform APIs added in `0.2.15`.
+
+```ts
+import {
+    createPluginHookBus,
+    createPluginHost,
+    createPluginServiceRegistry,
+    defineModule,
+    definePlugin,
+    PluginDependencyError,
+    PluginLifecycleError,
+    type PluginConfigParser,
+    type PluginConfigSchema,
+    type PluginContext,
+    type PluginDefinition,
+    type PluginHookBus,
+    type PluginHookHandler,
+    type PluginHost,
+    type PluginHostOptions,
+    type PluginHostView,
+    type PluginModule,
+    type PluginRecord,
+    type PluginServiceKey,
+    type PluginServiceRegistry,
+    type PluginState,
+} from "bcp/plugins";
+```
+
+`createPluginHost()` resolves required and optional plugin dependencies and starts plugins in topological order. `stop()` and `close()` shut them down/dispose them in reverse dependency order.
+
+`defineModule()` groups reusable plugin definitions while preserving one global host dependency graph.
+
+Plugin configuration can be parsed with a schema/parser during setup. Values from `PluginHostOptions.configs` override plugin-local defaults before parsing.
+
+`PluginServiceRegistry` provides shared string/Symbol-keyed services. `PluginHookBus` provides awaited, in-process extension hooks in registration order.
+
+Missing dependencies and dependency cycles throw `PluginDependencyError`. Setup/start failures surface `PluginLifecycleError`; startup failures roll back plugins that already started in the current transition.
+
+`host.plugin()` and `host.plugins()` expose inspectable lifecycle records.
+
+`bcp/plugins` is server-only and is rejected from page/client bundles.
+
+Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configuration](configuration.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+
 ## `bcp/observability`
 
 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`