@chidchanun/bcp 0.2.12 → 0.2.13

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, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.12 — Transactional Outbox & Events`
+> **Development target:** `0.2.13 — Realtime Platform`
 >
-> `0.2.12` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.2.13` 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,7 @@ 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 |
 | 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 +64,28 @@ 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 { 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 +93,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 +135,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,108 +153,182 @@ 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
+
+`0.2.13` adds the server-only `bcp/realtime` public entrypoint.
+
+Create a hub:
 
 ```ts
 import {
-    createOutboxMigrationSql,
-} from "bcp/events";
+    createRealtime,
+} from "bcp/realtime";
 
-const sql =
-    createOutboxMigrationSql(
-        "postgresql"
-    );
+export const realtime =
+    createRealtime();
 ```
 
-Supported providers:
+### Channels / rooms
 
-```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
+Rooms are represented by channel names. Connections receive broadcasts only for channels they joined.
 
-After the SQL transaction commits, a dispatcher claims due events and delivers them:
+### Presence
 
 ```ts
-import {
-    createOutboxDispatcher,
-} from "bcp/events";
+await connection.join(
+    "project:7",
+    {
+        presence: {
+            status: "online",
+        },
+    }
+);
 
-export const dispatcher =
-    createOutboxDispatcher({
-        store: outboxStore,
-        queue: jobs,
-        ownerId: "outbox-a",
-        leaseMs: 30_000,
-        batchSize: 100,
-        pollIntervalMs: 1_000,
+const members =
+    await realtime.members(
+        "project:7"
+    );
+```
+
+The built-in memory presence store is process-local. Multi-instance deployments should provide a shared `RealtimePresenceStore`.
+
+### Authentication and private channels
+
+```ts
+const realtime =
+    createRealtime({
+        authenticate:
+            async ({ request }) =>
+                request
+                    ? loadRealtimeUser(
+                        request
+                    )
+                    : null,
+
+        getUserId:
+            user => user.id,
+
+        authorizeChannel:
+            ({ connection, channel }) =>
+                !channel.startsWith(
+                    "private:"
+                ) ||
+                Boolean(
+                    connection.user
+                ),
     });
+```
+
+### WebSocket provider contract
 
-const runner =
-    dispatcher.start();
+BCP intentionally does not install `ws`, Socket.IO or another WebSocket server dependency.
+
+Adapt the selected server/provider to `RealtimeSocket`, then attach it:
+
+```ts
+const connection =
+    await realtime.attachSocket(
+        socketAdapter,
+        {
+            request,
+        }
+    );
 ```
 
-With `queue: jobs`, event type:
+The JSON socket protocol supports `join`, `leave`, `event` and `ping` messages.
 
-```text
-order.created
+### Server-Sent Events
+
+SSE is built in through Web `Response`:
+
+```ts
+export function GET(
+    request: Request
+) {
+    return realtime.sse(
+        "workflow:42",
+        {
+            signal:
+                request.signal,
+        }
+    );
+}
 ```
 
-is handed off as:
+### Cross-instance delivery
+
+`RealtimeBroker` is the provider-neutral pub/sub boundary. The built-in memory broker supports same-process hubs; production applications can implement shared Redis/NATS/etc. brokers without changing hub APIs.
 
 ```text
-event.order.created
+Browser A -> App A ----\
+                       Shared Broker
+Browser B -> App B ----/
+          |             |
+          +---- Shared Presence Store
 ```
 
-Register its durable consumer:
+### Heartbeat
 
 ```ts
-jobs.register(
-    "event.order.created",
-    async ({ payload }) => {
-        await handleOrderCreated(
-            payload
-        );
-    }
-);
+const heartbeat =
+    realtime.startHeartbeat({
+        intervalMs: 20_000,
+    });
+
+// shutdown
+await heartbeat.stop();
+await realtime.close();
 ```
 
-Dispatcher features include:
+`realtime.ping` / `realtime.pong` and `sweepStale()` provide connection liveness cleanup.
 
-- batched claims,
-- lease ownership,
-- stale lease recovery,
-- retry/backoff,
-- terminal failed state,
-- queue delivery,
-- custom publisher callbacks,
-- local `EventBus`,
-- retention cleanup,
-- outbox statistics.
+### Jobs / workflows / events integration
 
-`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.
+Realtime is the transient delivery edge for durable backend state:
+
+```ts
+await realtime.broadcast(
+    `jobs:${job.id}`,
+    "job.progress",
+    {
+        progress: 60,
+    }
+);
+```
 
-Delivery remains **at-least-once**, so consumers that perform non-idempotent side effects should use stable event IDs/idempotency controls.
+Important business facts should remain in database/outbox/jobs/workflows. Realtime delivery is transient, so reconnecting clients should refetch durable state/history when catch-up is required.
 
-Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
+Read more: [Realtime Platform](docs/realtime-platform.md)
 
 ## Public entrypoints
 
-The current documented platform surface is:
-
 ```text
 bcp
 bcp/island
@@ -384,13 +341,14 @@ bcp/auth
 bcp/jobs
 bcp/workflow
 bcp/events
+bcp/realtime
 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 +365,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 +386,21 @@ 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
 ```
 
 ## Packaging
 
-Raw production build:
-
 ```bash
 npm run build
 npm start
@@ -458,8 +414,6 @@ bcp package
 
 ## Documentation Platform
 
-The framework repository is the documentation source of truth.
-
 Machine-readable contracts:
 
 ```text
@@ -470,7 +424,7 @@ docs/api-manifest.json
 
 ## Release validation
 
-Before publishing `0.2.12`:
+Before publishing `0.2.13`:
 
 ```bash
 npm run typecheck
@@ -481,7 +435,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.13` adds unit and prepared-package smoke coverage for broker broadcasts, channel membership, presence, authentication/channel authorization, socket protocol, heartbeat cleanup, SSE streaming, 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 +462,13 @@ 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 |
 
 ## 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.13` establishes provider-neutral live delivery on top of the durable database/outbox/jobs/workflow stack.
 
-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.14 — Testing Platform`**, focused on framework-native request/route/auth/database/jobs/workflow/realtime testing utilities and application test harnesses.
 
 Native desktop/mobile compilation remains later roadmap work.