create-bcp-app 0.2.13 → 0.2.15

package/README.md

@@ -69,17 +69,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.13` target:
+Example for the `0.2.15` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.13",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.15",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.13"
+    "version": "0.2.15"
   },
   "packageManager": "npm",
   "presets": {
@@ -218,44 +218,154 @@ await realtime.broadcast(
 );
 ```
 
-Presence metadata can be attached during `join()` and read with `realtime.members(channel)`.
+BCP does not install a WebSocket library. Adapt your selected provider to `RealtimeSocket`. SSE is available directly through `realtime.sse()`.
 
-For private channels, configure `authenticate`, `getUserId` and `authorizeChannel` on `createRealtime()`.
+The memory broker/presence store are local-only. Multi-instance production deployments should provide shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+
+## Testing Platform — 0.2.14+
 
-### WebSocket integration
+`bcp/testing` adds framework-native test helpers without requiring a specific test runner.
 
-BCP does not install a WebSocket library. Adapt your selected provider to `RealtimeSocket` and pass it to:
+Request/route example:
 
 ```ts
-await realtime.attachSocket(
-    socketAdapter,
-    {
-        request,
-    }
-);
-```
+import {
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const app =
+    createTestApp({
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
+    });
 
-### Server-Sent Events
+await expectResponse(
+    await app.get("/api/health")
+)
+    .status(200)
+    .json({
+        ok: true,
+    });
+```
 
-SSE is available without another dependency:
+Create a real signed BCP auth session for authenticated requests:
 
 ```ts
-export function GET(
-    request: Request
-) {
-    return realtime.sse(
-        "jobs:42",
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
         {
-            signal:
-                request.signal,
+            id: 42,
+            role: "admin",
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
         }
     );
-}
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
 ```
 
-The memory broker/presence store are local-only. Multi-instance production deployments should provide shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+Rollback database tests:
+
+```ts
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+    }
+);
+```
+
+Infrastructure helpers include:
+
+```text
+createJobTestHarness()
+createWorkflowTestHarness()
+createOutboxTestHarness()
+createRealtimeTestSocket()
+createRealtimeTestHarness()
+readSseEvents()
+createFakeClock()
+createSequenceIdFactory()
+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/realtime` is server-only and cannot be imported into page/client bundles.
+`bcp/plugins` is server-only and cannot be imported into page/client bundles.
 
 ## Storage providers
 
@@ -295,5 +405,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.13.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.15.tgz
 ```

package/package.json

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

package/template/README.md

@@ -163,29 +163,130 @@ await realtime.broadcast(
 );
 ```
 
-Presence metadata can be supplied during `join()` and queried with `realtime.members(channel)`.
+BCP does not install a WebSocket server dependency. Adapt the selected provider to `RealtimeSocket`. SSE is built in through `realtime.sse()`.
 
-BCP does not install a WebSocket server dependency. Adapt the selected provider to `RealtimeSocket` and call `realtime.attachSocket(socketAdapter, { request })`.
+For multi-instance deployment, replace the memory broker/presence store with shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+
+## Testing Platform — BCP 0.2.14+
 
-SSE is built in:
+Use server-only `bcp/testing` to exercise framework contracts without adding a BCP-specific test runner.
 
 ```ts
-export function GET(
-    request: Request
-) {
-    return realtime.sse(
-        "jobs:42",
+import {
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const app =
+    createTestApp({
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
+    });
+
+await expectResponse(
+    await app.get("/api/health")
+)
+    .status(200)
+    .json({
+        ok: true,
+    });
+```
+
+Authentication tests can create a real signed BCP session:
+
+```ts
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+        },
         {
-            signal:
-                request.signal,
+            secret:
+                process.env.BCP_SESSION_SECRET,
         }
     );
-}
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
 ```
 
-For multi-instance deployment, replace the memory broker/presence store with shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+Database tests can force rollback after assertions:
+
+```ts
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+    }
+);
+```
+
+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/realtime` is server-only and cannot be imported into page/client bundles.
+`bcp/plugins` is server-only and cannot be imported from page/client bundles.
 
 ## Generate framework files