@chidchanun/bcp 0.2.8 → 0.2.10

package/docs/api-reference.md

@@ -8,26 +8,7 @@ The machine-readable source for this page is `docs/api-manifest.json`.
 
 Universal React application APIs.
 
-Common exports include:
-
-```ts
-import {
-    Form,
-    Link,
-    createIsland,
-    navigate,
-    notFound,
-    useActionData,
-    useActionError,
-    useFormStatus,
-    useGuardData,
-    useLoaderData,
-    useNavigation,
-    useRouter,
-} from "bcp";
-```
-
-Use this entrypoint for page/client-facing framework APIs, routing, forms, loader/guard data, islands and metadata types.
+Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound`, loader/action/guard hooks and router/navigation APIs.
 
 Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md).
 
@@ -45,18 +26,7 @@ Related guide: [Hydration](hydration.md).
 
 ## `bcp/cache`
 
-Caching and revalidation APIs.
-
-```ts
-import {
-    cache,
-    clearCache,
-    dedupe,
-    getCacheStats,
-    revalidatePath,
-    revalidateTag,
-} from "bcp/cache";
-```
+Caching, deduplication, statistics and path/tag revalidation primitives.
 
 Related guide: [Caching](caching.md).
 
@@ -64,67 +34,17 @@ Related guide: [Caching](caching.md).
 
 Typed framework configuration, application environment-schema validation and diagnostics APIs.
 
-```ts
-import {
-    applyEnvironmentDefaults,
-    defineConfig,
-    defineEnvironment,
-    diagnoseBcpConfiguration,
-    getEnvironmentSchemaFileNames,
-    loadBcpEnvironmentSchema,
-    readResolvedBcpConfig,
-    resolveBcpConfig,
-    validateEnvironment,
-} from "bcp/config";
-```
-
-Use `defineConfig()` for framework runtime/build settings and `defineEnvironment()` for the optional `bcp.environment.*` application-variable schema.
-
-`validateEnvironment()` returns parsed declared values and structured issues. `applyEnvironmentDefaults()` fills only missing environment keys and does not overwrite values already supplied by the environment/runtime.
-
 Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md).
 
 ## `bcp/validation`
 
-Typed validation primitives and `ValidationError`.
-
-```ts
-import {
-    array,
-    boolean,
-    literal,
-    nullable,
-    number,
-    object,
-    optional,
-    parse,
-    safeParse,
-    string,
-    union,
-} from "bcp/validation";
-```
+Typed validation primitives, parse helpers and `ValidationError`.
 
 Related guide: [Validation](validation.md).
 
 ## `bcp/error`
 
-Structured HTTP error helpers.
-
-```ts
-import {
-    HttpError,
-    badRequest,
-    conflict,
-    forbidden,
-    internalServerError,
-    isHttpError,
-    serviceUnavailable,
-    throwHttpError,
-    tooManyRequests,
-    unauthorized,
-    unprocessableEntity,
-} from "bcp/error";
-```
+Structured HTTP error helpers and response classification.
 
 Related guide: [Error Handling](error-handling.md).
 
@@ -132,33 +52,7 @@ Related guide: [Error Handling](error-handling.md).
 
 Server-only Database Platform v2 APIs.
 
-```ts
-import {
-    createDatabase,
-    db,
-    resolveDatabaseOptions,
-    type DatabaseAdapter,
-    type DatabaseAdapterFactory,
-    type DatabaseConnectionOptions,
-    type DatabaseDriver,
-    type DatabaseOptions,
-    type DatabaseParameters,
-    type ResolvedDatabaseOptions,
-    type TransactionDatabase,
-} from "bcp/database";
-```
-
-Built-in SQL providers are:
-
-```text
-mysql
-postgresql
-sqlite
-```
-
-`BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
-
-Use the public database helpers and adapter types instead of importing framework-internal provider/pool runtime modules.
+Built-in SQL providers are MySQL, PostgreSQL and SQLite. `BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
 
 Related guides: [Database](database.md), [Database Migrations](database-migrations.md).
 
@@ -166,172 +60,136 @@ Related guides: [Database](database.md), [Database Migrations](database-migratio
 
 Server-only authentication and authorization APIs.
 
-```ts
-import {
-    AuthorizationError,
-    assertPermission,
-    auth,
-    authorize,
-    can,
-    cannot,
-    createAuth,
-    createAuthGuard,
-    createGuestGuard,
-    createMemoryAuthSessionStore,
-    createPermissionGuard,
-    createRoleGuard,
-    defineAuthorizationPolicy,
-    getGuardAuth,
-    getSession,
-    getUserPermissions,
-    hasPermission,
-    login,
-    logout,
-    logoutAll,
-    requireAuth,
-    requireGuest,
-    requirePermission,
-    requireRole,
-    revokeSession,
-    revokeUserSessions,
-    rotateSession,
-    type AuthApi,
-    type AuthLoginOptions,
-    type AuthOptions,
-    type AuthSession,
-    type AuthSessionStore,
-    type AuthSessionStoreRecord,
-    type AuthUser,
-    type AuthorizationContext,
-    type AuthorizationMatch,
-    type AuthorizationPolicy,
-    type MemoryAuthSessionStore,
-    type PermissionCheckOptions,
-    type PermissionRequirement,
-    type RequirePermissionOptions,
-} from "bcp/auth";
-```
-
-The default authentication mode remains stateless signed JWT-cookie authentication.
-
-Configure `AuthOptions.store` to enable server-side session revocation and `idleTimeout`. `createMemoryAuthSessionStore()` is provided for development/testing; production multi-instance applications should implement `AuthSessionStore` with shared durable storage.
-
-Authorization & Security v2 adds permission checks, permission route guards and resource-aware policy functions:
-
-- `hasPermission()` / `assertPermission()` for flat permission or scope fields,
-- `requirePermission()` / `createPermissionGuard()` for route protection,
-- `defineAuthorizationPolicy()` for application policy definitions,
-- `can()` / `cannot()` for policy checks,
-- `authorize()` for throwing `AuthorizationError` when a policy denies access.
+The default authentication mode remains stateless signed JWT-cookie authentication. Applications may opt into server-side session stores, revocation, logout-all, idle timeout, role/permission guards and resource-aware authorization policies.
 
 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.
+Server-only Background Jobs, Job Scheduling and Durable Jobs APIs.
+
+Core queue APIs:
 
 ```ts
 import {
     createJobQueue,
     createMemoryJobQueueAdapter,
     type BackgroundJobQueue,
+    type CleanupJobsOptions,
+    type DeadLetterJobRecord,
     type EnqueueJobOptions,
+    type HeartbeatJobOptions,
     type JobHandler,
     type JobHandlerContext,
     type JobQueueAdapter,
     type JobQueueOptions,
+    type JobQueueStats,
     type JobRecord,
     type JobRetryDelay,
     type JobState,
     type JobWorker,
     type MemoryJobQueueAdapter,
+    type ProcessNextJobOptions,
+    type RecoverStaleJobsOptions,
+    type RequeueDeadLetterOptions,
+    type ReserveJobOptions,
     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.
+Scheduling APIs:
 
-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.
+```ts
+import {
+    createJobScheduler,
+    createMemoryJobScheduleStore,
+    nextCronTime,
+    nextScheduleTime,
+    type JobSchedule,
+    type JobScheduleRecord,
+    type JobScheduleStore,
+    type JobScheduler,
+    type JobSchedulerOptions,
+    type JobSchedulerRunner,
+    type MemoryJobScheduleStore,
+    type RunDueSchedulesOptions,
+    type ScheduleJobOptions,
+    type StartJobSchedulerOptions,
+} from "bcp/jobs";
+```
 
-The queue contract is designed for practical at-least-once processing; handlers should be idempotent when duplicate side effects are unsafe.
+Durable Redis-compatible APIs added in `0.2.10`:
 
-Related guides: [Background Jobs Platform](background-jobs.md), [Observability Platform v2](observability.md).
+```ts
+import {
+    createRedisJobQueueAdapter,
+    createRedisJobScheduleStore,
+    type RedisCommandClient,
+    type RedisJobQueueAdapter,
+    type RedisJobsAdapterOptions,
+    type RedisJobScheduleStore,
+} from "bcp/jobs";
+```
 
-## `bcp/observability`
+### Queue lifecycle
 
-Server-only Observability Platform v2 APIs.
+`createJobQueue()` supports:
 
-```ts
-import {
-    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 "bcp/observability";
+```text
+immediate/delayed enqueue
+retry/backoff
+cancellation
+manual processNext()
+worker concurrency
+visibility timeout
+heartbeat lease renewal
+stale-running recovery
+DLQ inspection/requeue
+terminal retention cleanup
+queue statistics
 ```
 
-`createMetricsRegistry()` provides process-local counters, gauges and histograms. `createMetricsResponse()` renders Prometheus-compatible text exposition. `createRequestMetricsMiddleware()` measures HTTP request counts and duration using bounded `method` / `status` labels by default and intentionally does not label by raw path.
+Durable adapter methods such as `heartbeat()`, `recoverStale()`, `listDeadLetters()`, `requeueDeadLetter()`, `cleanup()` and `stats()` are optional so earlier `JobQueueAdapter` implementations remain compatible.
 
-`createHealthRegistry()` registers synchronous or asynchronous liveness/readiness checks, applies per-check timeouts and produces JSON health responses with HTTP `200` when all checks pass or `503` when any check fails.
+`reserve()` receives an optional second `ReserveJobOptions` argument containing `ownerId` and `visibilityTimeoutMs`. Production durable adapters should use it to create an atomic visibility lease.
 
-The built-in registry is process-local. Multi-instance deployments should scrape each process/container or aggregate through external monitoring infrastructure.
+### Scheduling
 
-Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
+`createJobScheduler()` supports recurring interval and UTC five-field cron schedules.
 
-## `bcp/server`
+The scheduler leases due records from `JobScheduleStore`, then enqueues normal jobs using deterministic occurrence IDs. `nextCronTime()` and `nextScheduleTime()` are available for tooling and tests.
+
+### Redis-compatible durable adapters
 
-Server request/runtime APIs.
+`createRedisJobQueueAdapter()` implements the queue contract on a shared Redis-compatible command client.
 
-This entrypoint includes request context, cookies, CSRF and same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
+`createRedisJobScheduleStore()` implements the schedule-store contract using the same minimal client shape:
 
 ```ts
-import {
-    clientIp,
-    cookies,
-    createCsrfToken,
-    createLocalStorage,
-    createLogger,
-    createS3Storage,
-    createStorageResponse,
-    destroyCsrfToken,
-    getProductionHardeningConfig,
-    headers,
-    isSafeHttpMethod,
-    isSameOriginRequest,
-    json,
-    redirect,
-    registerShutdownHook,
-    requestId,
-    requestMethod,
-    requestUrl,
-    requireCsrfRequest,
-    requireSameOriginRequest,
-    storeMultipartFile,
-    verifyCsrfRequest,
-    verifyCsrfToken,
-    RequestSecurityError,
-    type CsrfTokenOptions,
-    type SameOriginOptions,
-    type VerifyCsrfRequestOptions,
-} from "bcp/server";
+interface RedisCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
 ```
 
-`requireSameOriginRequest()` protects unsafe cookie-authenticated mutations by validating `Origin`/`Referer`. `createCsrfToken()` and `requireCsrfRequest()` provide signed double-submit style CSRF protection. `BCP_CSRF_SECRET` is preferred when configured and falls back to `BCP_SESSION_SECRET`.
+BCP does not install a Redis library and does not create the connection. Applications own authentication, TLS, Cluster/Sentinel configuration and connection shutdown.
+
+The reference adapters use atomic Lua state transitions. The default namespace `bcp:{jobs}` uses a Redis Cluster hash tag so all job/schedule keys share one slot.
+
+The processing model is at-least-once. Handlers that perform non-idempotent external side effects should use application-level idempotency protection.
+
+Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Durable Jobs Platform](durable-jobs.md), [Observability Platform v2](observability.md).
+
+## `bcp/observability`
+
+Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.
+
+Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
+
+## `bcp/server`
+
+Server request/runtime APIs including request context, cookies, CSRF and same-origin protection, logging, graceful shutdown hooks, multipart upload helpers, storage adapters, file delivery, response helpers and low-level session primitives.
 
 Related guides: [Server Request APIs](server-request-apis.md), [Authorization & Security v2](authorization-security.md), [File Upload](file-upload.md), [Storage](storage.md), [Storage Ecosystem](storage-ecosystem.md), [Production Hardening](production-hardening.md).
 
@@ -343,20 +201,12 @@ Server-only module boundary marker.
 import "bcp/server-only";
 ```
 
-Place this import in application modules that must never enter a browser bundle.
-
 Related guide: [Application Modules](application-modules.md).
 
 ## `bcp/middleware`
 
 Middleware System v2 APIs and types.
 
-```ts
-import type {
-    MiddlewarePipelineHandler,
-} from "bcp/middleware";
-```
-
 Related guide: [Middleware](middleware.md).
 
 ## Stability

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.8",
+  "versionTarget": "0.2.10",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -57,13 +57,15 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, background jobs, observability, logging, caching, security and production hardening.",
+      "description": "Middleware, durable background jobs, scheduling, observability, logging, caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
         { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
         { "route": "/docs/observability", "source": "observability.md", "title": "Observability Platform v2" },
         { "route": "/docs/background-jobs", "source": "background-jobs.md", "title": "Background Jobs Platform" },
+        { "route": "/docs/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling Platform" },
+        { "route": "/docs/durable-jobs", "source": "durable-jobs.md", "title": "Durable Jobs Platform" },
         { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
         { "route": "/docs/security", "source": "security.md", "title": "Security" },
         { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
@@ -109,7 +111,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.8", "source": "releases/0.2.8.md", "version": "0.2.8", "state": "unreleased" },
+    { "route": "/releases/0.2.10", "source": "releases/0.2.10.md", "version": "0.2.10", "state": "unreleased" },
+    { "route": "/releases/0.2.9", "source": "releases/0.2.9.md", "version": "0.2.9" },
+    { "route": "/releases/0.2.8", "source": "releases/0.2.8.md", "version": "0.2.8" },
     { "route": "/releases/0.2.7", "source": "releases/0.2.7.md", "version": "0.2.7" },
     { "route": "/releases/0.2.6", "source": "releases/0.2.6.md", "version": "0.2.6" },
     { "route": "/releases/0.2.5", "source": "releases/0.2.5.md", "version": "0.2.5" },