@chidchanun/bcp 0.2.7 → 0.2.8

package/README.md

@@ -1,14 +1,14 @@
 # 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, 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, guarded application flows, API routes, authentication, authorization, database access, background jobs, observability, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.7 — Observability Platform v2`
+> **Development target:** `0.2.8 — Background Jobs Platform`
 >
-> `0.2.7` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.8` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 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, and `0.2.7` adds dependency-free metrics, Prometheus exposition, request metrics and health/readiness checks without intentionally changing the existing application model.
+`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, and `0.2.8` adds a provider-neutral background-job queue/worker contract with delayed work, retry/backoff, cancellation and process-local reference storage.
 
 Machine-readable platform contracts:
 
@@ -35,6 +35,7 @@ docs/api-manifest.json
 | 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 |
 | Middleware | Middleware System v2 with onion execution |
+| Background jobs | Adapter contract, in-memory queue, delayed jobs, retries/backoff, cancellation and concurrent workers |
 | 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 |
@@ -340,56 +341,80 @@ export function GET() {
 }
 ```
 
-Instrument HTTP requests through Middleware System v2:
+Health/readiness registry:
 
 ```ts
 import {
-    createRequestMetricsMiddleware,
+    createHealthRegistry,
 } from "bcp/observability";
 
-export const requestMetrics =
-    createRequestMetricsMiddleware(
-        metrics
-    );
+export const health =
+    createHealthRegistry();
 ```
 
-Default request metrics use only bounded labels:
-
-```text
-bcp_http_requests_total{method,status}
-bcp_http_request_duration_seconds{method,status}
-```
+Read more: [Observability Platform v2](docs/observability.md)
 
-Raw paths are not attached by default.
+## Background Jobs Platform — 0.2.8
 
-Health/readiness registry:
+Create a server-side queue:
 
 ```ts
 import {
-    createHealthRegistry,
-} from "bcp/observability";
+    createJobQueue,
+} from "bcp/jobs";
 
-export const health =
-    createHealthRegistry();
+export const jobs =
+    createJobQueue();
+```
+
+Register a handler:
 
-health.register(
-    "database",
-    async () => {
-        await db.query("SELECT 1");
-        return true;
+```ts
+jobs.register<{
+    userId: number;
+}>(
+    "email.welcome",
+    async ({ payload }) => {
+        await sendWelcomeEmail(
+            payload.userId
+        );
     }
 );
 ```
 
-Use:
+Enqueue immediately or with a delay:
 
 ```ts
-return health.response();
+await jobs.enqueue(
+    "email.welcome",
+    {
+        userId: 42,
+    },
+    {
+        delayMs: 5_000,
+        maxAttempts: 5,
+    }
+);
 ```
 
-Health responses return `200` when every check passes and `503` when any registered dependency is unhealthy or times out.
+Start concurrent workers:
 
-Read more: [Observability Platform v2](docs/observability.md)
+```ts
+const worker =
+    jobs.startWorker({
+        concurrency: 4,
+        pollIntervalMs: 250,
+    });
+
+// graceful shutdown
+await worker.stop();
+```
+
+The default in-memory adapter is process-local and is intended for development/tests/prototypes. Durable multi-process deployments should implement `JobQueueAdapter` against shared infrastructure. Adapter `reserve()` must atomically claim work.
+
+Retry behavior is configurable with fixed or callback-based backoff. The default is capped exponential backoff. Jobs can also be cancelled and inspected with `get()` / `list()`.
+
+Read more: [Background Jobs Platform](docs/background-jobs.md)
 
 ## Public entrypoints
 
@@ -404,6 +429,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/jobs
 bcp/observability
 bcp/server
 bcp/server-only
@@ -469,7 +495,7 @@ React SSR
 Hydration / SPA navigation
 
 Operational side channels:
-structured logs + metrics + health/readiness
+background jobs + structured logs + metrics + health/readiness
 ```
 
 ## Production build
@@ -515,7 +541,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.7` adds Observability Platform v2 unit and prepared-package smoke checks covering metrics, Prometheus exposition, request timing, cardinality-safe default labels, health/readiness responses and timeout handling.
+`0.2.8` adds Background Jobs Platform unit and prepared-package smoke checks covering delayed work, retries/backoff, cancellation, worker concurrency, server-only boundaries and the public `bcp/jobs` package surface.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -537,12 +563,13 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
 | `0.2.7` | Observability Platform v2 |
+| `0.2.8` | Background Jobs Platform |
 
 ## Roadmap
 
-`0.2.7 — Observability Platform v2` establishes process-level metrics and health/readiness contracts on top of the existing structured logging and Middleware System v2 runtime.
+`0.2.8 — Background Jobs Platform` establishes a provider-neutral queue/worker contract on top of the existing server runtime and lifecycle model.
 
-Future `0.2.x` work can add distributed tracing or exporter integrations without changing the application metrics/health contract introduced here. Native `.exe`, desktop and mobile compilation remain later roadmap work.
+Later `0.2.x` work can add durable queue providers, recurring schedules, distributed leases or workflow orchestration without changing the base enqueue/worker contract. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.7 — Observability Platform v2`
+> **Documentation target:** BCP Framework `0.2.8 — Background Jobs Platform`
 >
 > **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
 
@@ -53,48 +53,50 @@ Framework source and tests remain authoritative for runtime behavior.
 | `0.2.5` | Authentication Platform v2 |
 | `0.2.6` | Authorization & Security v2 |
 | `0.2.7` | Observability Platform v2 |
+| `0.2.8` | Background Jobs Platform |
 
-## 0.2.7 — Observability Platform v2
+## 0.2.8 — Background Jobs Platform
 
-`0.2.7` adds a server-only observability layer without adding third-party runtime dependencies.
+`0.2.8` adds a server-only provider-neutral queue/worker layer without adding a third-party queue dependency.
 
 New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `observability.md` | Metrics registry, Prometheus output, request metrics and health/readiness checks |
-| `api-reference.md` | Public `bcp/observability` exports |
-| `platform-manifest.json` | Observability capability flags and new public entrypoint |
-| `api-manifest.json` | `bcp/observability` guide ownership |
-| `docs-web-manifest.json` | Observability navigation and `0.2.7` release route |
-| `releases/0.2.7.md` | Observability Platform v2 release notes |
+| `background-jobs.md` | Queue contract, memory adapter, delay, retries, workers and production guidance |
+| `api-reference.md` | Public `bcp/jobs` exports |
+| `platform-manifest.json` | Background Jobs capability flags and public entrypoint |
+| `api-manifest.json` | `bcp/jobs` guide ownership |
+| `docs-web-manifest.json` | Background Jobs navigation and `0.2.8` release route |
+| `releases/0.2.8.md` | Background Jobs Platform release notes |
 
 Primary APIs:
 
 ```ts
 import {
-    createHealthRegistry,
-    createMetricsRegistry,
-    createMetricsResponse,
-    createRequestMetricsMiddleware,
-} from "bcp/observability";
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+} from "bcp/jobs";
 ```
 
 Runtime model:
 
 ```text
-structured logs
-    +
-process-local metrics
-    +
-Prometheus exposition
-    +
-health/readiness checks
+web/API/action
+    |
+    | enqueue
+    v
+JobQueueAdapter
+    |
+    v
+worker loop(s)
+    |
+    +-> success
+    +-> retry/backoff
+    +-> failed/cancelled
 ```
 
-The request metrics middleware intentionally uses bounded `method` and `status` labels by default rather than raw paths.
-
-The built-in metrics registry is process-local; distributed aggregation remains deployment infrastructure or future exporter work.
+The built-in memory adapter is process-local and not durable. Multi-process/container production deployments should implement `JobQueueAdapter` against shared durable infrastructure.
 
 ## Update rule
 
@@ -135,11 +137,12 @@ Important current routes:
 | `/docs/authentication` | `authentication.md` |
 | `/docs/authorization-security` | `authorization-security.md` |
 | `/docs/observability` | `observability.md` |
+| `/docs/background-jobs` | `background-jobs.md` |
 | `/docs/development-logging` | `development-logging.md` |
 | `/docs/application-packaging` | `application-packaging.md` |
 | `/docs/database` | `database.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.7` | `releases/0.2.7.md` |
+| `/releases/0.2.8` | `releases/0.2.8.md` |
 
 Every route/source pair is validated by unit tests.
 
@@ -179,6 +182,7 @@ bcp/validation
 bcp/error
 bcp/database
 bcp/auth
+bcp/jobs
 bcp/observability
 bcp/server
 bcp/server-only
@@ -219,7 +223,7 @@ synchronize CMS/search/navigation
 
 ## Release validation
 
-Before publishing `0.2.7`:
+Before publishing `0.2.8`:
 
 ```bash
 npm run typecheck
@@ -230,16 +234,15 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Observability Platform v2 validation covers:
+Background Jobs Platform validation covers:
 
-- counter/gauge/histogram behavior,
-- Prometheus exposition,
-- metric definition validation,
-- request count and duration middleware,
-- cardinality-safe default request labels,
-- health/readiness response semantics,
-- health check timeout handling,
-- public `bcp/observability` exports,
+- immediate and delayed jobs,
+- retry/backoff behavior,
+- terminal success/failure/cancellation states,
+- duplicate job IDs,
+- worker concurrency and graceful stop,
+- public `bcp/jobs` exports,
+- server-only browser/client boundaries,
 - prepared npm package contents,
 - docs/platform/API version parity.
 

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -94,6 +94,17 @@
         "/docs/session-auth"
       ]
     },
+    {
+      "package": "bcp/jobs",
+      "source": "packages/client/src/jobs.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-jobs",
+      "summary": "Background job queue contract with in-memory adapter, delayed jobs, retry/backoff, cancellation and concurrent workers.",
+      "guides": [
+        "/docs/background-jobs",
+        "/docs/observability"
+      ]
+    },
     {
       "package": "bcp/observability",
       "source": "packages/client/src/observability.ts",

package/docs/api-reference.md

@@ -226,6 +226,37 @@ Authorization & Security v2 adds permission checks, permission route guards and
 
 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).
 
+## `bcp/jobs`
+
+Server-only Background Jobs Platform APIs.
+
+```ts
+import {
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+    type BackgroundJobQueue,
+    type EnqueueJobOptions,
+    type JobHandler,
+    type JobHandlerContext,
+    type JobQueueAdapter,
+    type JobQueueOptions,
+    type JobRecord,
+    type JobRetryDelay,
+    type JobState,
+    type JobWorker,
+    type MemoryJobQueueAdapter,
+    type StartJobWorkerOptions,
+} from "bcp/jobs";
+```
+
+`createJobQueue()` provides delayed enqueueing, retry/backoff, cancellation, manual `processNext()` execution and concurrent workers. The default adapter is process-local memory storage and is intended for development, tests and single-process prototypes.
+
+Production applications that require durable processing should implement `JobQueueAdapter` against shared infrastructure. Adapter `reserve()` must atomically claim one eligible queued job so multiple workers cannot process the same reservation concurrently.
+
+The queue contract is designed for practical at-least-once processing; handlers should be idempotent when duplicate side effects are unsafe.
+
+Related guides: [Background Jobs Platform](background-jobs.md), [Observability Platform v2](observability.md).
+
 ## `bcp/observability`
 
 Server-only Observability Platform v2 APIs.