create-bcp-app 0.2.14 → 0.2.16

package/README.md

@@ -69,17 +69,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.14` target:
+Example for the `0.2.16` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.14",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.16",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.14"
+    "version": "0.2.16"
   },
   "packageManager": "npm",
   "presets": {
@@ -314,6 +314,116 @@ runTestMiddleware()
 
 `bcp/testing` is server-only. It can be used with Node `node:test`, Vitest, Jest or another runner; BCP does not install those runners as framework dependencies.
 
+## Plugin & Module Platform — 0.2.15+
+
+Use `bcp/plugins` to compose reusable server-side application modules with explicit lifecycle and dependencies.
+
+```ts
+import {
+    createPluginHost,
+    defineModule,
+    definePlugin,
+} from "bcp/plugins";
+
+const databasePlugin =
+    definePlugin({
+        name: "database",
+        setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
+        },
+    });
+
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+
+const backendModule =
+    defineModule({
+        name: "backend",
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+        ],
+    });
+
+const host =
+    createPluginHost({
+        modules: [
+            backendModule,
+        ],
+    });
+
+await host.start();
+```
+
+Plugins can use `setup/start/stop/dispose`, typed config parsers, a shared service registry and an awaited in-process hook bus. Required dependencies start first; shutdown runs in reverse order.
+
+`bcp/plugins` is server-only and cannot be imported into page/client bundles.
+
+## Cache Platform v2 — 0.2.16+
+
+Use the existing `bcp/cache` entrypoint for provider-neutral shared caching while keeping the original `cache()` and `dedupe()` APIs available.
+
+```ts
+import {
+    createCacheStore,
+} from "bcp/cache";
+
+export const cache =
+    createCacheStore();
+```
+
+Cache-aside loading:
+
+```ts
+const user =
+    await cache.getOrSet(
+        "user:42",
+        () => loadUser(42),
+        {
+            ttlMs: 60_000,
+            tags: ["users"],
+            paths: ["/users/42"],
+        }
+    );
+```
+
+For multi-instance deployments, applications can supply Redis-compatible 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,
+    });
+```
+
+BCP does not install or own the Redis client. Applications remain responsible for credentials, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+
+`getOrSet()` provides local singleflight and can use distributed lock leases with heartbeat renewal to reduce cache stampedes across instances.
+
 ## Storage providers
 
 Supported presets are Local Server, Amazon S3 and Cloudflare R2. Storage credentials are server-only and must not use `BCP_PUBLIC_*` variables.
@@ -352,5 +462,5 @@ npm run generate -- migration create_users
 For prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.14.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.16.tgz
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -240,10 +240,107 @@ await withTestTransaction(
 );
 ```
 
-Additional helpers include job/workflow/outbox harnesses, `runTestMiddleware()`, fake clocks and IDs, a fake `RealtimeSocket`, realtime event assertions and `readSseEvents()`.
+Additional helpers include job/workflow/outbox harnesses, `runTestMiddleware()`, page loader/guard/action helpers, fake clocks and IDs, a fake `RealtimeSocket`, realtime event assertions and `readSseEvents()`.
 
 BCP does not require Jest or Vitest; these helpers work with Node `node:test` or another runner.
 
+## Plugin & Module Platform — BCP 0.2.15+
+
+Use `bcp/plugins` to compose reusable server-only application services with explicit dependencies.
+
+```ts
+import {
+    createPluginHost,
+    definePlugin,
+} from "bcp/plugins";
+
+const databasePlugin =
+    definePlugin({
+        name: "database",
+        setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
+        },
+    });
+
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+
+export const plugins =
+    createPluginHost({
+        plugins: [
+            jobsPlugin,
+            databasePlugin,
+        ],
+    });
+```
+
+Plugin startup follows dependency order and shutdown reverses it. Plugins can use `setup/start/stop/dispose`, config parsers, shared services and async hooks.
+
+Use `defineModule()` when a reusable package needs to bundle multiple plugin definitions into one named module.
+
+`bcp/plugins` is server-only and cannot be imported from page/client bundles.
+
+## Cache Platform v2 — BCP 0.2.16+
+
+Use `createCacheStore()` for async cache-aside loading, shared adapters and distributed cache-fill coordination.
+
+```ts
+import {
+    createCacheStore,
+} from "bcp/cache";
+
+export const cache =
+    createCacheStore();
+```
+
+```ts
+const user =
+    await cache.getOrSet(
+        "user:42",
+        () => loadUser(42),
+        {
+            ttlMs: 60_000,
+            tags: ["users"],
+            paths: ["/users/42"],
+        }
+    );
+```
+
+For multiple instances, connect a shared cache and lock provider:
+
+```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,
+    });
+```
+
+BCP does not install or own a Redis client. The default adapter namespace is `bcp:{cache}`. The original `cache()` and `dedupe()` APIs remain available for backward-compatible process-local caching.
+
 ## Generate framework files
 
 ```bash