@chidchanun/bcp 0.2.6 → 0.2.8

package/docs/releases/0.2.8.md

@@ -0,0 +1,150 @@
+# BCP Framework 0.2.8
+
+**Milestone:** Background Jobs Platform
+
+`0.2.8` adds a framework-native server-side background-job queue contract with a process-local reference adapter, delayed execution, retries/backoff, worker concurrency and cancellation.
+
+> Release state: unreleased until the final RC sequence, tag and npm publication complete.
+
+## New public entrypoint
+
+```ts
+import {
+    createJobQueue,
+    createMemoryJobQueueAdapter,
+} from "bcp/jobs";
+```
+
+`bcp/jobs` is server-only and is protected by both package browser exports and the BCP client-boundary validator.
+
+## Queue adapter contract
+
+Applications and ecosystem packages can implement `JobQueueAdapter` for durable/shared infrastructure.
+
+The contract covers:
+
+```text
+enqueue
+reserve
+complete
+fail
+cancel
+get
+list
+close (optional)
+```
+
+`reserve()` is the adapter's atomic claim boundary for multi-worker processing.
+
+## In-memory reference adapter
+
+`createMemoryJobQueueAdapter()` provides a dependency-free process-local adapter for development, tests and prototypes.
+
+The memory adapter is intentionally not durable and cannot coordinate multiple Node.js processes or containers.
+
+## Delayed jobs
+
+```ts
+await jobs.enqueue(
+    "report.generate",
+    payload,
+    {
+        delayMs: 60_000,
+    }
+);
+```
+
+Jobs are eligible for reservation only after `availableAt`.
+
+## Retry and backoff
+
+Queues default to three maximum attempts and capped exponential retry delay.
+
+Applications can configure a fixed delay or callback:
+
+```ts
+createJobQueue({
+    defaultMaxAttempts: 5,
+    retryDelayMs: attempt =>
+        attempt * 5_000,
+});
+```
+
+Per-job `maxAttempts` overrides the queue default.
+
+## Workers
+
+```ts
+const worker =
+    jobs.startWorker({
+        concurrency: 4,
+        pollIntervalMs: 250,
+    });
+```
+
+Workers run concurrent processing loops and can be stopped gracefully.
+
+`jobs.close()` stops all workers started by that queue and closes the adapter when supported.
+
+## Cancellation
+
+```ts
+await jobs.cancel(jobId);
+```
+
+Cancelled records remain terminal; later worker completion/failure writes do not overwrite cancellation in the memory adapter.
+
+## Manual processing
+
+`processNext()` remains available for deterministic tests and custom supervisors.
+
+```ts
+const processed =
+    await jobs.processNext();
+```
+
+## Package and platform contracts
+
+`0.2.8` adds:
+
+- `bcp/jobs` to the framework package export map,
+- TypeScript path mapping for repository development,
+- server-only client-boundary enforcement,
+- Background Jobs capability metadata in `platform-manifest.json`,
+- API-manifest ownership and docs-web navigation,
+- prepared-package smoke coverage.
+
+## Compatibility
+
+`0.2.8` does not intentionally remove or rename existing `0.2.7` public APIs.
+
+Existing applications do not need to adopt background jobs.
+
+The built-in queue is opt-in and no additional runtime dependency is installed.
+
+## Delivery semantics
+
+Durable adapters should be designed for at-least-once processing. Job handlers should be idempotent when duplicate side effects are unsafe.
+
+`0.2.8` does not promise exactly-once execution.
+
+## Not included
+
+This milestone does not ship built-in adapters for Redis, PostgreSQL, SQS, RabbitMQ, Kafka, cron scheduling or workflow orchestration.
+
+Those providers/features can be layered behind the new queue contract in later versions.
+
+## Validation
+
+Before tagging/publishing `0.2.8` run:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+The final release tag must point to the exact commit that passed the complete RC sequence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -62,6 +62,16 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/auth.ts"
     },
+    "./jobs": {
+      "types": "./packages/client/src/jobs.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/jobs.ts"
+    },
+    "./observability": {
+      "types": "./packages/client/src/observability.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/observability.ts"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -28,6 +28,8 @@ const SERVER_ONLY_IMPORTS =
         "bcp/server-only",
         "bcp/database",
         "bcp/auth",
+        "bcp/jobs",
+        "bcp/observability",
     ]);
 
 export function validateClientBoundaries(

package/packages/client/src/jobs.ts

@@ -0,0 +1,16 @@
+export {
+    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 "../../server/src/jobs.js";

package/packages/client/src/observability.ts

@@ -0,0 +1,22 @@
+export {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createMetricsResponse,
+    createRequestMetricsMiddleware,
+
+    type CounterMetric,
+    type GaugeMetric,
+    type HealthCheck,
+    type HealthCheckOptions,
+    type HealthCheckReportItem,
+    type HealthCheckResult,
+    type HealthRegistry,
+    type HealthReport,
+    type HistogramMetric,
+    type HistogramOptions,
+    type MetricDefinitionOptions,
+    type MetricLabels,
+    type MetricLabelValue,
+    type MetricsRegistry,
+    type RequestMetricsOptions,
+} from "../../server/src/observability.js";