@chidchanun/bcp 0.2.12 → 0.2.14

package/README.md

@@ -1,15 +1,13 @@
 # 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, 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, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.12 — Transactional Outbox & Events`
+> **Development target:** `0.2.14 — Testing Platform`
 >
-> `0.2.12` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.14` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
-BCP `0.2.x` currently includes:
-
 | Area | Capability |
 | --- | --- |
 | Application | React SSR, hydration, layouts, metadata and SPA navigation |
@@ -26,6 +24,8 @@ BCP `0.2.x` currently includes:
 | Durable jobs | Redis-compatible queue/schedule adapters, visibility timeout, heartbeat, stale recovery and DLQ |
 | 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 |
 | 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 |
@@ -65,86 +65,29 @@ Generated projects normally use one framework dependency:
 }
 ```
 
-## Database Platform
+## Core backend entrypoints
 
 ```ts
-import {
-    db,
-    createDatabase,
-} from "bcp/database";
+import { db } from "bcp/database";
+import { createAuth } from "bcp/auth";
+import { createJobQueue } from "bcp/jobs";
+import { createWorkflow } from "bcp/workflow";
+import { createTransactionalOutbox } from "bcp/events";
+import { createRealtime } from "bcp/realtime";
+import { createTestApp } from "bcp/testing";
+import { createMetricsRegistry } from "bcp/observability";
 ```
 
-Migration CLI:
-
-```bash
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
-```
-
-## Authentication & authorization
-
-```ts
-import {
-    createAuth,
-    createMemoryAuthSessionStore,
-    requirePermission,
-} from "bcp/auth";
-```
-
-Request security is available from `bcp/server`:
-
-```ts
-import {
-    createCsrfToken,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-} from "bcp/server";
-```
-
-## Observability
-
-```ts
-import {
-    createHealthRegistry,
-    createMetricsRegistry,
-    createMetricsResponse,
-} from "bcp/observability";
-```
-
-## Background jobs
+## Durable jobs and scheduling
 
 ```ts
 import {
     createJobQueue,
+    createJobScheduler,
 } from "bcp/jobs";
 
 export const jobs =
     createJobQueue();
-```
-
-Register typed work:
-
-```ts
-jobs.register<{
-    userId: number;
-}>(
-    "email.welcome",
-    async ({ payload }) => {
-        await sendWelcomeEmail(
-            payload.userId
-        );
-    }
-);
-```
-
-## Job scheduling
-
-```ts
-import {
-    createJobScheduler,
-} from "bcp/jobs";
 
 export const scheduler =
     createJobScheduler({
@@ -152,33 +95,7 @@ export const scheduler =
     });
 ```
 
-UTC cron example:
-
-```ts
-await scheduler.schedule(
-    "report.weekday",
-    {},
-    {
-        cron: "30 9 * * 1-5",
-    }
-);
-```
-
-## Durable Jobs Platform — 0.2.10
-
-Workers support visibility leases, heartbeat renewal and stale-running recovery:
-
-```ts
-const worker =
-    jobs.startWorker({
-        workerId: "email-worker",
-        concurrency: 4,
-        visibilityTimeoutMs: 30_000,
-        heartbeatIntervalMs: 10_000,
-    });
-```
-
-Redis-compatible adapters are available from `bcp/jobs`. BCP does not install or own the Redis client; applications provide a command client and manage credentials/TLS/Cluster/lifecycle themselves.
+Production adapters can provide Redis-compatible durable queue/schedule storage without BCP owning the Redis connection.
 
 ## Workflow Orchestration — 0.2.11
 
@@ -220,45 +137,13 @@ export const onboarding =
     );
 ```
 
-Workflows support retries, compensation and optional execution through the durable job queue.
+Workflows support retries, compensation, persisted delays and optional durable queue execution.
 
 ## Transactional Outbox & Events — 0.2.12
 
-`0.2.12` adds the server-only `bcp/events` entrypoint.
-
-The problem it solves:
-
-```text
-DB commit succeeds
-       +
-external publish fails
-       =
-missing integration event
-```
-
-The outbox writes the event in the **same SQL transaction** as the business data:
+Use the same SQL transaction for business data and its outbox event:
 
 ```ts
-import {
-    db,
-} from "bcp/database";
-
-import {
-    createSqlOutboxStore,
-    createTransactionalOutbox,
-} from "bcp/events";
-
-const outboxStore =
-    createSqlOutboxStore({
-        database: db,
-        driver: "postgresql",
-    });
-
-const outbox =
-    createTransactionalOutbox({
-        store: outboxStore,
-    });
-
 await db.transaction(
     async tx => {
         await tx.execute(
@@ -270,107 +155,221 @@ await db.transaction(
             "order.created",
             {
                 orderId: 42,
-            },
-            {
-                aggregateId: "42",
-                correlationId: requestId,
             }
         );
     }
 );
 ```
 
-Generate the outbox table migration for the configured provider:
+After commit, an outbox dispatcher can deliver through `bcp/jobs`, a custom publisher or the local event bus.
+
+Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
+
+## Realtime Platform — 0.2.13
 
 ```ts
 import {
-    createOutboxMigrationSql,
-} from "bcp/events";
+    createRealtime,
+} from "bcp/realtime";
 
-const sql =
-    createOutboxMigrationSql(
-        "postgresql"
-    );
+export const realtime =
+    createRealtime();
 ```
 
-Supported providers:
+Join a channel and broadcast:
 
-```text
-mysql
-postgresql
-sqlite
+```ts
+const connection =
+    await realtime.connect();
+
+await connection.join(
+    "orders:42"
+);
+
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
 ```
 
-### Dispatcher
+BCP intentionally does not install a WebSocket server library. Applications adapt `ws`, uWebSockets.js or another transport to `RealtimeSocket`. SSE is built in through Web `Response`.
+
+Read more: [Realtime Platform](docs/realtime-platform.md)
+
+## Testing Platform — 0.2.14
 
-After the SQL transaction commits, a dispatcher claims due events and delivers them:
+`0.2.14` adds the server-only `bcp/testing` entrypoint. It is test-runner neutral and does not add Jest or Vitest as framework dependencies.
+
+### Request and route tests
 
 ```ts
 import {
-    createOutboxDispatcher,
-} from "bcp/events";
+    createRouteTestHandler,
+    createTestApp,
+    expectResponse,
+} from "bcp/testing";
+
+const handler =
+    createRouteTestHandler({
+        GET() {
+            return {
+                ok: true,
+            };
+        },
+    });
 
-export const dispatcher =
-    createOutboxDispatcher({
-        store: outboxStore,
-        queue: jobs,
-        ownerId: "outbox-a",
-        leaseMs: 30_000,
-        batchSize: 100,
-        pollIntervalMs: 1_000,
+const app =
+    createTestApp({
+        handler,
     });
 
-const runner =
-    dispatcher.start();
+const response =
+    await app.get(
+        "/api/health"
+    );
+
+await expectResponse(response)
+    .status(200)
+    .json({
+        ok: true,
+    });
 ```
 
-With `queue: jobs`, event type:
+`createTestApp()` keeps an in-memory cookie jar, supports default headers and can send JSON bodies directly.
 
-```text
-order.created
-```
+### Authentication tests
 
-is handed off as:
+Create a real signed BCP session token instead of a fake test-only user header:
 
-```text
-event.order.created
+```ts
+import {
+    createTestAuthSession,
+} from "bcp/testing";
+
+const session =
+    await createTestAuthSession(
+        {
+            id: 42,
+            role: "admin",
+        },
+        {
+            secret:
+                process.env.BCP_SESSION_SECRET,
+            store:
+                authSessionStore,
+        }
+    );
+
+app.setCookie(
+    session.cookieName,
+    session.token
+);
 ```
 
-Register its durable consumer:
+When `store` is provided, the matching server-side auth session record is inserted as well.
+
+### Rollback database tests
 
 ```ts
-jobs.register(
-    "event.order.created",
-    async ({ payload }) => {
-        await handleOrderCreated(
-            payload
+import {
+    withTestTransaction,
+} from "bcp/testing";
+
+await withTestTransaction(
+    db,
+    async tx => {
+        await tx.execute(
+            "INSERT INTO users ..."
         );
+
+        // assertions run here
     }
 );
 ```
 
-Dispatcher features include:
+The callback uses the real BCP transaction and is deliberately rolled back after the test callback succeeds.
 
-- batched claims,
-- lease ownership,
-- stale lease recovery,
-- retry/backoff,
-- terminal failed state,
-- queue delivery,
-- custom publisher callbacks,
-- local `EventBus`,
-- retention cleanup,
-- outbox statistics.
+### Infrastructure harnesses
 
-`published` means the configured destination accepted the event. For queue delivery, it means enqueue succeeded; it does not mean the downstream job handler has completed.
+```ts
+import {
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createWorkflowTestHarness,
+} from "bcp/testing";
+```
 
-Delivery remains **at-least-once**, so consumers that perform non-idempotent side effects should use stable event IDs/idempotency controls.
+These harnesses use the real platform contracts rather than separate mock implementations.
 
-Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
+Background jobs:
 
-## Public entrypoints
+```ts
+const jobTest =
+    createJobTestHarness(
+        jobs
+    );
 
-The current documented platform surface is:
+await jobTest.drain();
+
+await jobTest.expectCount(
+    1,
+    {
+        name: "email.welcome",
+        state: "succeeded",
+    }
+);
+```
+
+Realtime:
+
+```ts
+const realtimeTest =
+    createRealtimeTestHarness(
+        realtime
+    );
+
+const {
+    socket,
+    connection,
+} =
+    await realtimeTest.connect();
+
+await connection.join(
+    "orders:42"
+);
+
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
+
+realtimeTest.expectEvent(
+    socket,
+    "order.updated",
+    "orders:42"
+);
+```
+
+Other testing primitives include:
+
+```text
+createFakeClock()
+createSequenceIdFactory()
+runTestMiddleware()
+createRealtimeTestSocket()
+readSseEvents()
+```
+
+Read more: [Testing Platform](docs/testing-platform.md)
+
+## Public entrypoints
 
 ```text
 bcp
@@ -384,13 +383,15 @@ bcp/auth
 bcp/jobs
 bcp/workflow
 bcp/events
+bcp/realtime
+bcp/testing
 bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-Application code should use public entrypoints instead of importing private `packages/*` implementation files.
+Application code should use public entrypoints instead of private `packages/*` implementation files.
 
 ## CLI
 
@@ -407,6 +408,15 @@ bcp inspect
 bcp version
 ```
 
+Database migrations:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
 Generators:
 
 ```bash
@@ -419,32 +429,23 @@ bcp generate migration create_users
 ## Production model
 
 ```text
-Browser / API
-     |
-security + auth + middleware
-     |
-loaders / actions / API routes
-     |
-Database transaction
-     |\
-     | +--> transactional outbox
-     |          |
-     |      dispatcher
-     |          |
-     |      durable jobs
-     |          |
-     |       workers
-     |
-SSR / response
-
-Workflow + scheduler + logs + metrics + health
-operate alongside the request path.
+Browser / API / Realtime clients
+              |
+      security + auth
+              |
+       application APIs
+       /      |       \
+ database  workflows  realtime
+    |          |         ^
+ outbox       jobs       |
+    \__________|_________/
+           durable state
+
+Testing Platform exercises these server contracts without becoming part of browser runtime.
 ```
 
 ## Packaging
 
-Raw production build:
-
 ```bash
 npm run build
 npm start
@@ -458,8 +459,6 @@ bcp package
 
 ## Documentation Platform
 
-The framework repository is the documentation source of truth.
-
 Machine-readable contracts:
 
 ```text
@@ -470,7 +469,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.12`:
+Before publishing `0.2.14`:
 
 ```bash
 npm run typecheck
@@ -481,7 +480,7 @@ npm run test:package
 npm run rc:check
 ```
 
-`0.2.12` adds unit and prepared-package smoke coverage for transaction-bound outbox writes, dispatcher queue handoff, retry/failure behavior, stale lease recovery, SQL migration generation, public export/runtime compilation and browser boundary enforcement.
+`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.
 
 Do not tag or publish until the exact final release commit passes the full RC sequence.
 
@@ -508,12 +507,14 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.10` | Durable Jobs Platform |
 | `0.2.11` | Workflow Orchestration |
 | `0.2.12` | Transactional Outbox & Events |
+| `0.2.13` | Realtime Platform |
+| `0.2.14` | Testing Platform |
 
 ## Roadmap
 
-`0.2.12` closes the database-commit / external-publish gap and establishes a provider-neutral event-delivery boundary on top of Database + Durable Jobs.
+`0.2.14` establishes framework-native testing for the current BCP application/runtime stack without coupling the framework to a specific test runner.
 
-The next logical milestone is **`0.2.13 — Realtime Platform`**, adding WebSocket/SSE channels, rooms/presence, authenticated realtime connections and live delivery for workflow/job/event progress without changing the current outbox/job contracts.
+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.
 
 Native desktop/mobile compilation remains later roadmap work.