@chidchanun/bcp 0.2.17 → 0.2.19

package/docs/api-reference.md

@@ -10,25 +10,15 @@ Universal React application APIs for routing, navigation, layouts, metadata, loa
 
 Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound` and loader/action/guard hooks.
 
-Related guides: [Routing](routing.md), [Server Data Loaders](server-data-loaders.md), [Route Guards](route-guards.md), [Form Actions](form-actions.md), [Testing Platform](testing-platform.md).
-
 ## `bcp/island`
 
-Partial-hydration island APIs.
-
-```ts
-import {
-    createIsland,
-} from "bcp/island";
-```
-
-Related guide: [Hydration](hydration.md).
+Partial-hydration island APIs including `createIsland` and island loading strategy types.
 
 ## `bcp/cache`
 
 Backward-compatible request/data caching plus Cache Platform v2 shared-store APIs.
 
-Legacy APIs:
+Important exports:
 
 ```text
 cache
@@ -37,11 +27,6 @@ clearCache
 getCacheStats
 revalidateTag
 revalidatePath
-```
-
-Cache Platform v2 APIs:
-
-```text
 createCacheStore
 createMemoryCacheAdapter
 createMemoryCacheLockAdapter
@@ -52,33 +37,31 @@ createCacheMetrics
 
 Public contracts include `CacheAdapter`, `CacheLockAdapter`, `CacheStore`, cache statistics/options and Redis command-client adapter types.
 
-Related guides: [Caching](caching.md), [Cache Platform v2](cache-platform-v2.md), [Observability Platform v3](observability-v3.md).
+Related guides: [Caching](caching.md), [Cache Platform v2](cache-platform-v2.md).
 
 ## `bcp/config`
 
 Typed BCP configuration, environment-schema validation and diagnostics APIs.
 
-Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md).
+Prepared npm packages resolve the production runtime to compiled `config.mjs` in `0.2.18+`.
+
+Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md), [Deployment Platform v2](deployment-platform-v2.md).
 
 ## `bcp/validation`
 
 Typed validation primitives, parse helpers and `ValidationError`.
 
-Related guide: [Validation](validation.md).
-
 ## `bcp/error`
 
 Structured HTTP error helpers and response classification.
 
-Related guide: [Error Handling](error-handling.md).
-
 ## `bcp/database`
 
 Server-only provider-neutral SQL APIs for MySQL, PostgreSQL and SQLite.
 
-Core capabilities include query/execute, transactions, lifecycle, migration stores and migration execution.
+Core capabilities include query/execute, transactions, lifecycle and migrations.
 
-Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md), [Testing Platform](testing-platform.md), [Observability Platform v3](observability-v3.md).
+Related guides: [Database](database.md), [Database Migrations](database-migrations.md), [Transactional Outbox & Events](transactional-outbox-events.md).
 
 ## `bcp/auth`
 
@@ -86,13 +69,13 @@ Server-only Authentication Platform v2 and Authorization & Security v2 APIs.
 
 Capabilities include JWT-cookie sessions, optional server-side session stores, revocation, logout-all, idle timeout, role/permission guards, policies, same-origin protection and auth/guest guards.
 
-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).
+Prepared npm packages resolve the runtime to compiled `auth.mjs` in `0.2.18+`.
 
 ## `bcp/jobs`
 
 Server-only background jobs, scheduling and durable job APIs.
 
-Core queue APIs include:
+Important exports:
 
 ```text
 createJobQueue
@@ -109,8 +92,6 @@ Capabilities include delay, retry/backoff, worker concurrency, cancellation, vis
 
 Processing remains at-least-once; non-repeatable external side effects should use application-level idempotency.
 
-Related guides: [Background Jobs](background-jobs.md), [Job Scheduling](job-scheduling.md), [Durable Jobs](durable-jobs.md), [Observability Platform v3](observability-v3.md).
-
 ## `bcp/workflow`
 
 Server-only Workflow Orchestration APIs.
@@ -124,8 +105,6 @@ Workflow controls include `start`, `run`, `get`, `list`, `resume`, `retry`, `can
 
 Capabilities include sequential/parallel steps, per-step retry, persisted delays, compensation, run leases and optional execution through `bcp/jobs`.
 
-Related guides: [Workflow Orchestration](workflow-orchestration.md), [Durable Jobs](durable-jobs.md), [Observability Platform v3](observability-v3.md).
-
 ## `bcp/events`
 
 Server-only Transactional Outbox & Events APIs.
@@ -141,8 +120,6 @@ createEventBus
 
 SQL outbox storage supports MySQL, PostgreSQL and SQLite. Dispatch supports batched claims, leases, stale recovery, retry/backoff, terminal failure, durable-job handoff and custom publishing.
 
-Related guides: [Transactional Outbox & Events](transactional-outbox-events.md), [Database](database.md), [Durable Jobs](durable-jobs.md), [Observability Platform v3](observability-v3.md).
-
 ## `bcp/realtime`
 
 Server-only realtime APIs for channels/rooms, broker delivery, presence, channel authorization, socket adapters, heartbeat and Server-Sent Events.
@@ -156,8 +133,6 @@ createRealtimeSseResponse
 
 BCP intentionally does not install a WebSocket server library. Applications adapt the selected provider through `RealtimeSocket`.
 
-Related guides: [Realtime Platform](realtime-platform.md), [Testing Platform](testing-platform.md), [Observability Platform v3](observability-v3.md).
-
 ## `bcp/testing`
 
 Server-only framework-native testing utilities. BCP does not require Jest or Vitest.
@@ -184,8 +159,6 @@ createRealtimeTestHarness
 readSseEvents
 ```
 
-Related guide: [Testing Platform](testing-platform.md).
-
 ## `bcp/plugins`
 
 Server-only Plugin & Module Platform APIs.
@@ -200,15 +173,11 @@ createPluginHookBus
 
 Capabilities include required/optional dependency ordering, setup/start/stop/dispose lifecycle, startup rollback, typed configuration parsing, shared services and awaited in-process hooks.
 
-Related guides: [Plugin & Module Platform](plugin-module-platform.md), [Configuration](configuration.md), [Observability Platform v3](observability-v3.md).
-
 ## `bcp/observability`
 
 Server-only metrics, health and tracing APIs.
 
-### Observability Platform v2
-
-Existing APIs remain supported:
+Metrics/health APIs:
 
 ```text
 createMetricsRegistry
@@ -217,157 +186,175 @@ createRequestMetricsMiddleware
 createHealthRegistry
 ```
 
-The metrics registry provides counters, gauges, histograms and Prometheus exposition. Health checks provide readiness/liveness-style reports with timeout support.
+Observability Platform v3 tracing APIs:
+
+```text
+createTracer
+createRequestTracingMiddleware
+createTraceCarrier
+runWithTraceCarrier
+runWithTraceContext
+currentTraceContext
+injectTraceHeaders
+extractTraceHeaders
+formatTraceparent
+parseTraceparent
+createMemoryTraceSpanExporter
+createCompositeTraceSpanExporter
+createTraceMetricsExporter
+getTraceLogFields
+```
+
+Important tracing contracts include `Tracer`, `TraceContext`, `TraceCarrier`, `TraceSpan`, `TraceSpanRecord`, `TraceSpanExporter`, `TraceSpanKind` and `TraceSpanStatus`.
+
+Active trace context uses Node `AsyncLocalStorage`. W3C `traceparent`, optional `tracestate` and `x-correlation-id` can cross HTTP boundaries, while trace carriers can be stored in application-owned job/workflow/event/realtime payload metadata.
+
+Prepared npm packages expose compiled `observability.mjs`.
+
+Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md).
+
+## `bcp/deployment`
 
-### Observability Platform v3 — 0.2.17
+Server-only Deployment Platform v2 lifecycle APIs introduced in `0.2.18`.
 
-Tracing APIs:
+Primary functions:
 
 ```ts
 import {
-    createCompositeTraceSpanExporter,
-    createMemoryTraceSpanExporter,
-    createRequestTracingMiddleware,
-    createTraceCarrier,
-    createTraceMetricsExporter,
-    createTracer,
-    currentTraceContext,
-    extractTraceCarrier,
-    extractTraceHeaders,
-    formatTraceparent,
-    getTraceLogFields,
-    injectTraceHeaders,
-    parseTraceparent,
-    runWithTraceCarrier,
-    runWithTraceContext,
-} from "bcp/observability";
+    createDeploymentDiagnosticsResponse,
+    createDeploymentReadinessResponse,
+    createDeploymentRuntime,
+} from "bcp/deployment";
 ```
 
 Important public types:
 
 ```text
-Tracer
-TracerOptions
-TraceContext
-TraceCarrier
-TraceSpan
-TraceSpanRecord
-TraceSpanEvent
-TraceSpanExporter
-TraceSpanKind
-TraceSpanStatus
-TraceAttributes
-TraceIdFactory
-StartTraceSpanOptions
-RequestTracingOptions
-TraceMetricsOptions
+DeploymentRuntime
+DeploymentRuntimeOptions
+DeploymentRuntimeState
+DeploymentResource
+DeploymentResourceContext
+DeploymentResourceStatus
+DeploymentReadinessResult
+DeploymentReadinessReport
+DeploymentReadinessItem
+DeploymentDiagnosticsReport
+DeploymentDiagnosticsResource
+DeploymentMetadata
+DeploymentSignalOptions
+DeploymentShutdownOptions
 ```
 
-`createTracer()` creates root/child spans. Active context is stored with Node `AsyncLocalStorage`, allowing nested awaited operations to inherit the current `traceId`, `correlationId` and parent span.
+Create a runtime:
 
 ```ts
-await tracer.withSpan(
-    "order.checkout",
-    async () => {
-        await tracer.withSpan(
-            "database.insert",
-            createOrder,
-            {
-                kind: "client",
-            }
-        );
-    }
-);
+const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+        version: "1.0.0",
+    });
 ```
 
-Supported span kinds:
+Register resources:
 
-```text
-internal
-server
-client
-producer
-consumer
-```
+```ts
+deployment.addResource({
+    name: "database",
 
-Failed `withSpan()` callbacks are marked `error`, receive an `exception` event and rethrow the original application error.
+    async start() {
+        await db.connect();
+    },
 
-### W3C propagation
+    ready() {
+        return true;
+    },
 
-`formatTraceparent()` / `parseTraceparent()` support W3C version `00` trace headers.
+    async stop() {
+        await db.close();
+    },
+});
+```
 
-```ts
-const headers =
-    new Headers();
+Resources start in registration order and stop in reverse order. If startup fails, previously started resources are rolled back in reverse order.
 
-injectTraceHeaders(
-    headers
-);
+Runtime states:
+
+```text
+idle
+starting
+ready
+draining
+stopped
+failed
 ```
 
-`extractTraceHeaders()` reads `traceparent`, optional `tracestate` and `x-correlation-id`.
+Readiness:
 
-### Middleware tracing
+```ts
+const report =
+    await deployment.readiness();
+```
+
+or:
 
 ```ts
-export const middleware =
-    createRequestTracingMiddleware(
-        tracer
-    );
+return createDeploymentReadinessResponse(
+    deployment
+);
 ```
 
-The middleware continues a valid incoming trace and adds active trace/correlation headers to the response.
+The response is `200` when the runtime and all resource checks are ready, otherwise `503`.
 
-### Non-HTTP propagation
+Diagnostics:
 
 ```ts
-const trace =
-    createTraceCarrier();
+const report =
+    await deployment.diagnostics();
 ```
 
-Transport that carrier through job payloads, workflow input, event metadata or realtime payloads, then restore it with:
+or:
 
 ```ts
-runWithTraceCarrier(
-    payload.trace,
-    handler
+return createDeploymentDiagnosticsResponse(
+    deployment
 );
 ```
 
-BCP does not automatically mutate persisted job/workflow/event schemas in `0.2.17`.
-
-### Exporters and metrics
+Metadata includes service/deployment identity, process ID, Node version, platform, architecture and startup time. Optional environment-backed identity fields use:
 
-`TraceSpanExporter` is provider-neutral. BCP supplies an in-memory exporter and a composite exporter.
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+```
 
-`createTraceMetricsExporter()` converts completed spans into the existing metrics registry:
+Install process signal handlers:
 
-```text
-bcp_trace_spans_total
-bcp_trace_span_duration_seconds
+```ts
+const remove =
+    deployment.installSignalHandlers();
 ```
 
-Default labels are `kind` and `status`. Span names are opt-in to reduce accidental high cardinality.
+Defaults are `SIGTERM` and `SIGINT`.
 
-`getTraceLogFields()` returns:
+Integrate with the framework shutdown-hook registry:
 
-```text
-traceId
-spanId
-correlationId
+```ts
+const unregister =
+    deployment.registerShutdownHook();
 ```
 
-for structured log enrichment.
-
-Prepared npm packages expose compiled `observability.mjs` as the runtime default for `bcp/observability`.
+Prepared npm packages expose compiled `deployment.mjs`.
 
-Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md), [Logging](development-logging.md), [Cache Platform v2](cache-platform-v2.md).
+Related guides: [Deployment Platform v2](deployment-platform-v2.md), [Application Packaging](application-packaging.md), [Production Hardening](production-hardening.md), [Observability Platform v3](observability-v3.md).
 
 ## `bcp/server`
 
 Server request/runtime APIs including request context, cookies, CSRF/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), [Production Hardening](production-hardening.md), [Observability Platform v3](observability-v3.md).
+Prepared npm packages resolve this runtime to compiled `server.mjs` in `0.2.18+`.
 
 ## `bcp/server-only`
 
@@ -381,7 +368,30 @@ import "bcp/server-only";
 
 Middleware System v2 request/response pipeline types and helpers.
 
-Related guides: [Middleware](middleware.md), [Testing Platform](testing-platform.md), [Observability Platform v3](observability-v3.md).
+Prepared npm packages resolve this runtime to compiled `middleware.mjs` in `0.2.18+`.
+
+## Prepared server runtime map
+
+For `0.2.18`, the prepared npm package uses compiled ESM runtime defaults for:
+
+```text
+bcp/cache          -> cache.mjs
+bcp/config         -> config.mjs
+bcp/database       -> database.mjs
+bcp/auth           -> auth.mjs
+bcp/jobs           -> jobs.mjs
+bcp/workflow       -> workflow.mjs
+bcp/events         -> events.mjs
+bcp/realtime       -> realtime.mjs
+bcp/testing        -> testing.mjs
+bcp/plugins        -> plugins.mjs
+bcp/observability  -> observability.mjs
+bcp/deployment     -> deployment.mjs
+bcp/server         -> server.mjs
+bcp/middleware     -> middleware.mjs
+```
+
+Types remain sourced from the TypeScript public entrypoint files.
 
 ## Stability