@chidchanun/bcp 0.2.19 → 0.3.1

package/docs/api-reference.md

@@ -1,8 +1,8 @@
 # API Reference
 
-BCP Framework exposes supported package entrypoints through the `bcp` package. Application code should import these public entrypoints instead of private implementation files under `packages/`.
+BCP Framework exposes supported APIs through public `bcp/*` package entrypoints. Application code should not import private implementation files under `packages/`.
 
-The machine-readable source for this page is `docs/api-manifest.json`.
+The machine-readable ownership source is `docs/api-manifest.json` and the reviewed package-resolution baseline is `docs/api-freeze-snapshot.json`.
 
 ## `bcp`
 
@@ -12,13 +12,11 @@ Common exports include `Form`, `Link`, `createIsland`, `navigate`, `notFound` an
 
 ## `bcp/island`
 
-Partial-hydration island APIs including `createIsland` and island loading strategy types.
+Partial-hydration island creation and loading strategy APIs.
 
 ## `bcp/cache`
 
-Backward-compatible request/data caching plus Cache Platform v2 shared-store APIs.
-
-Important exports:
+Request/data caching plus Cache Platform v2 adapters, locks, invalidation and metrics.
 
 ```text
 cache
@@ -35,47 +33,29 @@ createRedisCacheLockAdapter
 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).
-
 ## `bcp/config`
 
-Typed BCP configuration, environment-schema validation and diagnostics APIs.
-
-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).
+Typed framework configuration, environment-schema validation and configuration diagnostics. Prepared packages expose compiled `config.mjs`.
 
 ## `bcp/validation`
 
-Typed validation primitives, parse helpers and `ValidationError`.
+Typed validators, parse helpers and structured validation errors.
 
 ## `bcp/error`
 
-Structured HTTP error helpers and response classification.
+Structured HTTP error creation, classification and response helpers.
 
 ## `bcp/database`
 
-Server-only provider-neutral SQL APIs for MySQL, PostgreSQL and SQLite.
-
-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).
+Server-only provider-neutral SQL APIs for MySQL, PostgreSQL and SQLite, including query/execute, transactions, lifecycle and migrations.
 
 ## `bcp/auth`
 
-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.
-
-Prepared npm packages resolve the runtime to compiled `auth.mjs` in `0.2.18+`.
+Server-only authentication and authorization APIs including JWT cookie sessions, optional revocable session stores, role/permission guards, policies and auth/guest guards. Prepared packages expose compiled `auth.mjs`.
 
 ## `bcp/jobs`
 
-Server-only background jobs, scheduling and durable job APIs.
-
-Important exports:
+Server-only background jobs, scheduling and durable queue APIs.
 
 ```text
 createJobQueue
@@ -88,26 +68,22 @@ nextCronTime
 nextScheduleTime
 ```
 
-Capabilities include delay, retry/backoff, worker concurrency, cancellation, visibility leases, heartbeat renewal, stale recovery, DLQ/requeue, retention cleanup, queue statistics and recurring interval/UTC cron schedules.
-
-Processing remains at-least-once; non-repeatable external side effects should use application-level idempotency.
+Capabilities include delay, retry/backoff, concurrency, cancellation, visibility leases, heartbeat, stale recovery, DLQ/requeue, cleanup, statistics and recurring schedules.
 
 ## `bcp/workflow`
 
-Server-only Workflow Orchestration APIs.
+Server-only persistent workflow orchestration.
 
 ```text
 createWorkflow
 createMemoryWorkflowStore
 ```
 
-Workflow controls include `start`, `run`, `get`, `list`, `resume`, `retry`, `cancel`, `compensate` and `close`.
-
-Capabilities include sequential/parallel steps, per-step retry, persisted delays, compensation, run leases and optional execution through `bcp/jobs`.
+Supports sequential/parallel steps, retries, persisted delays, compensation, run leases and optional durable queue execution.
 
 ## `bcp/events`
 
-Server-only Transactional Outbox & Events APIs.
+Server-only transactional outbox and event delivery APIs.
 
 ```text
 createTransactionalOutbox
@@ -118,11 +94,9 @@ createOutboxDispatcher
 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.
-
 ## `bcp/realtime`
 
-Server-only realtime APIs for channels/rooms, broker delivery, presence, channel authorization, socket adapters, heartbeat and Server-Sent Events.
+Server-only channels/rooms, broker delivery, presence, authorization, socket adapters, heartbeat and Server-Sent Events APIs.
 
 ```text
 createRealtime
@@ -131,11 +105,11 @@ createMemoryRealtimePresenceStore
 createRealtimeSseResponse
 ```
 
-BCP intentionally does not install a WebSocket server library. Applications adapt the selected provider through `RealtimeSocket`.
+BCP does not require a WebSocket server library; applications adapt providers through `RealtimeSocket`.
 
 ## `bcp/testing`
 
-Server-only framework-native testing utilities. BCP does not require Jest or Vitest.
+Server-only framework-native testing utilities without a Jest/Vitest requirement.
 
 Important APIs include:
 
@@ -171,24 +145,17 @@ createPluginServiceRegistry
 createPluginHookBus
 ```
 
-Capabilities include required/optional dependency ordering, setup/start/stop/dispose lifecycle, startup rollback, typed configuration parsing, shared services and awaited in-process hooks.
+The Plugin Platform service registry remains supported for compatibility. For new typed application dependencies, prefer `bcp/container`.
 
 ## `bcp/observability`
 
-Server-only metrics, health and tracing APIs.
-
-Metrics/health APIs:
+Server-only metrics, health and distributed tracing APIs.
 
 ```text
 createMetricsRegistry
 createMetricsResponse
 createRequestMetricsMiddleware
 createHealthRegistry
-```
-
-Observability Platform v3 tracing APIs:
-
-```text
 createTracer
 createRequestTracingMiddleware
 createTraceCarrier
@@ -205,156 +172,280 @@ createTraceMetricsExporter
 getTraceLogFields
 ```
 
-Important tracing contracts include `Tracer`, `TraceContext`, `TraceCarrier`, `TraceSpan`, `TraceSpanRecord`, `TraceSpanExporter`, `TraceSpanKind` and `TraceSpanStatus`.
+Prepared packages expose compiled `observability.mjs`.
+
+## `bcp/deployment`
+
+Server-only Deployment Platform lifecycle APIs.
 
-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.
+```text
+createDeploymentRuntime
+createDeploymentReadinessResponse
+createDeploymentDiagnosticsResponse
+```
 
-Prepared npm packages expose compiled `observability.mjs`.
+Important types include `DeploymentRuntime`, `DeploymentResource`, `DeploymentReadinessReport`, `DeploymentDiagnosticsReport`, `DeploymentMetadata`, `DeploymentSignalOptions` and `DeploymentShutdownOptions`.
 
-Related guides: [Observability Platform v2](observability.md), [Observability Platform v3](observability-v3.md).
+Resources start in registration order and stop in reverse order. Startup failure rolls back already-started resources.
 
-## `bcp/deployment`
+Prepared packages expose compiled `deployment.mjs`.
 
-Server-only Deployment Platform v2 lifecycle APIs introduced in `0.2.18`.
+## `bcp/container`
 
-Primary functions:
+Server-only Dependency Injection & Service Container APIs introduced in `0.3.1`.
 
-```ts
-import {
-    createDeploymentDiagnosticsResponse,
-    createDeploymentReadinessResponse,
-    createDeploymentRuntime,
-} from "bcp/deployment";
+Primary exports:
+
+```text
+createServiceToken
+createServiceContainer
+provideValue
+provideFactory
+provideClass
+ServiceNotFoundError
+ServiceResolutionError
+ServiceDisposalError
 ```
 
-Important public types:
+Important types:
 
 ```text
-DeploymentRuntime
-DeploymentRuntimeOptions
-DeploymentRuntimeState
-DeploymentResource
-DeploymentResourceContext
-DeploymentResourceStatus
-DeploymentReadinessResult
-DeploymentReadinessReport
-DeploymentReadinessItem
-DeploymentDiagnosticsReport
-DeploymentDiagnosticsResource
-DeploymentMetadata
-DeploymentSignalOptions
-DeploymentShutdownOptions
+ServiceToken<T>
+ServiceTokenValue<TToken>
+ServiceDependencyValues<TDependencies>
+ServiceProvider<T>
+ServiceProviderOptions<T>
+ServiceFactoryContext
+ServiceLifetime
+ServiceContainer
+ServiceContainerOptions
+ServiceScope
+ServiceScopeOptions
+ServiceScopeState
+ServiceGraphNode
 ```
 
-Create a runtime:
+Create typed tokens:
 
 ```ts
-const deployment =
-    createDeploymentRuntime({
-        serviceName: "orders-api",
-        version: "1.0.0",
-    });
+import {
+    createServiceToken,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
 ```
 
-Register resources:
+Value provider:
 
 ```ts
-deployment.addResource({
-    name: "database",
-
-    async start() {
-        await db.connect();
-    },
+const configProvider =
+    provideValue(
+        configToken,
+        {
+            apiUrl: "https://api.example.com",
+        }
+    );
+```
 
-    ready() {
-        return true;
-    },
+Typed factory dependencies:
 
-    async stop() {
-        await db.close();
-    },
-});
+```ts
+const repositoryProvider =
+    provideFactory(
+        repositoryToken,
+        [
+            configToken,
+        ] as const,
+        (_context, [config]) =>
+            createRepository(
+                config.apiUrl
+            )
+    );
 ```
 
-Resources start in registration order and stop in reverse order. If startup fails, previously started resources are rolled back in reverse order.
+Class provider:
+
+```ts
+provideClass(
+    serviceToken,
+    [
+        repositoryToken,
+    ] as const,
+    UserService
+);
+```
 
-Runtime states:
+Supported lifetimes:
 
 ```text
-idle
-starting
-ready
-draining
-stopped
-failed
+singleton
+scoped
+transient
 ```
 
-Readiness:
+The default is `singleton`.
+
+Resolve services:
 
 ```ts
-const report =
-    await deployment.readiness();
+const container =
+    createServiceContainer({
+        providers: [
+            configProvider,
+            repositoryProvider,
+        ],
+    });
+
+const repository =
+    await container.resolve(
+        repositoryToken
+    );
 ```
 
-or:
+Optional dependencies:
 
 ```ts
-return createDeploymentReadinessResponse(
-    deployment
-);
+const value =
+    await container.optional(
+        optionalToken
+    );
 ```
 
-The response is `200` when the runtime and all resource checks are ready, otherwise `503`.
-
-Diagnostics:
+Child/request scopes:
 
 ```ts
-const report =
-    await deployment.diagnostics();
+const requestScope =
+    container.createScope({
+        name: "request:123",
+    });
 ```
 
-or:
+Testing overrides:
 
 ```ts
-return createDeploymentDiagnosticsResponse(
-    deployment
-);
+const testScope =
+    container.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                mailerToken,
+                fakeMailer
+            ),
+        ],
+    });
 ```
 
-Metadata includes service/deployment identity, process ID, Node version, platform, architecture and startup time. Optional environment-backed identity fields use:
+`graph()` exposes effective provider descriptions, lifetimes, dependencies and override state. Circular dependency paths throw `ServiceResolutionError`.
+
+Providers may define `dispose(value)`. The container disposes children first and resolved services in reverse creation order. Multiple disposal failures are collected in `ServiceDisposalError`.
+
+Prepared npm contract:
 
 ```text
-BCP_DEPLOYMENT_ID
-BCP_INSTANCE_ID
-BCP_RELEASE
-NODE_ENV
+types   -> packages/client/src/container.ts
+default -> packages/client/src/container.mjs
+browser -> packages/client/src/server-only.browser.mjs
 ```
 
-Install process signal handlers:
+Related guide: [Dependency Injection & Service Container](service-container.md).
 
-```ts
-const remove =
-    deployment.installSignalHandlers();
+## `bcp/application`
+
+Server-only Application Platform composition root.
+
+Primary exports:
+
+```text
+defineApp
+createApp
+ApplicationLifecycleError
+```
+
+Important types:
+
+```text
+Application
+ApplicationState
+ApplicationDefinition
+ApplicationContext
+ApplicationConfigSchema
+ApplicationConfigParser
 ```
 
-Defaults are `SIGTERM` and `SIGINT`.
+`0.3.1` application roots expose both the typed DI container and the legacy Plugin Platform service registry:
+
+```text
+app.config
+app.container
+app.services
+app.hooks
+app.plugins
+app.deployment
+```
 
-Integrate with the framework shutdown-hook registry:
+Define DI providers with the application:
 
 ```ts
-const unregister =
-    deployment.registerShutdownHook();
+const app =
+    createApp({
+        name: "orders-api",
+        providers: [
+            configProvider,
+            repositoryProvider,
+        ],
+    });
 ```
 
-Prepared npm packages expose compiled `deployment.mjs`.
+Resolve from lifecycle hooks:
 
-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).
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        providers: [
+            repositoryProvider,
+        ],
+        async setup(context) {
+            const repository =
+                await context.container.resolve(
+                    repositoryToken
+                );
+        },
+    });
+```
 
-## `bcp/server`
+Additional container integration:
 
-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.
+```text
+app.register(provider)
+app.createScope(options)
+```
+
+`register()` follows the application mutation rule and is allowed only before `start()`.
 
-Prepared npm packages resolve this runtime to compiled `server.mjs` in `0.2.18+`.
+Application deployment order:
+
+```text
+bcp:container
+bcp:plugins
+application resources
+bcp:application
+```
+
+Shutdown reverses this order. The container remains active while application resources/plugins stop, then disposes injected services before `application.dispose()` finishes the application lifecycle.
+
+`readiness()` and `diagnostics()` delegate to Deployment Platform. `installSignalHandlers()` and `registerShutdownHook()` perform full application shutdown.
+
+Prepared packages expose compiled `application.mjs` and block the entrypoint from browser/page graphs.
+
+Related guides: [Application Platform](application-platform.md), [Service Container](service-container.md), [Migrating to 0.3.x](migration-0.3.md).
+
+## `bcp/server`
+
+Server request/runtime APIs including request context, cookies, CSRF/same-origin protection, logging, graceful shutdown hooks, uploads, storage, response helpers and low-level session primitives. Prepared packages expose compiled `server.mjs`.
 
 ## `bcp/server-only`
 
@@ -366,13 +457,11 @@ import "bcp/server-only";
 
 ## `bcp/middleware`
 
-Middleware System v2 request/response pipeline types and helpers.
-
-Prepared npm packages resolve this runtime to compiled `middleware.mjs` in `0.2.18+`.
+Middleware System v2 request/response pipeline types and helpers. Prepared packages expose compiled `middleware.mjs`.
 
 ## Prepared server runtime map
 
-For `0.2.18`, the prepared npm package uses compiled ESM runtime defaults for:
+For `0.3.1`, prepared npm packages use compiled ESM runtime defaults for:
 
 ```text
 bcp/cache          -> cache.mjs
@@ -387,14 +476,16 @@ bcp/testing        -> testing.mjs
 bcp/plugins        -> plugins.mjs
 bcp/observability  -> observability.mjs
 bcp/deployment     -> deployment.mjs
+bcp/container      -> container.mjs
+bcp/application    -> application.mjs
 bcp/server         -> server.mjs
 bcp/middleware     -> middleware.mjs
 ```
 
-Types remain sourced from the TypeScript public entrypoint files.
+Types remain sourced from public TypeScript entrypoint files.
 
 ## Stability
 
-Only entrypoints listed in both `docs/platform-manifest.json` and `docs/api-manifest.json` are part of the documented platform surface.
+Only entrypoints listed in both `docs/platform-manifest.json` and `docs/api-manifest.json` are supported public platform modules.
 
-Files under internal `packages/*` paths are implementation details unless re-exported through a documented public package entrypoint.
+`docs/api-freeze-snapshot.json` records the current reviewed package/CLI/API baseline. Internal `packages/*` files remain implementation details unless exposed through a documented public entrypoint.