@chidchanun/bcp 0.2.7 → 0.2.9

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,141 +60,75 @@ 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.
+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.
 
-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.
+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).
 
-Authorization & Security v2 adds permission checks, permission route guards and resource-aware policy functions:
+## `bcp/jobs`
 
-- `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.
+Server-only Background Jobs and Job Scheduling APIs.
 
-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).
+Queue APIs:
 
-## `bcp/observability`
+```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";
+```
 
-Server-only Observability Platform v2 APIs.
+Scheduling APIs added in `0.2.9`:
 
 ```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";
+    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";
 ```
 
-`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.
+`createJobQueue()` provides delayed enqueueing, retry/backoff, cancellation, manual `processNext()` execution and concurrent workers.
 
-`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.
+`createJobScheduler()` adds recurring interval and UTC five-field cron schedules. The scheduler leases due records from `JobScheduleStore`, then enqueues normal queue jobs using deterministic occurrence ids.
 
-The built-in registry is process-local. Multi-instance deployments should scrape each process/container or aggregate through external monitoring infrastructure.
+The built-in queue adapter and schedule store are process-local. Durable multi-instance deployments should implement both `JobQueueAdapter` and `JobScheduleStore` against shared infrastructure. `JobQueueAdapter.reserve()` and `JobScheduleStore.acquireDue()` are the respective atomic concurrency boundaries.
 
-Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
+Cron evaluation in `0.2.9` uses UTC. `nextCronTime()` and `nextScheduleTime()` are available for tooling and tests.
 
-## `bcp/server`
+Related guides: [Background Jobs Platform](background-jobs.md), [Job Scheduling Platform](job-scheduling.md), [Observability Platform v2](observability.md).
 
-Server request/runtime APIs.
+## `bcp/observability`
 
-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.
+Server-only Observability Platform v2 APIs for process-local counters, gauges, histograms, Prometheus exposition, request metrics middleware and health/readiness checks.
 
-```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";
-```
+Related guides: [Observability Platform v2](observability.md), [Logging](development-logging.md).
 
-`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/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).
 
@@ -312,20 +140,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