create-bcp-app 0.2.12 → 0.2.14

package/README.md

@@ -69,17 +69,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.2.12` target:
+Example for the `0.2.14` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.12",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.14",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.12"
+    "version": "0.2.14"
   },
   "packageManager": "npm",
   "presets": {
@@ -167,26 +167,6 @@ export const onboarding =
 Applications using the SQL Database Platform can persist integration events in the same transaction as business data:
 
 ```ts
-import {
-    db,
-} from "bcp/database";
-
-import {
-    createSqlOutboxStore,
-    createTransactionalOutbox,
-} from "bcp/events";
-
-const outboxStore =
-    createSqlOutboxStore({
-        database: db,
-        driver: "mysql",
-    });
-
-const outbox =
-    createTransactionalOutbox({
-        store: outboxStore,
-    });
-
 await db.transaction(
     async tx => {
         await tx.execute(
@@ -204,42 +184,135 @@ await db.transaction(
 );
 ```
 
-Create migration SQL with:
+After commit, `createOutboxDispatcher()` can hand off events to durable jobs/custom publishers.
+
+## Realtime Platform — 0.2.13+
+
+Generated applications can add server-side realtime channels without changing the scaffold preset model:
 
 ```ts
 import {
-    createOutboxMigrationSql,
-} from "bcp/events";
+    createRealtime,
+} from "bcp/realtime";
 
-const migrationSql =
-    createOutboxMigrationSql(
-        "mysql"
-    );
+export const realtime =
+    createRealtime();
+```
+
+Channel/room usage:
+
+```ts
+const connection =
+    await realtime.connect();
+
+await connection.join(
+    "orders:42"
+);
+
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
 ```
 
-After commit, dispatch to the durable job queue:
+BCP does not install a WebSocket library. Adapt your selected provider to `RealtimeSocket`. SSE is available directly through `realtime.sse()`.
+
+The memory broker/presence store are local-only. Multi-instance production deployments should provide shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+
+## Testing Platform — 0.2.14+
+
+`bcp/testing` adds framework-native test helpers without requiring a specific test runner.
+
+Request/route example:
 
 ```ts
 import {
-    createOutboxDispatcher,
-} from "bcp/events";
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const app =
+    createTestApp({
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
+    });
 
-const dispatcher =
-    createOutboxDispatcher({
-        store: outboxStore,
-        queue: jobs,
-        ownerId: "outbox-a",
+await expectResponse(
+    await app.get("/api/health")
+)
+    .status(200)
+    .json({
+        ok: true,
     });
+```
+
+Create a real signed BCP auth session for authenticated requests:
+
+```ts
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+            role: "admin",
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
+        }
+    );
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
+```
 
-const runner =
-    dispatcher.start();
+Rollback database tests:
+
+```ts
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+    }
+);
 ```
 
-Event type `order.created` is handed off to queue name `event.order.created`.
+Infrastructure helpers include:
 
-The outbox dispatcher supports leases, stale recovery, retry/backoff, custom publishers, a local EventBus, cleanup and statistics.
+```text
+createJobTestHarness()
+createWorkflowTestHarness()
+createOutboxTestHarness()
+createRealtimeTestSocket()
+createRealtimeTestHarness()
+readSseEvents()
+createFakeClock()
+createSequenceIdFactory()
+runTestMiddleware()
+```
 
-`bcp/events` is server-only. The SQL outbox protects the database-commit/external-publish boundary, but downstream delivery remains at-least-once, so non-repeatable side effects should use idempotency protection.
+`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.
 
 ## Storage providers
 
@@ -279,5 +352,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.12.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.14.tgz
 ```

package/package.json

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

package/template/README.md

@@ -112,26 +112,6 @@ Workflows support sequential/parallel steps, retries, persisted delays, compensa
 Use `bcp/events` when application data and an integration event must commit atomically in the same SQL transaction.
 
 ```ts
-import {
-    db,
-} from "bcp/database";
-
-import {
-    createSqlOutboxStore,
-    createTransactionalOutbox,
-} from "bcp/events";
-
-const outboxStore =
-    createSqlOutboxStore({
-        database: db,
-        driver: "mysql",
-    });
-
-const outbox =
-    createTransactionalOutbox({
-        store: outboxStore,
-    });
-
 await db.transaction(
     async tx => {
         await tx.execute(
@@ -149,42 +129,120 @@ await db.transaction(
 );
 ```
 
-Generate the required table SQL:
+After commit, `createOutboxDispatcher()` can deliver through durable jobs or a custom publisher.
+
+## Realtime Platform — BCP 0.2.13+
+
+Create a server-side realtime hub:
 
 ```ts
 import {
-    createOutboxMigrationSql,
-} from "bcp/events";
+    createRealtime,
+} from "bcp/realtime";
 
-const sql =
-    createOutboxMigrationSql(
-        "mysql"
-    );
+export const realtime =
+    createRealtime();
 ```
 
-Dispatch committed events to the durable queue:
+Channels/rooms:
+
+```ts
+const connection =
+    await realtime.connect();
+
+await connection.join(
+    "orders:42"
+);
+
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
+```
+
+BCP does not install a WebSocket server dependency. Adapt the selected provider to `RealtimeSocket`. SSE is built in through `realtime.sse()`.
+
+For multi-instance deployment, replace the memory broker/presence store with shared `RealtimeBroker` and `RealtimePresenceStore` implementations.
+
+## Testing Platform — BCP 0.2.14+
+
+Use server-only `bcp/testing` to exercise framework contracts without adding a BCP-specific test runner.
 
 ```ts
 import {
-    createOutboxDispatcher,
-} from "bcp/events";
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const app =
+    createTestApp({
+        handler:
+            createRouteTestHandler({
+                GET() {
+                    return {
+                        ok: true,
+                    };
+                },
+            }),
+    });
 
-const dispatcher =
-    createOutboxDispatcher({
-        store: outboxStore,
-        queue: jobs,
-        ownerId: "outbox-a",
+await expectResponse(
+    await app.get("/api/health")
+)
+    .status(200)
+    .json({
+        ok: true,
     });
+```
+
+Authentication tests can create a real signed BCP session:
 
-const runner =
-    dispatcher.start();
+```ts
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
+        }
+    );
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
 ```
 
-Event `order.created` is queued as `event.order.created`.
+Database tests can force rollback after assertions:
+
+```ts
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
+        );
+    }
+);
+```
 
-The dispatcher supports leases, stale recovery, retry/backoff, custom publishers, local EventBus delivery, retention cleanup and statistics.
+Additional helpers include job/workflow/outbox harnesses, `runTestMiddleware()`, fake clocks and IDs, a fake `RealtimeSocket`, realtime event assertions and `readSseEvents()`.
 
-`bcp/events` is server-only. Outbox delivery remains at-least-once, so non-repeatable downstream side effects should use idempotency protection.
+BCP does not require Jest or Vitest; these helpers work with Node `node:test` or another runner.
 
 ## Generate framework files