@chidchanun/bcp 0.2.12 → 0.2.14

package/docs/api-reference.md

@@ -10,7 +10,7 @@ Universal React application APIs.
 
 Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound`, loader/action/guard hooks and router/navigation APIs.
 
-Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md).
+Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/island`
 
@@ -54,7 +54,7 @@ Server-only Database Platform v2 APIs.
 
 Built-in SQL providers are MySQL, PostgreSQL and SQLite. `BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
 
-Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md).
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/auth`
 
@@ -62,7 +62,7 @@ Server-only authentication and authorization APIs.
 
 The default authentication mode remains stateless signed JWT-cookie authentication. Applications may opt into server-side session stores, revocation, logout-all, idle timeout, role/permission guards and resource-aware authorization policies.
 
-Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md).
+Related guides: [Authentication](authentication.md), [Auth Session Stores](auth-session-store.md), [Auth Route Guards](auth-route-guards.md), [Authorization & Security v2](authorization-security.md), [JWT Sessions](session-auth.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/jobs`
 
@@ -78,7 +78,7 @@ BCP does not install a Redis library and does not create the connection. Applica
 
 The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
 
-Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Observability Platform v2](observability.md).
+Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
 ## `bcp/workflow`
 
@@ -111,7 +111,7 @@ When an existing `BackgroundJobQueue` is supplied, workflow execution and delay
 
 `WorkflowStore.claim()` / `release()` form the run-level lease boundary for multi-instance stores.
 
-Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
+Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
 ## `bcp/events`
 
@@ -125,81 +125,188 @@ import {
     createOutboxMigrationSql,
     createSqlOutboxStore,
     createTransactionalOutbox,
-    type ClaimOutboxEventsOptions,
-    type CleanupOutboxOptions,
-    type EventBus,
-    type FailOutboxEventOptions,
-    type MemoryOutboxStore,
-    type OutboxDispatcher,
-    type OutboxDispatcherOptions,
-    type OutboxDispatcherRunner,
-    type OutboxEventHandler,
-    type OutboxEventHandlerContext,
-    type OutboxEventRecord,
-    type OutboxEventState,
-    type OutboxRetryDelay,
-    type OutboxStats,
-    type OutboxStore,
-    type PublishOutboxEventOptions,
-    type SqlOutboxStore,
-    type SqlOutboxStoreOptions,
-    type TransactionalOutbox,
-    type TransactionalOutboxOptions,
 } from "bcp/events";
 ```
 
-### Transactional publishing
+`createTransactionalOutbox()` writes an event through the same `TransactionDatabase` used by `db.transaction()`, allowing business rows and outbox rows to commit or roll back together.
 
-`createTransactionalOutbox()` exposes `publish(transaction, type, payload, options)`.
+`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite. `createOutboxMigrationSql()` generates the outbox table/index DDL.
 
-The supplied `TransactionDatabase` is the same object received inside `db.transaction()`, allowing the application row and outbox event row to commit or roll back together.
+`createOutboxDispatcher()` supports batched claims, leases, stale recovery, retry/backoff, terminal failure, job-queue handoff, custom publishing, local event-bus delivery and runner lifecycle.
 
-### SQL store
+Delivery is at-least-once; consumers should use idempotency controls for non-repeatable side effects.
 
-`createSqlOutboxStore()` supports MySQL, PostgreSQL and SQLite through the existing BCP database abstraction.
+Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
 
-`createOutboxMigrationSql()` generates the outbox table/index DDL for those providers.
+## `bcp/realtime`
 
-The SQL store persists payload/metadata, correlation/causation/aggregate IDs, retry counts, state timestamps and dispatcher lease information.
+Server-only Realtime Platform APIs added in `0.2.13`.
 
-### Dispatcher
+```ts
+import {
+    createMemoryRealtimeBroker,
+    createMemoryRealtimePresenceStore,
+    createRealtime,
+    createRealtimeSseResponse,
+    type RealtimeAuthenticate,
+    type RealtimeAuthorizeChannel,
+    type RealtimeBroker,
+    type RealtimeBroadcastOptions,
+    type RealtimeConnection,
+    type RealtimeEnvelope,
+    type RealtimeEventContext,
+    type RealtimeEventHandler,
+    type RealtimeHeartbeatOptions,
+    type RealtimeHeartbeatRunner,
+    type RealtimeHub,
+    type RealtimeJoinOptions,
+    type RealtimeOptions,
+    type RealtimePresenceMember,
+    type RealtimePresenceStore,
+    type RealtimeSocket,
+    type RealtimeSseOptions,
+} from "bcp/realtime";
+```
 
-`createOutboxDispatcher()` supports:
+`createRealtime()` creates a server-side hub. Connections can `join()`, `leave()`, `emit()`, `send()`, `touch()` and `disconnect()`.
 
-```text
-batched claim
-dispatcher lease
-stale recovery
-retry/backoff
-terminal failure
-durable job queue handoff
-custom publisher callback
-in-process EventBus delivery
-runner lifecycle
+`RealtimeBroker` is the cross-hub pub/sub boundary and `RealtimePresenceStore` is the channel-presence boundary. Built-in memory implementations are intended for tests/single-process use; shared deployments can supply provider adapters.
+
+`RealtimeOptions.authenticate` can resolve identity from a Request/connection payload, while `authorizeChannel` runs before channel membership is accepted.
+
+BCP does not install a WebSocket provider. `RealtimeSocket` defines the minimal transport surface consumed by `hub.attachSocket()`.
+
+`hub.sse()` and `createRealtimeSseResponse()` expose Web-standard Server-Sent Events responses with abort, filtering, retry hint and keep-alive options.
+
+Realtime delivery is transient. Use database/outbox/jobs/workflows for durable state and refetch durable state/history after reconnect when catch-up is required.
+
+Related guides: [Realtime Platform](realtime-platform.md), [Authentication](authentication.md), [Testing Platform](testing-platform.md), [Observability Platform v2](observability.md).
+
+## `bcp/testing`
+
+Server-only Testing Platform APIs added in `0.2.14`.
+
+```ts
+import {
+    createFakeClock,
+    createJobTestHarness,
+    createOutboxTestHarness,
+    createRealtimeTestHarness,
+    createRealtimeTestSocket,
+    createRouteTestHandler,
+    createSequenceIdFactory,
+    createTestApp,
+    createTestAuthSession,
+    createTestFormData,
+    createWorkflowTestHarness,
+    expectResponse,
+    readSseEvents,
+    runTestMiddleware,
+    runTestPageAction,
+    runTestPageGuards,
+    runTestPageLoader,
+    withTestTransaction,
+    type CreateTestAuthSessionOptions,
+    type FakeClock,
+    type JobTestHarness,
+    type OutboxTestHarness,
+    type ParsedSseEvent,
+    type RealtimeTestConnection,
+    type RealtimeTestHarness,
+    type RealtimeTestSocket,
+    type TestApp,
+    type TestAppOptions,
+    type TestAuthSession,
+    type TestPageActionOptions,
+    type TestPageContextOptions,
+    type TestPageGuardOptions,
+    type TestRequestHandler,
+    type TestRequestOptions,
+    type TestResponseExpectation,
+    type TestRouteFunction,
+    type TestRouteHandlerOptions,
+    type TestRouteMethod,
+    type TestRouteModule,
+    type TestTransactionDatabase,
+    type WorkflowTestHarness,
+} from "bcp/testing";
 ```
 
-With `queue` configured, event `order.created` is enqueued as `event.order.created` using stable job ID `outbox:<event-id>`.
+### Request application harness
+
+`createTestApp()` runs a Web-standard `Request -> Response` handler with convenience methods for GET/POST/PUT/PATCH/DELETE, JSON bodies, mutable default headers and an in-memory cookie jar that consumes `Set-Cookie` responses.
+
+### API route module testing
+
+`createRouteTestHandler()` adapts BCP-style method exports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`) to a Request handler. Missing methods return 405 with an `Allow` header.
+
+Return values are normalized for tests: Response is preserved, strings become text Responses, null/undefined become 204, and other values become JSON.
+
+### Page loader, guard and form action testing
+
+`runTestPageGuards()` executes one or more guards through the production `executePageGuardFunctions()` path. Guard data is chained in order and redirect/other Response short-circuits are preserved.
 
-### Stores
+`runTestPageLoader()` invokes the production `executePageLoaderFunction()` path with test params, URL/search params and optional guard data. The returned value is the normal `PageLoaderExecution` contract.
 
-`OutboxStore` is the persistence and concurrency boundary.
+`runTestPageAction()` invokes the production `executePageActionFunction()` path, including action-name/method validation, guard data, FormData and Response/data handling.
 
-`createMemoryOutboxStore()` is intended for tests and single-process development. It does not provide durable transactional persistence.
+`createTestFormData()` creates a FormData object from string/Blob fields and supports repeated values.
 
-### States
+### Response assertions
+
+`expectResponse()` exposes lightweight runner-neutral assertions:
 
 ```text
-pending
-processing
-published
-failed
+status()
+header()
+text()
+json()
+jsonMatches()
 ```
 
-`published` means the configured dispatcher destination accepted the event. It does not mean a downstream queued consumer has completed.
+BCP does not require Jest/Vitest assertion APIs.
+
+### Auth testing
+
+`createTestAuthSession()` uses the production `createSessionToken()` implementation, including HS256 signature, issuer/audience and expiration semantics. It can also register the matching server-side record in an `AuthSessionStore`.
+
+This allows route/auth tests to use a real BCP session cookie instead of introducing a test-only identity header.
+
+### Database rollback testing
+
+`withTestTransaction()` executes a callback in a real BCP database transaction and deliberately rejects the transaction with an internal rollback sentinel after the test callback succeeds. The callback result is returned to the test while the transaction is rolled back.
+
+Application callback errors remain unchanged and are not swallowed.
+
+### Middleware testing
+
+`runTestMiddleware()` invokes the actual Middleware System v2 onion pipeline through `executeMiddlewarePipeline()` and supports a custom downstream Request handler.
+
+### Deterministic utilities
+
+`createFakeClock()` exposes `now()`, `set()`, `advance()` and `reset()` for time-sensitive queues/workflows/schedulers.
+
+`createSequenceIdFactory()` creates deterministic IDs for stable assertions.
+
+### Infrastructure harnesses
+
+`createJobTestHarness()` drains currently eligible work through the real `BackgroundJobQueue.processNext()` API and exposes record/count assertions.
+
+`createWorkflowTestHarness()` can start/run workflows until terminal or waiting state and optionally force persisted delays to resume.
+
+`createOutboxTestHarness()` dispatches through the actual `OutboxDispatcher` and exposes event/state/statistics helpers.
+
+`createRealtimeTestSocket()` implements the `RealtimeSocket` adapter contract entirely in memory. `createRealtimeTestHarness()` connects that socket to a real `RealtimeHub` and can assert server-sent channel events.
+
+`readSseEvents()` reads event-stream Responses, ignores comment/retry frames and JSON-decodes `data:` payloads when possible.
+
+### Runner neutrality and boundary
+
+`bcp/testing` has no dependency on Jest or Vitest. BCP's own suite uses Node `node:test`, but the helpers can be called from another runner.
 
-Delivery is at-least-once; consumers should use idempotency controls for non-repeatable external side effects.
+The package is server-only; the client boundary validator rejects `bcp/testing` from pages/client islands.
 
-Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
+Related guides: [Testing Platform](testing-platform.md), [Authentication](authentication.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Workflow Orchestration](workflow-orchestration.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Realtime Platform](realtime-platform.md).
 
 ## `bcp/observability`
 
@@ -211,7 +318,7 @@ Related guides: [Observability Platform v2](observability.md), [Logging](develop
 
 Server request/runtime APIs including request context, cookies, CSRF and same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
 
-Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md).
+Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md), [Testing Platform](testing-platform.md).
 
 ## `bcp/server-only`
 
@@ -227,7 +334,7 @@ Related guide: [Application Modules](application-modules.md).
 
 Middleware System v2 APIs and types.
 
-Related guide: [Middleware](middleware.md).
+Related guides: [Middleware](middleware.md), [Testing Platform](testing-platform.md).
 
 ## Stability
 

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.12",
+  "versionTarget": "0.2.14",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,7 +58,7 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, durable background jobs, scheduling, workflow orchestration, event delivery, 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" },
@@ -68,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" }
@@ -87,10 +88,11 @@
     {
       "id": "developer-experience",
       "title": "Developer Experience",
-      "description": "Project generators, diagnostics, project metadata and framework maintenance tooling.",
+      "description": "Project generators, diagnostics, testing, project metadata and framework maintenance tooling.",
       "pages": [
         { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
-        { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" }
+        { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" },
+        { "route": "/docs/testing-platform", "source": "testing-platform.md", "title": "Testing Platform" }
       ]
     },
     {
@@ -113,7 +115,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.12", "source": "releases/0.2.12.md", "version": "0.2.12", "state": "unreleased" },
+    { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14", "state": "unreleased" },
+    { "route": "/releases/0.2.13", "source": "releases/0.2.13.md", "version": "0.2.13" },
+    { "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" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "releaseState": "unreleased",
-  "baseline": "transactional-outbox-events",
+  "baseline": "testing-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -22,6 +22,8 @@
     "bcp/jobs",
     "bcp/workflow",
     "bcp/events",
+    "bcp/realtime",
+    "bcp/testing",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -111,6 +113,31 @@
     "outboxStatistics": true,
     "eventBus": true,
     "outboxJobDelivery": true,
+    "realtimePlatform": true,
+    "realtimeBrokerContract": true,
+    "realtimePresenceStore": true,
+    "realtimeChannels": true,
+    "realtimeChannelAuthorization": true,
+    "realtimeSocketAdapter": true,
+    "realtimeServerSentEvents": true,
+    "realtimeHeartbeats": true,
+    "realtimeCrossHubBroadcast": true,
+    "testingPlatform": true,
+    "testRequestHarness": true,
+    "testRouteHandlers": true,
+    "testPageLoaders": true,
+    "testPageGuards": true,
+    "testFormActions": true,
+    "testResponseAssertions": true,
+    "testAuthSessions": true,
+    "testTransactionRollback": true,
+    "testMiddlewarePipeline": true,
+    "testJobHarness": true,
+    "testWorkflowHarness": true,
+    "testOutboxHarness": true,
+    "testRealtimeSocket": true,
+    "testSseReader": true,
+    "deterministicTestClock": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -150,7 +177,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.11",
+    "previousBaseline": "0.2.13",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -172,7 +199,9 @@
     "durableJobs": "durable-jobs.md",
     "workflowOrchestration": "workflow-orchestration.md",
     "transactionalOutboxEvents": "transactional-outbox-events.md",
+    "realtimePlatform": "realtime-platform.md",
+    "testingPlatform": "testing-platform.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.12.md"
+    "releaseNotes": "releases/0.2.14.md"
   }
 }