@chidchanun/bcp 0.2.8 → 0.2.10

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "releaseState": "unreleased",
-  "baseline": "background-jobs-platform",
+  "baseline": "durable-jobs-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -73,6 +73,23 @@
     "jobRetries": true,
     "jobWorkerConcurrency": true,
     "jobCancellation": true,
+    "jobSchedulingPlatform": true,
+    "recurringJobs": true,
+    "cronScheduling": true,
+    "intervalScheduling": true,
+    "jobScheduleStoreContract": true,
+    "schedulerLeases": true,
+    "scheduledRunDeduplication": true,
+    "durableJobsPlatform": true,
+    "redisJobQueueAdapter": true,
+    "redisJobScheduleStore": true,
+    "jobVisibilityTimeout": true,
+    "jobHeartbeats": true,
+    "staleJobRecovery": true,
+    "deadLetterQueue": true,
+    "deadLetterRequeue": true,
+    "jobRetentionCleanup": true,
+    "jobQueueStatistics": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -112,7 +129,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.7",
+    "previousBaseline": "0.2.9",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -130,7 +147,9 @@
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
     "backgroundJobs": "background-jobs.md",
+    "jobScheduling": "job-scheduling.md",
+    "durableJobs": "durable-jobs.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.8.md"
+    "releaseNotes": "releases/0.2.10.md"
   }
 }

package/docs/releases/0.2.10.md

@@ -0,0 +1,148 @@
+# 0.2.10 — Durable Jobs Platform
+
+**State:** unreleased development target
+
+BCP Framework `0.2.10` extends the Background Jobs and Job Scheduling platforms with durable worker lifecycle contracts, dead-letter handling, retention/statistics APIs and Redis-compatible reference adapters.
+
+## Highlights
+
+### Durable worker leases
+
+Workers can reserve jobs with a visibility timeout and stable worker identity.
+
+New job record metadata:
+
+```text
+leaseOwner
+leaseUntil
+heartbeatAt
+recoveredAt
+```
+
+When an adapter supports `heartbeat()`, BCP workers renew the lease while a handler is running.
+
+When an adapter supports `recoverStale()`, expired running jobs can be returned to the queue for at-least-once recovery.
+
+### Dead-letter queue
+
+Retry-exhausted jobs remain terminal `failed` jobs and can also be indexed in the adapter DLQ.
+
+New queue APIs:
+
+```ts
+jobs.deadLetters()
+jobs.requeueDeadLetter()
+```
+
+The built-in memory adapter and Redis-compatible adapter implement both APIs.
+
+### Queue maintenance
+
+New operational APIs:
+
+```ts
+jobs.stats()
+jobs.cleanup()
+jobs.recoverStale()
+```
+
+Statistics include queue state totals and DLQ depth.
+
+Cleanup can remove old succeeded, failed and cancelled records after an application-defined retention period.
+
+### Redis-compatible queue adapter
+
+New public API:
+
+```ts
+createRedisJobQueueAdapter()
+```
+
+The adapter consumes a minimal application-owned Redis command client exposing:
+
+```ts
+sendCommand(command: string[]): Promise<unknown>
+```
+
+BCP does not add a Redis client runtime dependency.
+
+The Redis adapter uses atomic Lua operations for:
+
+- duplicate-safe enqueue,
+- job reservation,
+- complete/fail/cancel transitions,
+- heartbeat lease renewal,
+- stale-job recovery,
+- DLQ requeue,
+- retention cleanup.
+
+The default Redis namespace is `bcp:{jobs}` so all adapter keys share one Redis Cluster hash slot.
+
+### Redis-compatible scheduler store
+
+New public API:
+
+```ts
+createRedisJobScheduleStore()
+```
+
+The scheduler store implements the `0.2.9` `JobScheduleStore` contract on shared Redis state and uses atomic schedule leasing for multi-instance schedulers.
+
+### Compiled npm runtime
+
+The published `bcp/jobs` default runtime continues to use generated `jobs.mjs` rather than requiring consumers to execute framework TypeScript directly.
+
+The Durable Jobs package smoke imports that compiled runtime and verifies the new public APIs.
+
+## Public API additions
+
+`bcp/jobs` adds:
+
+```text
+createRedisJobQueueAdapter
+createRedisJobScheduleStore
+RedisCommandClient
+RedisJobQueueAdapter
+RedisJobScheduleStore
+RedisJobsAdapterOptions
+
+CleanupJobsOptions
+DeadLetterJobRecord
+HeartbeatJobOptions
+JobQueueStats
+ProcessNextJobOptions
+RecoverStaleJobsOptions
+RequeueDeadLetterOptions
+ReserveJobOptions
+```
+
+Existing queue and scheduling APIs remain available.
+
+## Compatibility
+
+The release is intended to be backward compatible with `0.2.9`.
+
+Existing `JobQueueAdapter` implementations remain valid because durable capabilities are optional and the new reservation metadata is provided as an optional second parameter to `reserve()`.
+
+Adapters that need production visibility-timeout semantics should implement the new durable methods.
+
+## Delivery semantics
+
+Durable jobs use at-least-once processing semantics.
+
+Applications should make side-effecting handlers idempotent when duplicate execution would be unsafe.
+
+## Validation target
+
+Before tagging/publishing `0.2.10`, 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/docs/releases/0.2.9.md

@@ -0,0 +1,162 @@
+# BCP Framework 0.2.9 — Job Scheduling Platform
+
+> Release state: unreleased until the complete RC workflow passes, the release commit is tagged `v0.2.9`, and npm publication completes.
+
+BCP Framework `0.2.9` extends the `0.2.8` Background Jobs Platform with recurring schedules, dependency-free UTC cron expressions and a lease-aware schedule-store contract.
+
+## Highlights
+
+- Added `createJobScheduler()` through `bcp/jobs`.
+- Added interval-based recurring jobs with `everyMs`.
+- Added five-field UTC cron expressions.
+- Added `nextCronTime()` and `nextScheduleTime()` helpers.
+- Added `JobScheduleStore` for durable/shared scheduler state.
+- Added `createMemoryJobScheduleStore()` for local development and tests.
+- Added atomic-style `acquireDue()` lease semantics to the schedule-store contract.
+- Added deterministic scheduled queue ids to reduce duplicate enqueue risk.
+- Added scheduler polling lifecycle with `start()`, `stop()` and `close()`.
+- Added schedule inspection, removal and stable-id upsert behavior.
+- Added unit, package-smoke and platform-contract coverage.
+
+## Scheduling API
+
+```ts
+import {
+    createJobQueue,
+    createJobScheduler,
+} from "bcp/jobs";
+
+const jobs =
+    createJobQueue();
+
+const scheduler =
+    createJobScheduler({
+        queue: jobs,
+    });
+```
+
+Interval:
+
+```ts
+await scheduler.schedule(
+    "cache.cleanup",
+    {},
+    {
+        id: "cache-cleanup",
+        everyMs: 300_000,
+    }
+);
+```
+
+Cron:
+
+```ts
+await scheduler.schedule(
+    "report.weekday",
+    {},
+    {
+        cron: "30 9 * * 1-5",
+    }
+);
+```
+
+Cron evaluation is UTC in `0.2.9`.
+
+## Cron syntax
+
+Five fields are supported:
+
+```text
+minute hour day-of-month month day-of-week
+```
+
+Supported tokens:
+
+```text
+*
+*/n
+comma-separated values
+ranges
+range steps
+```
+
+Day of week accepts `0` and `7` for Sunday. When both day-of-month and day-of-week are restricted, standard cron OR semantics are used.
+
+## Scheduler lifecycle
+
+Long-running scheduler:
+
+```ts
+const runner =
+    scheduler.start({
+        pollIntervalMs: 1_000,
+        leaseMs: 30_000,
+    });
+
+// shutdown
+await runner.stop();
+await scheduler.close();
+```
+
+`runDue()` is also available for tests, external control loops and deterministic execution.
+
+## Multi-instance contract
+
+`JobScheduleStore.acquireDue()` is the scheduler concurrency boundary. Durable implementations should atomically claim due schedules with a lease owner and expiry.
+
+The default memory store is process-local and is not suitable for schedules that must survive restarts or coordinate across multiple containers.
+
+Production multi-instance systems will normally pair:
+
+```text
+shared JobScheduleStore
++
+shared JobQueueAdapter
+```
+
+`0.2.9` intentionally leaves provider choice to the application instead of forcing Redis, PostgreSQL or another queue/scheduler backend.
+
+## Duplicate protection
+
+Each scheduled occurrence uses a deterministic queue id:
+
+```text
+schedule:<schedule-id>:<scheduled-for-timestamp>
+```
+
+This complements store leasing and protects the built-in queue from enqueuing the same occurrence twice if the same schedule occurrence is retried.
+
+## Compatibility
+
+This milestone is additive. There are no intentional breaking changes from `0.2.8`.
+
+Existing `createJobQueue()`, handlers, delayed jobs, retries, workers and adapters continue to work without scheduling enabled.
+
+## Documentation
+
+New guide:
+
+```text
+docs/job-scheduling.md
+```
+
+Background jobs remain documented in:
+
+```text
+docs/background-jobs.md
+```
+
+## Validation
+
+Before tagging/publishing `0.2.9`, 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 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.8",
+  "version": "0.2.10",
   "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",
@@ -65,7 +65,7 @@
     "./jobs": {
       "types": "./packages/client/src/jobs.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",
-      "default": "./packages/client/src/jobs.ts"
+      "default": "./packages/client/src/jobs.mjs"
     },
     "./observability": {
       "types": "./packages/client/src/observability.ts",