@chidchanun/bcp 0.2.10 → 0.2.12

package/README.md

@@ -1,54 +1,37 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, authorization, database access, background jobs, recurring scheduling, observability, validation, uploads, storage and standalone Node.js production 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, observability, uploads, storage and standalone Node.js deployment.
 
-> **Development target:** `0.2.10 — Durable Jobs Platform`
+> **Development target:** `0.2.12 — Transactional Outbox & Events`
 >
-> `0.2.10` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.12` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
-## 0.2 platform
+## Current platform
 
-`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, `0.2.4` added Application Packaging, `0.2.5` added Authentication Platform v2, `0.2.6` added Authorization & Security v2, `0.2.7` added Observability Platform v2, `0.2.8` added Background Jobs Platform, `0.2.9` added recurring scheduling, and `0.2.10` adds durable worker leases, DLQ maintenance and Redis-compatible queue/scheduler adapters.
-
-Machine-readable platform contracts:
-
-```text
-docs/platform-manifest.json
-  -> runtime target, capabilities and compatibility
-
-docs/docs-web-manifest.json
-  -> documentation navigation, routes and releases
-
-docs/api-manifest.json
-  -> public package entrypoints and guide ownership
-```
-
-## Current capabilities
+BCP `0.2.x` currently includes:
 
 | Area | Capability |
 | --- | --- |
 | Application | React SSR, hydration, layouts, metadata and SPA navigation |
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
-| Server data | Route `loader.ts`, request-scoped server APIs |
-| Mutations | Route-owned `actions.ts` and `<Form>` |
-| Authentication | JWT cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout and rotation |
-| Authorization | Auth/guest/role/permission route guards, flat permissions and resource-aware policies |
-| Request security | Same-origin validation and signed CSRF tokens for unsafe mutations |
+| Server data | Route loaders and request-scoped server APIs |
+| Mutations | Route-owned actions and `<Form>` |
+| Authentication | JWT cookie sessions, optional server-side stores, revocation, logout-all and idle timeout |
+| Authorization | Auth/guest/role/permission guards and resource-aware policies |
+| Security | Same-origin validation and signed CSRF tokens |
 | Middleware | Middleware System v2 with onion execution |
-| Background jobs | Delayed jobs, retries/backoff, cancellation, concurrent workers, visibility leases, heartbeat, stale recovery and DLQ |
-| Scheduling | Recurring interval jobs, UTC cron, schedule-store leases and deterministic scheduled run IDs |
-| Durable jobs | Redis-compatible queue/schedule adapters, retention cleanup, requeue and queue statistics |
-| Observability | Structured logs, counters/gauges/histograms, Prometheus output, request metrics and health/readiness checks |
-| Validation | Typed validators and structured validation errors |
-| Error handling | HTTP error helpers and consistent error responses |
-| Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Uploads | Buffered multipart helpers and production multipart streaming |
-| Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
+| Database | MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
+| Background jobs | Delay, retry/backoff, cancellation and concurrent workers |
+| Scheduling | Interval/UTC cron schedules and scheduler leases |
+| 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 |
+| 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 |
-| Configuration | Typed `bcp.config.*`, optional `bcp.environment.*`, startup diagnostics and `bcp config check` |
-| Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
-| Production | Standalone Node.js build, application packaging, production dependency pruning, deployment manifests, Docker starter, hardening and graceful shutdown |
-| Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
+| Configuration | Typed config/environment validation and diagnostics |
+| Production | Standalone Node.js build, packaging, dependency pruning, Docker starter and graceful shutdown |
+| Documentation | Manifest-driven docs, platform metadata and API reference |
 
 ## Requirements
 
@@ -56,7 +39,7 @@ docs/api-manifest.json
 - React `19`
 - npm
 
-Database drivers are optional and provider-specific:
+Optional SQL drivers:
 
 ```text
 MySQL       mysql2
@@ -72,7 +55,7 @@ cd my-app
 npm run dev
 ```
 
-Generated projects normally keep one framework dependency key:
+Generated projects normally use one framework dependency:
 
 ```json
 {
@@ -82,55 +65,7 @@ Generated projects normally keep one framework dependency key:
 }
 ```
 
-Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application.
-
-## Configuration & environment
-
-Framework configuration stays in one of:
-
-```text
-bcp.config.ts
-bcp.config.mts
-bcp.config.js
-bcp.config.mjs
-```
-
-Application environment validation can be declared in:
-
-```text
-bcp.environment.ts
-bcp.environment.mts
-bcp.environment.js
-bcp.environment.mjs
-```
-
-Configuration precedence is:
-
-```text
-CLI override
-    ↓
-BCP_* environment
-    ↓
-bcp.config.*
-    ↓
-framework defaults
-```
-
-Validate configuration and declared environment values with:
-
-```bash
-bcp config check
-bcp config check --json
-```
-
-Variables beginning with `BCP_PUBLIC_` may be embedded in browser output. Never expose application secrets through public-prefixed variables.
-
-Read more:
-
-- [Configuration](docs/configuration.md)
-- [Environment Validation](docs/environment-validation.md)
-
-## Database Platform v2 — 0.2.3
+## Database Platform
 
 ```ts
 import {
@@ -139,14 +74,6 @@ import {
 } from "bcp/database";
 ```
 
-Built-in SQL providers:
-
-```text
-mysql
-postgresql
-sqlite
-```
-
 Migration CLI:
 
 ```bash
@@ -156,61 +83,17 @@ bcp db status
 bcp db rollback
 ```
 
-Read more:
-
-- [Database](docs/database.md)
-- [Database Migrations](docs/database-migrations.md)
-
-## Application Packaging — 0.2.4
-
-Create a fresh production build and deployment package:
-
-```bash
-bcp package
-```
-
-Output is written under:
-
-```text
-.bcp-framework/package/
-```
-
-Read more:
-
-- [Application Packaging](docs/application-packaging.md)
-- [Deployment](docs/deployment.md)
-
-## Authentication Platform v2 — 0.2.5
+## Authentication & authorization
 
 ```ts
 import {
-    auth,
     createAuth,
     createMemoryAuthSessionStore,
-    login,
-    logout,
-} from "bcp/auth";
-```
-
-Stateless signed JWT-cookie authentication remains supported. Applications that need centralized revocation can configure an `AuthSessionStore`.
-
-Read more:
-
-- [Authentication](docs/authentication.md)
-- [Auth Session Stores](docs/auth-session-store.md)
-- [Auth Route Guards](docs/auth-route-guards.md)
-
-## Authorization & Security v2 — 0.2.6
-
-```ts
-import {
-    authorize,
-    hasPermission,
     requirePermission,
 } from "bcp/auth";
 ```
 
-Request-security helpers are exposed from `bcp/server`:
+Request security is available from `bcp/server`:
 
 ```ts
 import {
@@ -220,9 +103,7 @@ import {
 } from "bcp/server";
 ```
 
-Read more: [Authorization & Security v2](docs/authorization-security.md)
-
-## Observability Platform v2 — 0.2.7
+## Observability
 
 ```ts
 import {
@@ -232,9 +113,7 @@ import {
 } from "bcp/observability";
 ```
 
-Read more: [Observability Platform v2](docs/observability.md)
-
-## Background Jobs Platform — 0.2.8
+## Background jobs
 
 ```ts
 import {
@@ -245,7 +124,7 @@ export const jobs =
     createJobQueue();
 ```
 
-Register work:
+Register typed work:
 
 ```ts
 jobs.register<{
@@ -260,24 +139,7 @@ jobs.register<{
 );
 ```
 
-Enqueue work:
-
-```ts
-await jobs.enqueue(
-    "email.welcome",
-    {
-        userId: 42,
-    },
-    {
-        delayMs: 5_000,
-        maxAttempts: 5,
-    }
-);
-```
-
-Read more: [Background Jobs Platform](docs/background-jobs.md)
-
-## Job Scheduling Platform — 0.2.9
+## Job scheduling
 
 ```ts
 import {
@@ -290,20 +152,7 @@ export const scheduler =
     });
 ```
 
-Interval schedule:
-
-```ts
-await scheduler.schedule(
-    "cache.cleanup",
-    {},
-    {
-        id: "cache-cleanup",
-        everyMs: 5 * 60 * 1000,
-    }
-);
-```
-
-UTC cron schedule:
+UTC cron example:
 
 ```ts
 await scheduler.schedule(
@@ -315,11 +164,9 @@ await scheduler.schedule(
 );
 ```
 
-Read more: [Job Scheduling Platform](docs/job-scheduling.md)
-
 ## Durable Jobs Platform — 0.2.10
 
-Workers now support visibility leases, heartbeat renewal and stale-running recovery when the configured adapter implements those capabilities:
+Workers support visibility leases, heartbeat renewal and stale-running recovery:
 
 ```ts
 const worker =
@@ -328,104 +175,202 @@ const worker =
         concurrency: 4,
         visibilityTimeoutMs: 30_000,
         heartbeatIntervalMs: 10_000,
-        pollIntervalMs: 250,
     });
 ```
 
-Retry-exhausted jobs can be inspected and requeued:
+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.
+
+## Workflow Orchestration — 0.2.11
 
 ```ts
-const failed =
-    await jobs.deadLetters();
+import {
+    createWorkflow,
+} from "bcp/workflow";
+
+export const onboarding =
+    createWorkflow<{
+        userId: number;
+    }>(
+        "user.onboarding",
+        workflow => {
+            workflow.step(
+                "profile",
+                createProfile
+            );
+
+            workflow.parallel(
+                "initialize",
+                parallel => {
+                    parallel.step(
+                        "preferences",
+                        createPreferences
+                    );
+                    parallel.step(
+                        "workspace",
+                        createWorkspace
+                    );
+                }
+            );
+
+            workflow.delay(
+                "cooldown",
+                1_000
+            );
+        }
+    );
+```
+
+Workflows support retries, compensation and optional execution through the durable job queue.
+
+## Transactional Outbox & Events — 0.2.12
+
+`0.2.12` adds the server-only `bcp/events` entrypoint.
+
+The problem it solves:
 
-await jobs.requeueDeadLetter(
-    failed[0].id,
-    {
-        delayMs: 5_000,
-        resetAttempts: true,
+```text
+DB commit succeeds
+       +
+external publish fails
+       =
+missing integration event
+```
+
+The outbox writes the event in the **same SQL transaction** as the business data:
+
+```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(
+            "INSERT INTO orders ..."
+        );
+
+        await outbox.publish(
+            tx,
+            "order.created",
+            {
+                orderId: 42,
+            },
+            {
+                aggregateId: "42",
+                correlationId: requestId,
+            }
+        );
     }
 );
 ```
 
-Operational helpers:
+Generate the outbox table migration for the configured provider:
 
 ```ts
-await jobs.recoverStale({
-    limit: 100,
-});
-
-const stats =
-    await jobs.stats();
-
-await jobs.cleanup({
-    before:
-        Date.now() -
-        7 * 24 * 60 * 60 * 1000,
-});
-```
+import {
+    createOutboxMigrationSql,
+} from "bcp/events";
 
-### Redis-compatible durable queue
+const sql =
+    createOutboxMigrationSql(
+        "postgresql"
+    );
+```
 
-BCP does not install a Redis client library. Supply an application-owned client that implements:
+Supported providers:
 
-```ts
-interface RedisCommandClient {
-    sendCommand(
-        command: string[]
-    ): Promise<unknown>;
-}
+```text
+mysql
+postgresql
+sqlite
 ```
 
-Then create the adapters:
+### Dispatcher
+
+After the SQL transaction commits, a dispatcher claims due events and delivers them:
 
 ```ts
 import {
-    createJobQueue,
-    createJobScheduler,
-    createRedisJobQueueAdapter,
-    createRedisJobScheduleStore,
-} from "bcp/jobs";
+    createOutboxDispatcher,
+} from "bcp/events";
 
-const queueAdapter =
-    createRedisJobQueueAdapter({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
+export const dispatcher =
+    createOutboxDispatcher({
+        store: outboxStore,
+        queue: jobs,
+        ownerId: "outbox-a",
+        leaseMs: 30_000,
+        batchSize: 100,
+        pollIntervalMs: 1_000,
     });
 
-export const jobs =
-    createJobQueue({
-        adapter: queueAdapter,
-    });
+const runner =
+    dispatcher.start();
+```
 
-const scheduleStore =
-    createRedisJobScheduleStore({
-        client: redisCommandClient,
-        namespace: "my-app:{jobs}",
-    });
+With `queue: jobs`, event type:
 
-export const scheduler =
-    createJobScheduler({
-        queue: jobs,
-        store: scheduleStore,
-        ownerId: "scheduler-a",
-    });
+```text
+order.created
 ```
 
-The Redis reference adapters use atomic Lua operations for reservations, visibility leases, heartbeat, stale recovery, DLQ requeue and scheduler leasing. The default namespace is `bcp:{jobs}` so keys share one Redis Cluster hash slot.
+is handed off as:
 
-A typical application may configure its Redis client with:
+```text
+event.order.created
+```
+
+Register its durable consumer:
 
-```dotenv
-REDIS_URL=redis://localhost:6379
+```ts
+jobs.register(
+    "event.order.created",
+    async ({ payload }) => {
+        await handleOrderCreated(
+            payload
+        );
+    }
+);
 ```
 
-BCP does not read `REDIS_URL` automatically; connection creation, TLS/Cluster settings and credentials remain application-owned.
+Dispatcher features include:
+
+- batched claims,
+- lease ownership,
+- stale lease recovery,
+- retry/backoff,
+- terminal failed state,
+- queue delivery,
+- custom publisher callbacks,
+- local `EventBus`,
+- retention cleanup,
+- outbox statistics.
 
-Read more: [Durable Jobs Platform](docs/durable-jobs.md)
+`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.
+
+Delivery remains **at-least-once**, so consumers that perform non-idempotent side effects should use stable event IDs/idempotency controls.
+
+Read more: [Transactional Outbox & Events](docs/transactional-outbox-events.md)
 
 ## Public entrypoints
 
-The current `0.2.x` platform contract recognizes:
+The current documented platform surface is:
 
 ```text
 bcp
@@ -437,24 +382,18 @@ bcp/error
 bcp/database
 bcp/auth
 bcp/jobs
+bcp/workflow
+bcp/events
 bcp/observability
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-Application code should use public entrypoints instead of importing framework internals under `packages/`.
-
-See:
-
-- [API Reference](docs/api-reference.md)
-- [Platform Manifest](docs/platform-manifest.json)
-- [API Manifest](docs/api-manifest.json)
+Application code should use public entrypoints instead of importing private `packages/*` implementation files.
 
 ## CLI
 
-Core commands:
-
 ```bash
 bcp dev
 bcp build
@@ -468,16 +407,7 @@ bcp inspect
 bcp version
 ```
 
-Database migrations:
-
-```bash
-bcp db create create_users
-bcp db migrate
-bcp db status
-bcp db rollback
-```
-
-Project generators:
+Generators:
 
 ```bash
 bcp generate page dashboard/users
@@ -489,23 +419,35 @@ bcp generate migration create_users
 ## Production model
 
 ```text
-Browser / API clients
-        ↓
-security + middleware + auth
-        ↓
+Browser / API
+     |
+security + auth + middleware
+     |
 loaders / actions / API routes
-        ↓
-SSR / application responses
+     |
+Database transaction
+     |\
+     | +--> transactional outbox
+     |          |
+     |      dispatcher
+     |          |
+     |      durable jobs
+     |          |
+     |       workers
+     |
+SSR / response
 
-Operational side channels:
-shared jobs + scheduler + structured logs + metrics + health/readiness
+Workflow + scheduler + logs + metrics + health
+operate alongside the request path.
 ```
 
-Raw standalone build:
+## Packaging
+
+Raw production build:
 
 ```bash
 npm run build
-npm run start
+npm start
 ```
 
 Deployment package:
@@ -518,31 +460,30 @@ bcp package
 
 The framework repository is the documentation source of truth.
 
-`bcp-docs-web` consumes:
+Machine-readable contracts:
 
 ```text
-docs/docs-web-manifest.json
 docs/platform-manifest.json
+docs/docs-web-manifest.json
 docs/api-manifest.json
 ```
 
 ## Release validation
 
-Framework releases must pass:
+Before publishing `0.2.12`:
 
 ```bash
-npm install
 npm run typecheck
 npm run test:unit
 npm run test:integration
-npm run test:package
 npm run test:e2e
+npm run test:package
 npm run rc:check
 ```
 
-`0.2.10` adds Durable Jobs Platform unit and prepared-package smoke checks covering visibility leases, heartbeat renewal, stale recovery, DLQ/requeue, retention/statistics, Redis queue/scheduler command contracts and the compiled `bcp/jobs` runtime.
+`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.
 
-Do not tag or publish until the final release commit passes the complete RC sequence.
+Do not tag or publish until the exact final release commit passes the full RC sequence.
 
 ## Release history
 
@@ -565,12 +506,16 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.8` | Background Jobs Platform |
 | `0.2.9` | Job Scheduling Platform |
 | `0.2.10` | Durable Jobs Platform |
+| `0.2.11` | Workflow Orchestration |
+| `0.2.12` | Transactional Outbox & Events |
 
 ## Roadmap
 
-`0.2.10 — Durable Jobs Platform` establishes shared production queue/scheduler adapters and worker recovery semantics while keeping the provider-neutral `bcp/jobs` contract.
+`0.2.12` closes the database-commit / external-publish gap and establishes a provider-neutral event-delivery boundary on top of Database + Durable Jobs.
+
+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.
 
-Later `0.2.x` work can add workflow orchestration, transactional outbox helpers or additional durable providers without changing the base queue/scheduler model. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+Native desktop/mobile compilation remains later roadmap work.
 
 ## License