@chidchanun/bcp 0.3.0 → 0.3.1

package/README.md

@@ -1,16 +1,17 @@
 # BCP Framework
 
-BCP Framework is a React full-stack application framework for file-based routing, SSR, server data, APIs, authentication, SQL databases, jobs, workflows, transactional events, realtime, caching, observability, plugins, deployment lifecycle and standalone Node.js production builds.
+BCP Framework is a React full-stack application framework for file-based routing, SSR, server data, APIs, authentication, SQL databases, jobs, workflows, transactional events, realtime, caching, observability, plugins, dependency injection, deployment lifecycle and standalone Node.js production builds.
 
-> **Development target:** `0.3.0 — BCP Application Platform`
+> **Development target:** `0.3.1 — Dependency Injection & Service Container`
 >
-> `0.3.0` remains unreleased until local validation, RC checks, tagging and npm publication complete.
+> `0.3.1` remains unreleased until local validation, RC checks, tagging and npm publication complete.
 
 ## Current platform
 
 | Area | Capability |
 | --- | --- |
-| Application runtime | `defineApp()` / `createApp()`, typed config, shared services, plugins/modules, resource lifecycle, readiness and diagnostics |
+| Application runtime | `defineApp()` / `createApp()`, typed config, DI, plugins/modules, resource lifecycle, readiness and diagnostics |
+| Dependency injection | Typed tokens, value/factory/class providers, singleton/scoped/transient lifetimes, child scopes and test overrides |
 | Routing | Static, dynamic, catch-all, optional catch-all and route groups |
 | Rendering | React SSR, hydration, layouts, metadata and SPA navigation |
 | Server data | Route loaders, guards, actions and request-scoped server APIs |
@@ -21,7 +22,7 @@ BCP Framework is a React full-stack application framework for file-based routing
 | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
 | Events | Transactional outbox, SQL persistence, dispatcher leases and durable handoff |
 | Realtime | Channels, presence, broker delivery, WebSocket adapter contract, SSE and heartbeat |
-| Plugins | Dependency ordering, lifecycle, config parsing, services and async hooks |
+| Plugins | Dependency ordering, lifecycle, config parsing, legacy shared services and async hooks |
 | Cache | Redis-compatible adapters/locks, stampede protection, TTL/tag/path invalidation and metrics |
 | Observability | Prometheus metrics, health/readiness, distributed tracing, W3C context and correlation IDs |
 | Deployment | Resource lifecycle, readiness, diagnostics, runtime identity and graceful shutdown |
@@ -61,85 +62,158 @@ Generated projects normally use one framework dependency:
 }
 ```
 
-## BCP Application Platform — 0.3.0
+## Dependency Injection & Service Container — 0.3.1
 
-`0.3.0` adds the server-only `bcp/application` composition root.
+`0.3.1` adds the server-only `bcp/container` entrypoint.
+
+```ts
+import {
+    createServiceContainer,
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const clientToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("api-client");
+
+const container =
+    createServiceContainer({
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                clientToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) => ({
+                    apiUrl: config.apiUrl,
+                })
+            ),
+        ],
+    });
+
+const client =
+    await container.resolve(
+        clientToken
+    );
+```
+
+Supported lifetimes:
+
+```text
+singleton  one shared instance
+scoped     one instance per child/request scope
+transient  a new instance for every resolve
+```
+
+Testing/request overrides use child scopes:
+
+```ts
+const testScope =
+    container.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                configToken,
+                fakeConfig
+            ),
+        ],
+    });
+```
+
+Resolved disposable services are cleaned up in reverse creation order. Circular dependency graphs fail with `ServiceResolutionError` instead of returning partial objects.
+
+Read more: [Dependency Injection & Service Container](docs/service-container.md).
+
+## BCP Application Platform — 0.3.x
+
+`bcp/application` is the server-side composition root.
 
 ```ts
 import {
     createApp,
 } from "bcp/application";
+import {
+    createServiceToken,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        region: string;
+    }>("config");
 
 export const app =
     createApp({
         name: "orders-api",
         version: "1.0.0",
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    region: "ap-southeast-1",
+                }
+            ),
+        ],
+        async setup(context) {
+            const config =
+                await context.container.resolve(
+                    configToken
+                );
+        },
     });
 ```
 
-The runtime exposes one shared application context:
+The application exposes:
 
 ```text
 app.config
+app.container
 app.services
 app.hooks
 app.plugins
 app.deployment
 ```
 
-Existing BCP subsystem APIs remain independent. Application Platform coordinates them; it does not replace them.
+`app.services` remains the Plugin Platform compatibility registry. New typed dependencies should prefer `app.container`.
 
-### Shared services
+Applications can register DI providers before start:
 
 ```ts
-app.provide(
-    "database",
-    database
-);
-
-app.provide(
-    "cache",
-    cache
-);
+app.register(provider);
 ```
 
-Existing plugins/modules use the same service registry:
+and create request/job/test scopes:
 
 ```ts
-const app =
-    createApp({
-        name: "orders-api",
-        modules: [
-            backendModule,
-        ],
+const scope =
+    app.createScope({
+        name: "request:123",
     });
 ```
 
-### Infrastructure lifecycle
+Infrastructure resources still use `app.addResource()`.
 
-```ts
-app.addResource({
-    name: "database",
-
-    start() {
-        return database.connect();
-    },
-
-    ready() {
-        return database.ready;
-    },
-
-    stop() {
-        return database.close();
-    },
-});
-```
-
-Startup is deterministic:
+Application startup order:
 
 ```text
 application.setup()
         ↓
+bcp:container
+        ↓
 plugin setup/start
         ↓
 resources start
@@ -149,47 +223,11 @@ application.start()
 ready
 ```
 
-Shutdown reverses dependencies:
+Shutdown reverses resource dependencies, so injected services remain alive until application resources/plugins have stopped. The container is then disposed, followed by `application.dispose()`.
 
-```text
-application.stop()
-        ↓
-resources stop (reverse order)
-        ↓
-plugin stop/dispose
-        ↓
-application.dispose()
-```
-
-Start failures roll back already-started resources using Deployment Platform semantics.
-
-### Readiness and diagnostics
-
-```ts
-const readiness =
-    await app.readiness();
-
-const diagnostics =
-    await app.diagnostics();
-```
-
-Graceful signal handling:
-
-```ts
-const removeSignals =
-    app.installSignalHandlers();
-```
-
-Framework shutdown registry:
-
-```ts
-const unregister =
-    app.registerShutdownHook();
-```
-
-Read more: [Application Platform](docs/application-platform.md) and [Migrating to 0.3.0](docs/migration-0.3.md).
+Read more: [Application Platform](docs/application-platform.md) and [Migrating to 0.3.x](docs/migration-0.3.md).
 
-## Public entrypoints — 0.3.0 baseline
+## Public entrypoints — 0.3.1 baseline
 
 ```text
 bcp
@@ -208,6 +246,7 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/container
 bcp/application
 bcp/server
 bcp/server-only
@@ -220,6 +259,7 @@ Application code should use public entrypoints rather than private `packages/*`
 
 ```ts
 import { createApp } from "bcp/application";
+import { createServiceContainer } from "bcp/container";
 import { createCacheStore } from "bcp/cache";
 import { db } from "bcp/database";
 import { createAuth } from "bcp/auth";
@@ -232,7 +272,7 @@ import { createTracer } from "bcp/observability";
 import { createDeploymentRuntime } from "bcp/deployment";
 ```
 
-You may use these systems independently or compose selected instances through `createApp()`.
+These systems remain independently usable. Application Platform coordinates selected instances and the DI container adds typed dependency composition.
 
 ## Compiled production entrypoints
 
@@ -251,6 +291,7 @@ 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
@@ -293,36 +334,18 @@ bcp generate migration create_users
 
 ## API baseline and release readiness
 
-`0.2.19` froze the `0.2.x` public contract. `0.3.0` intentionally establishes the next additive baseline with `bcp/application` while preserving existing entrypoints.
-
-Check the current baseline:
+`0.2.19` froze the `0.2.x` contract. `0.3.0` established the Application Platform baseline. `0.3.1` advances that baseline additively with `bcp/container` and no intentional breaking changes from `0.3.0`.
 
 ```bash
 npm run api:check
-```
-
-Regenerate the snapshot only for an intentional reviewed platform-baseline change:
-
-```bash
-npm run api:snapshot
-```
-
-Release metadata readiness:
-
-```bash
 npm run release:readiness
-```
-
-Optional machine-readable report:
-
-```bash
 npm run release:readiness:report
 ```
 
-Output:
+Regenerate the snapshot only for an intentional reviewed baseline change:
 
-```text
-.bcp-framework/release-readiness.json
+```bash
+npm run api:snapshot
 ```
 
 ## Machine-readable contracts
@@ -336,7 +359,7 @@ docs/api-freeze-snapshot.json
 
 ## Release validation
 
-Before publishing `0.3.0`:
+Before publishing `0.3.1`:
 
 ```bash
 npm run typecheck
@@ -382,12 +405,13 @@ Do not tag or publish until the exact final release commit passes the full RC se
 | `0.2.18` | Deployment Platform v2 |
 | `0.2.19` | Stability & API Freeze |
 | `0.3.0` | BCP Application Platform |
+| `0.3.1` | Dependency Injection & Service Container |
 
 ## Roadmap
 
-The next milestone is **`0.3.1 — Dependency Injection & Service Container`**, building typed service tokens, singleton/scoped/transient lifetimes, request scopes, factories and testing overrides on top of the Application Platform service composition model.
+The next milestone is **`0.3.2 — Module System v2`**, focused on application-native modules that can compose providers, plugins, routes, middleware, jobs and lifecycle contributions around the `createApp()` composition root.
 
-Later `0.3.x` milestones expand modules, typed APIs, SDK generation, identity/authorization, multi-tenancy, developer tooling and build/runtime targets.
+Later `0.3.x` milestones expand routing/API contracts, repositories, validation/DTOs, SDK generation, identity/authorization, multi-tenancy, developer tooling and build/runtime targets.
 
 Native desktop/mobile compilation remains later roadmap work.
 

package/docs/README.md

@@ -2,21 +2,21 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.3.0 — BCP Application Platform`
+> **Documentation target:** BCP Framework `0.3.1 — Dependency Injection & Service Container`
 >
-> **Release state:** unreleased development target until RC validation, tagging and npm publication complete.
+> **Release state:** unreleased until the complete RC validation, tagging and npm publication finish.
 
 ## Documentation architecture
 
 ```text
 docs/docs-web-manifest.json
-  -> website navigation, routes, Markdown sources and release routes
+  -> website navigation, Markdown sources and release routes
 
 docs/platform-manifest.json
   -> framework version, runtime target, public entrypoints and capabilities
 
 docs/api-manifest.json
-  -> public package entrypoints, source ownership and guide mapping
+  -> public package ownership and guide mapping
 
 docs/api-freeze-snapshot.json
   -> reviewed public/CLI/prepared-package API baseline
@@ -24,107 +24,87 @@ docs/api-freeze-snapshot.json
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## Current platform milestones
+## Current milestones
 
 | Version | Milestone |
 | --- | --- |
-| `0.2.0` | Framework Platform |
-| `0.2.1` | Documentation Platform |
-| `0.2.2` | Configuration & Environment v2 |
-| `0.2.3` | Database Platform v2 |
-| `0.2.4` | Application Packaging |
-| `0.2.5` | Authentication Platform v2 |
-| `0.2.6` | Authorization & Security v2 |
-| `0.2.7` | Observability Platform v2 |
-| `0.2.8` | Background Jobs Platform |
-| `0.2.9` | Job Scheduling Platform |
-| `0.2.10` | Durable Jobs Platform |
-| `0.2.11` | Workflow Orchestration |
-| `0.2.12` | Transactional Outbox & Events |
-| `0.2.13` | Realtime Platform |
-| `0.2.14` | Testing Platform |
 | `0.2.15` | Plugin & Module Platform |
 | `0.2.16` | Cache Platform v2 |
 | `0.2.17` | Observability Platform v3 |
 | `0.2.18` | Deployment Platform v2 |
 | `0.2.19` | Stability & API Freeze |
 | `0.3.0` | BCP Application Platform |
+| `0.3.1` | Dependency Injection & Service Container |
 
-## 0.3.0 — BCP Application Platform
+## 0.3.1 — Dependency Injection & Service Container
 
-`0.3.0` adds one server-only public composition root:
+New public entrypoint:
 
 ```text
-bcp/application
+bcp/container
 ```
 
 Primary APIs:
 
-```ts
-import {
-    createApp,
-    defineApp,
-} from "bcp/application";
+```text
+createServiceToken
+createServiceContainer
+provideValue
+provideFactory
+provideClass
 ```
 
-The application runtime composes existing Plugin and Deployment platforms instead of duplicating them. It provides:
+The container provides typed service tokens, singleton/scoped/transient lifetimes, child scopes, testing overrides, dependency graph diagnostics, circular-dependency detection and reverse-order disposal.
+
+`bcp/application` now exposes:
+
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
+```
 
-- typed application config parsing;
-- a shared service registry and hook bus;
-- existing plugin/module composition;
-- application-owned deployment resources;
-- deterministic startup/shutdown ordering;
-- startup rollback;
-- readiness and diagnostics;
-- signal/shutdown-hook integration;
-- compiled `application.mjs` production runtime.
+The Plugin Platform `services` registry remains available for compatibility. New typed dependency injection should prefer `container`.
 
-Lifecycle:
+Application lifecycle order is now:
 
 ```text
 application.setup
     ↓
-plugins
+bcp:container
     ↓
-resources
-    ↓
-application.start
-    ↓
-ready
-
-shutdown:
-application.stop
-    ↓
-resources (reverse)
+bcp:plugins
     ↓
-plugins
+resources
     ↓
-application.dispose
+bcp:application
 ```
 
-Read [Application Platform](application-platform.md) and [Migrating to 0.3.0](migration-0.3.md).
+Shutdown reverses deployment resources so the DI container remains available until application resources and plugins have stopped.
 
-## API baseline
+Read [Dependency Injection & Service Container](service-container.md), [Application Platform](application-platform.md) and [Migrating to 0.3.x](migration-0.3.md).
 
-`0.2.19` froze the final `0.2.x` public contract. `0.3.0` establishes the next reviewed baseline by adding `bcp/application` without intentionally removing existing `0.2.19` entrypoints.
+## API baseline
 
-Validate the current baseline:
+`0.3.1` advances the reviewed `0.3.0` baseline additively by adding `bcp/container`.
 
-```bash
-npm run api:check
+```text
+previous baseline: 0.3.0
+intentional breaking changes: false
 ```
 
-Regenerate only when an intentional platform-baseline change is being reviewed:
+Validate:
 
 ```bash
-npm run api:snapshot
+npm run api:check
+npm run release:readiness
 ```
 
-Release metadata readiness:
+Regenerate `docs/api-freeze-snapshot.json` only for an intentional reviewed platform contract change:
 
 ```bash
-npm run release:readiness
-npm run release:readiness:report
+npm run api:snapshot
 ```
 
 ## Update rule
@@ -134,33 +114,27 @@ When framework behavior or public surface changes:
 1. Update framework source.
 2. Add/update regression tests.
 3. Update the matching Markdown guide.
-4. Update `platform-manifest.json` for runtime/public-entrypoint/capability changes.
-5. Update `api-manifest.json` for public API ownership/guide changes.
-6. Update `docs-web-manifest.json` for website route/navigation changes.
-7. Review the API baseline snapshot when public/package contracts change.
+4. Update `platform-manifest.json`.
+5. Update `api-manifest.json`.
+6. Update `docs-web-manifest.json`.
+7. Review/update the API baseline snapshot when public/package contracts change.
 8. Update `docs/releases/<version>.md`.
-9. Change release state only after the release workflow reaches that state.
+9. Keep the release state `unreleased` until release completion.
 
 ## Important docs-web routes
 
 | Website route | Markdown source |
 | --- | --- |
 | `/docs/application-platform` | `application-platform.md` |
+| `/docs/service-container` | `service-container.md` |
 | `/docs/migration-0.3` | `migration-0.3.md` |
 | `/docs/stability-api-freeze` | `stability-api-freeze.md` |
 | `/docs/observability-v3` | `observability-v3.md` |
 | `/docs/deployment-platform-v2` | `deployment-platform-v2.md` |
-| `/docs/durable-jobs` | `durable-jobs.md` |
-| `/docs/workflow-orchestration` | `workflow-orchestration.md` |
-| `/docs/transactional-outbox-events` | `transactional-outbox-events.md` |
-| `/docs/realtime-platform` | `realtime-platform.md` |
 | `/docs/testing-platform` | `testing-platform.md` |
 | `/docs/plugin-module-platform` | `plugin-module-platform.md` |
-| `/docs/cache-platform-v2` | `cache-platform-v2.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.3.0` | `releases/0.3.0.md` |
-
-Every route/source pair is validated by unit tests.
+| `/releases/0.3.1` | `releases/0.3.1.md` |
 
 ## Public entrypoints
 
@@ -181,17 +155,18 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/container
 bcp/application
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-The API manifest, platform manifest and reviewed API baseline must remain aligned.
+The API manifest, platform manifest and API snapshot must remain aligned.
 
 ## Release validation
 
-Before publishing `0.3.0`:
+Before publishing `0.3.1`:
 
 ```bash
 npm run typecheck

package/docs/api-freeze-snapshot.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.3.0",
-  "baselineVersion": "0.2.19",
+  "version": "0.3.1",
+  "baselineVersion": "0.3.0",
   "state": "frozen",
   "intentionalBreakingChanges": false,
   "publicEntrypoints": [
@@ -22,6 +22,7 @@
     "bcp/plugins",
     "bcp/observability",
     "bcp/deployment",
+    "bcp/container",
     "bcp/application",
     "bcp/server",
     "bcp/server-only",
@@ -65,6 +66,11 @@
       "default": "./packages/client/src/config.mjs",
       "types": "./packages/client/src/config.ts"
     },
+    "./container": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/container.mjs",
+      "types": "./packages/client/src/container.ts"
+    },
     "./database": {
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/database.mjs",
@@ -219,6 +225,11 @@
       "source": "packages/client/src/deployment.ts",
       "environment": "server"
     },
+    {
+      "package": "bcp/container",
+      "source": "packages/client/src/container.ts",
+      "environment": "server"
+    },
     {
       "package": "bcp/application",
       "source": "packages/client/src/application.ts",