@chidchanun/bcp 0.2.7 → 0.2.9

package/docs/job-scheduling.md

@@ -0,0 +1,357 @@
+# Job Scheduling Platform
+
+BCP Framework `0.2.9` extends the Background Jobs Platform with recurring job schedules, dependency-free UTC cron expressions, interval schedules and a schedule-store lease contract for multi-instance deployments.
+
+Import scheduling APIs from the server-only `bcp/jobs` entrypoint:
+
+```ts
+import {
+    createJobQueue,
+    createJobScheduler,
+} from "bcp/jobs";
+```
+
+## Create a scheduler
+
+A scheduler enqueues work into an existing BCP background job queue:
+
+```ts
+import {
+    createJobQueue,
+    createJobScheduler,
+} from "bcp/jobs";
+
+export const jobs =
+    createJobQueue();
+
+export const scheduler =
+    createJobScheduler({
+        queue: jobs,
+    });
+```
+
+The scheduler does not execute application work itself. It creates normal queue jobs when a schedule becomes due; queue workers execute the registered job handlers.
+
+## Interval schedules
+
+Schedule a recurring job every five minutes:
+
+```ts
+await scheduler.schedule(
+    "cache.cleanup",
+    {
+        scope: "expired",
+    },
+    {
+        id: "cache-cleanup",
+        everyMs: 5 * 60 * 1000,
+    }
+);
+```
+
+`everyMs` must be a positive integer.
+
+By default the first run occurs one interval after the schedule is created.
+
+Use `startAt` to select the first due time explicitly:
+
+```ts
+await scheduler.schedule(
+    "report.daily",
+    {},
+    {
+        everyMs:
+            24 * 60 * 60 * 1000,
+        startAt:
+            Date.now() + 10_000,
+    }
+);
+```
+
+`startAt` accepts either a millisecond timestamp or a `Date`.
+
+## Cron schedules
+
+BCP `0.2.9` supports dependency-free five-field cron expressions:
+
+```text
+minute hour day-of-month month day-of-week
+```
+
+Example — every weekday at 09:30 UTC:
+
+```ts
+await scheduler.schedule(
+    "report.weekday",
+    {},
+    {
+        cron: "30 9 * * 1-5",
+    }
+);
+```
+
+Example — every 15 minutes:
+
+```ts
+await scheduler.schedule(
+    "sync.incremental",
+    {},
+    {
+        cron: "*/15 * * * *",
+    }
+);
+```
+
+Supported field syntax:
+
+```text
+*          every allowed value
+*/n        step
+1,5,10     list
+1-5        range
+1-10/2     range with step
+```
+
+Ranges:
+
+```text
+minute        0-59
+hour          0-23
+day-of-month  1-31
+month         1-12
+day-of-week   0-7 (0 and 7 are Sunday)
+```
+
+Cron evaluation is **UTC** in `0.2.9`. This avoids machine-local timezone differences between containers and servers.
+
+When both day-of-month and day-of-week are restricted, BCP follows conventional cron OR semantics: either field may match.
+
+Use `nextCronTime()` when application tooling needs to preview the next UTC occurrence:
+
+```ts
+import {
+    nextCronTime,
+} from "bcp/jobs";
+
+const next =
+    nextCronTime(
+        "0 2 * * *",
+        Date.now()
+    );
+```
+
+## Run due schedules manually
+
+`runDue()` is useful for deterministic tests or externally driven schedulers:
+
+```ts
+const count =
+    await scheduler.runDue();
+```
+
+The return value is the number of newly enqueued jobs.
+
+Options:
+
+```ts
+await scheduler.runDue({
+    limit: 100,
+    leaseMs: 30_000,
+});
+```
+
+Each call claims at most one occurrence per due schedule. If an application was offline for many intervals, later calls may progressively catch up.
+
+## Start a scheduler runner
+
+For a long-running Node.js process:
+
+```ts
+const runner =
+    scheduler.start({
+        pollIntervalMs: 1_000,
+        leaseMs: 30_000,
+        limit: 100,
+        onError(error) {
+            console.error(
+                "scheduler failure",
+                error
+            );
+        },
+    });
+```
+
+Graceful shutdown:
+
+```ts
+await runner.stop();
+await scheduler.close();
+await jobs.close();
+```
+
+Stopping a scheduler does not close the queue automatically because applications may run queue workers independently.
+
+## Schedule records
+
+`JobScheduleRecord` includes:
+
+```text
+id
+jobName
+payload
+schedule
+createdAt
+updatedAt
+nextRunAt
+lastRunAt
+maxAttempts
+leaseOwner
+leaseUntil
+```
+
+Inspect schedules:
+
+```ts
+const schedules =
+    await scheduler.list();
+
+const schedule =
+    await scheduler.get(
+        "cache-cleanup"
+    );
+```
+
+Remove one:
+
+```ts
+await scheduler.remove(
+    "cache-cleanup"
+);
+```
+
+Calling `schedule()` with an existing schedule id is an upsert. Use stable ids for application-owned recurring schedules.
+
+## Retry policy
+
+A schedule may forward a queue retry limit:
+
+```ts
+await scheduler.schedule(
+    "billing.reconcile",
+    {},
+    {
+        cron: "0 * * * *",
+        maxAttempts: 5,
+    }
+);
+```
+
+Retry timing is still owned by `createJobQueue()`:
+
+```ts
+const jobs =
+    createJobQueue({
+        retryDelayMs: attempt =>
+            attempt * 5_000,
+    });
+```
+
+The scheduler determines **when a recurring occurrence is created**. The queue determines **how that occurrence is retried after handler failure**.
+
+## Deterministic scheduled run IDs
+
+Scheduled occurrences receive deterministic queue ids:
+
+```text
+schedule:<schedule-id>:<scheduled-for-timestamp>
+```
+
+This provides an additional duplicate-enqueue defense if a scheduler retries the same occurrence.
+
+Applications should avoid manually creating queue job ids with the `schedule:` prefix.
+
+## Schedule store contract
+
+The built-in schedule store is process-local:
+
+```ts
+import {
+    createMemoryJobScheduleStore,
+} from "bcp/jobs";
+```
+
+It is useful for development, tests and single-process applications.
+
+Production deployments that run multiple scheduler processes or must preserve schedules across restarts should implement `JobScheduleStore` using shared durable infrastructure.
+
+Required operations:
+
+```text
+upsert
+get
+list
+remove
+acquireDue
+complete
+release
+close (optional)
+```
+
+`acquireDue()` is the critical concurrency boundary. A durable implementation should atomically claim due schedules and assign a lease owner/expiry so two scheduler instances do not both own the same occurrence.
+
+Conceptually:
+
+```text
+scheduler A ─┐
+             ├─ shared JobScheduleStore ── atomic acquireDue()
+scheduler B ─┘
+                         │
+                         ▼
+                  shared/durable queue
+```
+
+Examples of possible application adapters include PostgreSQL, Redis, DynamoDB or another transactional/atomic data store. `0.2.9` intentionally does not force one provider.
+
+## Lease behavior
+
+A scheduler runner identifies itself with `ownerId`:
+
+```ts
+const scheduler =
+    createJobScheduler({
+        queue: jobs,
+        store,
+        ownerId:
+            process.env.INSTANCE_ID,
+    });
+```
+
+If `ownerId` is omitted, BCP generates a unique process-local scheduler id.
+
+A due schedule is leased for `leaseMs`. The store releases the lease after the occurrence is committed. If a scheduler dies while holding a lease, another instance may reclaim it after lease expiry.
+
+For durable adapters, choose a lease duration longer than the expected enqueue/store round trip but short enough for acceptable recovery.
+
+## Queue durability remains separate
+
+A durable schedule store does not make the queue durable by itself.
+
+For multi-instance production you will normally need both:
+
+```text
+shared JobScheduleStore
++
+shared JobQueueAdapter
+```
+
+The built-in memory schedule store and memory queue are intentionally process-local.
+
+## Server-only boundary
+
+`bcp/jobs` is server-only. Do not import it from page components, client islands or other modules reachable from browser bundles.
+
+Use job/scheduler calls from server routes, loaders/actions, server startup modules or dedicated worker processes.
+
+## Compatibility
+
+`0.2.9` does not intentionally break `0.2.8` Background Jobs APIs. Existing queue/worker code remains valid; scheduling is additive.

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "releaseState": "unreleased",
-  "baseline": "observability-platform-v2",
+  "baseline": "job-scheduling-platform",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -19,6 +19,7 @@
     "bcp/error",
     "bcp/database",
     "bcp/auth",
+    "bcp/jobs",
     "bcp/observability",
     "bcp/server",
     "bcp/server-only",
@@ -65,6 +66,20 @@
     "prometheusMetrics": true,
     "requestMetricsMiddleware": true,
     "healthChecks": true,
+    "backgroundJobsPlatform": true,
+    "jobQueueAdapterContract": true,
+    "inMemoryJobQueue": true,
+    "delayedJobs": true,
+    "jobRetries": true,
+    "jobWorkerConcurrency": true,
+    "jobCancellation": true,
+    "jobSchedulingPlatform": true,
+    "recurringJobs": true,
+    "cronScheduling": true,
+    "intervalScheduling": true,
+    "jobScheduleStoreContract": true,
+    "schedulerLeases": true,
+    "scheduledRunDeduplication": true,
     "databaseMigrations": true,
     "databaseAdapterContract": true,
     "databasePostgresql": true,
@@ -104,7 +119,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.6",
+    "previousBaseline": "0.2.8",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -121,7 +136,9 @@
     "authSessionStore": "auth-session-store.md",
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
+    "backgroundJobs": "background-jobs.md",
+    "jobScheduling": "job-scheduling.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.7.md"
+    "releaseNotes": "releases/0.2.9.md"
   }
 }

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/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.