@chidchanun/bcp 0.2.11 → 0.2.13

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.11",
+  "versionTarget": "0.2.13",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -48,16 +48,17 @@
     {
       "id": "database",
       "title": "Database",
-      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle and migrations.",
+      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle, migrations and transactional outbox integration.",
       "pages": [
         { "route": "/docs/database", "source": "database.md", "title": "Database" },
-        { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
+        { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" },
+        { "route": "/docs/transactional-outbox-events", "source": "transactional-outbox-events.md", "title": "Transactional Outbox & Events" }
       ]
     },
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, durable background jobs, scheduling, workflow orchestration, observability, logging, caching, security and production hardening.",
+      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
@@ -67,6 +68,7 @@
         { "route": "/docs/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling Platform" },
         { "route": "/docs/durable-jobs", "source": "durable-jobs.md", "title": "Durable Jobs Platform" },
         { "route": "/docs/workflow-orchestration", "source": "workflow-orchestration.md", "title": "Workflow Orchestration" },
+        { "route": "/docs/realtime-platform", "source": "realtime-platform.md", "title": "Realtime Platform" },
         { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
         { "route": "/docs/security", "source": "security.md", "title": "Security" },
         { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
@@ -112,7 +114,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11", "state": "unreleased" },
+    { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13", "state": "unreleased" },
+    { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12" },
+    { "route": "/releases/0.2.11", "source": "releases/0.2.11.md", "version": "0.2.11" },
     { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10" },
     { "route": "/releases/0.2.9", "source": "releases/0.2.9.md", "version": "0.2.9" },
     { "route": "/releases/0.2.8", "source": "releases/0.2.8.md", "version": "0.2.8" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "releaseState": "unreleased",
-  "baseline": "workflow-orchestration",
+  "baseline": "realtime-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -21,6 +21,8 @@
     "bcp/auth",
     "bcp/jobs",
     "bcp/workflow",
+    "bcp/events",
+    "bcp/realtime",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -100,6 +102,25 @@
     "workflowDelays": true,
     "workflowCompensation": true,
     "workflowQueueExecution": true,
+    "transactionalOutboxEvents": true,
+    "outboxStoreContract": true,
+    "sqlOutboxStore": true,
+    "outboxDispatcher": true,
+    "outboxDispatcherLeases": true,
+    "outboxRetryRecovery": true,
+    "outboxRetentionCleanup": true,
+    "outboxStatistics": true,
+    "eventBus": true,
+    "outboxJobDelivery": true,
+    "realtimePlatform": true,
+    "realtimeBrokerContract": true,
+    "realtimePresenceStore": true,
+    "realtimeChannels": true,
+    "realtimeChannelAuthorization": true,
+    "realtimeSocketAdapter": true,
+    "realtimeServerSentEvents": true,
+    "realtimeHeartbeats": true,
+    "realtimeCrossHubBroadcast": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -139,7 +160,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.10",
+    "previousBaseline": "0.2.12",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -160,7 +181,9 @@
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
     "workflowOrchestration": "workflow-orchestration.md",
+    "transactionalOutboxEvents": "transactional-outbox-events.md",
+    "realtimePlatform": "realtime-platform.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.11.md"
+    "releaseNotes": "releases/0.2.13.md"
   }
 }

package/docs/realtime-platform.md

@@ -0,0 +1,447 @@
+# Realtime Platform
+
+BCP Framework `0.2.13` adds the server-only `bcp/realtime` entrypoint for application realtime delivery without forcing one WebSocket or pub/sub provider.
+
+The platform separates four concerns:
+
+```text
+connection/session
+      |
+      +--> channel membership
+      +--> authentication / authorization
+      +--> heartbeat
+      |
+      v
+RealtimeHub
+      |
+      +--> RealtimeBroker
+      |       -> cross-hub delivery
+      |
+      +--> RealtimePresenceStore
+      |       -> room/channel presence
+      |
+      +--> RealtimeSocket adapter
+      |       -> WebSocket provider integration
+      |
+      +--> SSE Response
+              -> built-in HTTP streaming
+```
+
+## Create a hub
+
+```ts
+import {
+    createRealtime,
+} from "bcp/realtime";
+
+export const realtime =
+    createRealtime();
+```
+
+The default broker and presence store are process-local and intended for development, tests and single-process deployments.
+
+## Channels and rooms
+
+BCP treats rooms as named channels.
+
+```ts
+const connection =
+    await realtime.connect();
+
+await connection.join(
+    "orders:42"
+);
+```
+
+Broadcast to everyone currently joined:
+
+```ts
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
+```
+
+You can exclude one connection when echo suppression is needed:
+
+```ts
+await realtime.broadcast(
+    "chat:general",
+    "chat.message",
+    message,
+    {
+        excludeConnectionId:
+            sender.id,
+    }
+);
+```
+
+## Presence
+
+Presence is stored separately from message delivery.
+
+```ts
+await connection.join(
+    "project:7",
+    {
+        presence: {
+            status: "online",
+        },
+    }
+);
+
+const members =
+    await realtime.members(
+        "project:7"
+    );
+```
+
+The default `createMemoryRealtimePresenceStore()` is local-only. Multi-instance deployments should use a shared store whose `join`, `leave`, `leaveConnection`, `touch` and `list` operations are visible to every instance.
+
+## Authentication
+
+A realtime connection may be authenticated when it is created:
+
+```ts
+const realtime =
+    createRealtime({
+        authenticate:
+            async ({ request }) => {
+                if (!request) {
+                    return null;
+                }
+
+                return loadRealtimeUser(
+                    request
+                );
+            },
+
+        getUserId:
+            user => user.id,
+    });
+```
+
+The authenticated value is available as:
+
+```ts
+connection.user
+```
+
+BCP does not automatically turn a failed authentication callback into a rejected connection. Applications that require authentication should enforce that policy in their authentication callback/adapter or channel authorization policy.
+
+## Channel authorization
+
+```ts
+const realtime =
+    createRealtime({
+        authorizeChannel:
+            async ({
+                connection,
+                channel,
+            }) => {
+                if (
+                    channel.startsWith(
+                        "private:"
+                    )
+                ) {
+                    return Boolean(
+                        connection.user
+                    );
+                }
+
+                return true;
+            },
+    });
+```
+
+Authorization is evaluated before a connection joins a channel.
+
+## Client-originated events
+
+Register a server event handler:
+
+```ts
+realtime.on(
+    "chat.message",
+    async ({
+        connection,
+        channel,
+        payload,
+    }) => {
+        await saveMessage(
+            payload
+        );
+
+        await realtime.broadcast(
+            channel,
+            "chat.message",
+            payload,
+            {
+                excludeConnectionId:
+                    connection.id,
+            }
+        );
+    }
+);
+```
+
+Calling `connection.emit()` runs registered server handlers. It does not automatically broadcast the message. This keeps application authorization and mutation logic explicit.
+
+## WebSocket adapter contract
+
+BCP does not install `ws`, Socket.IO, uWebSockets.js or another WebSocket server package.
+
+Adapt your selected provider to this shape:
+
+```ts
+interface RealtimeSocket {
+    send(
+        data: string
+    ): void | Promise<void>;
+
+    close?(
+        code?: number,
+        reason?: string
+    ): void | Promise<void>;
+
+    onMessage(
+        listener: (
+            data: string
+        ) => void | Promise<void>
+    ): () => void;
+
+    onClose(
+        listener: () =>
+            void | Promise<void>
+    ): () => void;
+
+    onError?(
+        listener: (
+            error: unknown
+        ) => void | Promise<void>
+    ): () => void;
+}
+```
+
+Attach it:
+
+```ts
+const connection =
+    await realtime.attachSocket(
+        socketAdapter,
+        {
+            request,
+        }
+    );
+```
+
+### Socket message protocol
+
+Inbound JSON messages use these shapes:
+
+```json
+{
+  "type": "join",
+  "channel": "chat:general",
+  "presence": {
+    "status": "online"
+  }
+}
+```
+
+```json
+{
+  "type": "leave",
+  "channel": "chat:general"
+}
+```
+
+```json
+{
+  "type": "event",
+  "channel": "chat:general",
+  "event": "chat.message",
+  "payload": {
+    "text": "hello"
+  }
+}
+```
+
+Heartbeat input:
+
+```json
+{
+  "type": "ping"
+}
+```
+
+The server answers with a `realtime.pong` event.
+
+## Server-Sent Events
+
+SSE does not require a WebSocket provider.
+
+```ts
+export function GET(
+    request: Request
+) {
+    return realtime.sse(
+        "jobs:42",
+        {
+            signal:
+                request.signal,
+        }
+    );
+}
+```
+
+Equivalent standalone helper:
+
+```ts
+import {
+    createRealtimeSseResponse,
+} from "bcp/realtime";
+
+return createRealtimeSseResponse(
+    realtime,
+    "jobs:42",
+    {
+        signal:
+            request.signal,
+    }
+);
+```
+
+The response includes:
+
+```text
+Content-Type: text/event-stream
+Cache-Control: no-cache, no-transform
+Connection: keep-alive
+X-Accel-Buffering: no
+```
+
+Optional settings include `retryMs`, `keepAliveMs`, an event-name filter and additional response headers.
+
+## Heartbeat and stale connections
+
+```ts
+const realtime =
+    createRealtime({
+        heartbeatTimeoutMs:
+            60_000,
+    });
+
+const heartbeat =
+    realtime.startHeartbeat({
+        intervalMs: 20_000,
+    });
+```
+
+The heartbeat runner sends `realtime.ping` and calls `sweepStale()` periodically.
+
+A client `ping` message or any valid socket message updates the connection's `lastSeenAt` timestamp.
+
+Shutdown:
+
+```ts
+await heartbeat.stop();
+await realtime.close();
+```
+
+## Cross-instance broker
+
+`RealtimeBroker` is the pub/sub boundary:
+
+```ts
+interface RealtimeBroker {
+    publish(
+        message: RealtimeEnvelope
+    ): Promise<void>;
+
+    subscribe(
+        listener: (
+            message: RealtimeEnvelope
+        ) => void | Promise<void>
+    ): () => void;
+}
+```
+
+The built-in memory broker can be shared by multiple hubs in one process and is useful for tests.
+
+For multiple Node processes or containers, implement the broker using shared infrastructure such as Redis Pub/Sub, NATS or another application-selected service.
+
+A production topology may look like:
+
+```text
+Browser A -> App A ----\
+                       Shared Broker
+Browser B -> App B ----/
+          |             |
+          +---- Shared Presence Store
+```
+
+BCP intentionally does not install or own a Redis/NATS connection.
+
+## Jobs, workflows and events
+
+Realtime is designed to be the delivery edge for existing backend systems.
+
+Job progress:
+
+```ts
+await realtime.broadcast(
+    `jobs:${job.id}`,
+    "job.progress",
+    {
+        progress: 60,
+    }
+);
+```
+
+Workflow progress:
+
+```ts
+await realtime.broadcast(
+    `workflow:${run.id}`,
+    "workflow.updated",
+    run
+);
+```
+
+Outbox/event delivery can broadcast after durable publication/consumption according to application semantics.
+
+Do not treat a transient realtime broadcast as a durable event store. Important business events should continue to use the transactional outbox/durable queue path.
+
+## Delivery semantics
+
+Realtime delivery is transient. A disconnected client can miss a broadcast.
+
+Use:
+
+- database/outbox for durable business facts,
+- jobs/workflows for durable background execution,
+- realtime for live client delivery.
+
+For reconnect catch-up, expose application state or an event history endpoint and let the client refetch after reconnecting.
+
+## Security
+
+`bcp/realtime` is server-only.
+
+Applications should:
+
+- authenticate connections where required,
+- authorize every private channel join,
+- validate client event payloads,
+- rate-limit untrusted client messages when appropriate,
+- avoid placing secrets in broadcast payloads,
+- use TLS (`wss:` / HTTPS) in production,
+- apply origin checks at the WebSocket upgrade boundary when browser-origin restrictions are required.
+
+## 0.2.13 scope
+
+`0.2.13` provides the provider-neutral realtime runtime contract. It does not add a built-in Redis broker, WebSocket server dependency, durable message replay or browser client SDK.

package/docs/releases/0.2.12.md

@@ -0,0 +1,147 @@
+# BCP Framework 0.2.12 — Transactional Outbox & Events
+
+Release state: unreleased development target.
+
+`0.2.12` adds a server-only transactional outbox and event-delivery platform that bridges BCP Database transactions with durable jobs or application-owned publishers without performing external side effects inside the business transaction.
+
+## New public entrypoint
+
+```ts
+import {
+    createEventBus,
+    createMemoryOutboxStore,
+    createOutboxDispatcher,
+    createOutboxMigrationSql,
+    createSqlOutboxStore,
+    createTransactionalOutbox,
+} from "bcp/events";
+```
+
+`bcp/events` is server-only and receives the same browser/client boundary protection as `bcp/database`, `bcp/jobs` and `bcp/workflow`.
+
+## Transaction-bound outbox writes
+
+Application code can insert business rows and outbox rows through the same `TransactionDatabase`:
+
+```ts
+await db.transaction(async tx => {
+    await tx.execute(
+        "INSERT INTO orders ..."
+    );
+
+    await outbox.publish(
+        tx,
+        "order.created",
+        {
+            orderId: 42,
+        }
+    );
+});
+```
+
+`createSqlOutboxStore()` writes through the caller transaction rather than the root database connection.
+
+## SQL providers
+
+Provider-specific migration SQL is available for:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+The SQL store persists:
+
+- event ID/type/payload,
+- metadata,
+- correlation/causation/aggregate IDs,
+- state,
+- attempts/max attempts,
+- created/available/processing/published/failed timestamps,
+- delivery errors,
+- lease owner/expiry.
+
+## Dispatcher
+
+`createOutboxDispatcher()` adds:
+
+- batched claiming,
+- dispatcher leases,
+- stale-lease recovery,
+- retry/backoff,
+- terminal failed state,
+- durable job-queue handoff,
+- custom publisher delivery,
+- in-process EventBus delivery,
+- polling runner lifecycle,
+- cleanup/statistics through the store.
+
+## Durable job handoff
+
+With `queue: jobs`, event type:
+
+```text
+order.created
+```
+
+is handed off as:
+
+```text
+event.order.created
+```
+
+The queued payload contains the event envelope and uses stable job ID:
+
+```text
+outbox:<event-id>
+```
+
+A successful enqueue marks the outbox event `published`. Downstream job completion remains the responsibility of the job runtime.
+
+## Event bus
+
+`createEventBus()` provides local server-side handler registration and sequential event delivery for tests, local composition and single-process handlers.
+
+It is not a distributed durable broker.
+
+## States
+
+```text
+pending
+processing
+published
+failed
+```
+
+Expired `processing` leases can return to `pending` for another dispatcher attempt.
+
+## Delivery semantics
+
+The platform closes the database-commit / external-publish gap but intentionally uses at-least-once delivery semantics.
+
+Consumers should use stable event IDs and application-level idempotency when duplicate external side effects are unsafe.
+
+## Backward compatibility
+
+`0.2.12` is additive relative to `0.2.11`:
+
+- existing `bcp/jobs` APIs remain unchanged,
+- existing `bcp/workflow` APIs remain unchanged,
+- no database adapter contract method was removed,
+- existing applications do not need an outbox unless they opt into `bcp/events`.
+
+## Validation
+
+The release candidate must pass:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Package validation executes the compiled `events.mjs` runtime and verifies the `bcp/events` export, transaction/outbox API, dispatcher delivery and migration helper.