@chidchanun/bcp 0.2.19 → 0.3.1

package/README.md

@@ -1,36 +1,34 @@
 # BCP Framework
 
-BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, API routes, authentication, authorization, SQL databases, background jobs, scheduling, workflow orchestration, transactional events, realtime delivery, framework-native testing, plugin/module composition, distributed caching, observability, deployment lifecycle, uploads, storage and standalone Node.js deployment.
+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.2.19 — Stability & API Freeze`
+> **Development target:** `0.3.1 — Dependency Injection & Service Container`
 >
-> `0.2.19` 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 | React SSR, hydration, layouts, metadata and SPA navigation |
+| 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 |
-| Server data | Route loaders and request-scoped server APIs |
-| Mutations | Route-owned actions and `<Form>` |
-| Authentication | JWT cookie sessions, optional server-side stores, revocation, logout-all and idle timeout |
+| Rendering | React SSR, hydration, layouts, metadata and SPA navigation |
+| Server data | Route loaders, guards, actions and request-scoped server APIs |
+| Authentication | JWT cookie sessions, revocation, logout-all and idle timeout |
 | Authorization | Auth/guest/role/permission guards and resource-aware policies |
-| Security | Same-origin validation and signed CSRF tokens |
-| Middleware | Middleware System v2 with onion execution |
 | Database | MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle and migrations |
-| Jobs | Delay, retries, scheduling, Redis-compatible durable queues, heartbeat, stale recovery and DLQ |
+| Jobs | Delay, retries, scheduling, Redis-compatible durable queues, heartbeat, recovery and DLQ |
 | Workflows | Sequential/parallel steps, retries, persisted delays, compensation and run leases |
-| Events | Transactional outbox, SQL persistence, dispatcher leases, retries and durable queue handoff |
-| Realtime | Channels/rooms, presence, broker delivery, socket adapter contract, SSE and heartbeat |
+| 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, 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 |
 | Testing | Request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE harnesses |
-| Plugins & modules | Dependency ordering, lifecycle hooks, config parsing, shared services and async hooks |
-| Caching | Redis-compatible adapters/locks, stampede protection, TTL/tag/path invalidation and metrics |
-| Observability | Prometheus metrics, health/readiness, distributed tracing, W3C trace context and correlation IDs |
-| Deployment | Resource lifecycle, readiness, diagnostics, runtime identity, signal handling and graceful shutdown |
-| Stability | Frozen public/CLI/package contract, compatibility gate and release-readiness report |
-| Production | Standalone Node.js build, compiled server entrypoints, dependency pruning and Docker starter |
-| Documentation | Manifest-driven docs, API/platform metadata and release contracts |
+| Stability | API baseline snapshot, package-export parity and release-readiness gates |
+| Production | Standalone Node.js build, compiled server runtimes, dependency pruning and Docker starter |
 
 ## Requirements
 
@@ -64,77 +62,204 @@ Generated projects normally use one framework dependency:
 }
 ```
 
-## Public entrypoints — frozen for 0.2.19
+## Dependency Injection & Service Container — 0.3.1
+
+`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
-bcp
-bcp/island
-bcp/cache
-bcp/config
-bcp/validation
-bcp/error
-bcp/database
-bcp/auth
-bcp/jobs
-bcp/workflow
-bcp/events
-bcp/realtime
-bcp/testing
-bcp/plugins
-bcp/observability
-bcp/deployment
-bcp/server
-bcp/server-only
-bcp/middleware
+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
+            ),
+        ],
+    });
 ```
 
-Application code should use these public entrypoints instead of private `packages/*` implementation files.
+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).
 
-## Stability & API Freeze — 0.2.19
+## BCP Application Platform — 0.3.x
 
-The committed freeze contract is:
+`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 application exposes:
 
 ```text
-docs/api-freeze-snapshot.json
+app.config
+app.container
+app.services
+app.hooks
+app.plugins
+app.deployment
 ```
 
-It locks the current public entrypoint set, CLI command set, API ownership and exact prepared npm export targets.
+`app.services` remains the Plugin Platform compatibility registry. New typed dependencies should prefer `app.container`.
 
-Check compatibility:
+Applications can register DI providers before start:
 
-```bash
-npm run api:check
+```ts
+app.register(provider);
 ```
 
-Regenerate the snapshot only when an intentional platform-baseline change is reviewed:
+and create request/job/test scopes:
 
-```bash
-npm run api:snapshot
+```ts
+const scope =
+    app.createScope({
+        name: "request:123",
+    });
 ```
 
-Release metadata readiness:
+Infrastructure resources still use `app.addResource()`.
 
-```bash
-npm run release:readiness
+Application startup order:
+
+```text
+application.setup()
+        ↓
+bcp:container
+        ↓
+plugin setup/start
+        ↓
+resources start
+        ↓
+application.start()
+        ↓
+ready
 ```
 
-Persist a local machine-readable report:
+Shutdown reverses resource dependencies, so injected services remain alive until application resources/plugins have stopped. The container is then disposed, followed by `application.dispose()`.
 
-```bash
-npm run release:readiness:report
-```
+Read more: [Application Platform](docs/application-platform.md) and [Migrating to 0.3.x](docs/migration-0.3.md).
 
-Output:
+## Public entrypoints — 0.3.1 baseline
 
 ```text
-.bcp-framework/release-readiness.json
+bcp
+bcp/island
+bcp/cache
+bcp/config
+bcp/validation
+bcp/error
+bcp/database
+bcp/auth
+bcp/jobs
+bcp/workflow
+bcp/events
+bcp/realtime
+bcp/testing
+bcp/plugins
+bcp/observability
+bcp/deployment
+bcp/container
+bcp/application
+bcp/server
+bcp/server-only
+bcp/middleware
 ```
 
-Read more: [Stability & API Freeze](docs/stability-api-freeze.md)
+Application code should use public entrypoints rather than private `packages/*` files.
 
-## Core backend entrypoints
+## Core backend composition
 
 ```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";
@@ -142,37 +267,12 @@ import { createJobQueue } from "bcp/jobs";
 import { createWorkflow } from "bcp/workflow";
 import { createTransactionalOutbox } from "bcp/events";
 import { createRealtime } from "bcp/realtime";
-import { createTestApp } from "bcp/testing";
 import { createPluginHost } from "bcp/plugins";
 import { createTracer } from "bcp/observability";
 import { createDeploymentRuntime } from "bcp/deployment";
 ```
 
-## Deployment lifecycle
-
-```ts
-import {
-    createDeploymentRuntime,
-} from "bcp/deployment";
-
-const deployment =
-    createDeploymentRuntime({
-        serviceName: "orders-api",
-    });
-
-deployment.addResource({
-    name: "database",
-    start: () => db.connect(),
-    ready: () => db.status === "ready",
-    stop: () => db.close(),
-});
-
-await deployment.start();
-```
-
-Startup follows registration order. Shutdown runs in reverse order. Repeated/concurrent start while active and repeated/concurrent shutdown are covered by the `0.2.19` stability suite.
-
-Read more: [Deployment Platform v2](docs/deployment-platform-v2.md)
+These systems remain independently usable. Application Platform coordinates selected instances and the DI container adds typed dependency composition.
 
 ## Compiled production entrypoints
 
@@ -191,11 +291,13 @@ 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
 ```
 
-The exact prepared export map is now part of the API freeze contract.
+The reviewed prepared export map is recorded in `docs/api-freeze-snapshot.json` and validated by `npm run api:check`.
 
 ## CLI
 
@@ -230,14 +332,21 @@ bcp generate middleware
 bcp generate migration create_users
 ```
 
-## Packaging
+## API baseline and release readiness
+
+`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 build
-bcp package
+npm run api:check
+npm run release:readiness
+npm run release:readiness:report
 ```
 
-Application packages include production dependency manifests, deployment/environment metadata, file-integrity metadata and a Docker starter while excluding `.env` secrets and application devDependencies.
+Regenerate the snapshot only for an intentional reviewed baseline change:
+
+```bash
+npm run api:snapshot
+```
 
 ## Machine-readable contracts
 
@@ -250,7 +359,7 @@ docs/api-freeze-snapshot.json
 
 ## Release validation
 
-Before publishing `0.2.19`:
+Before publishing `0.3.1`:
 
 ```bash
 npm run typecheck
@@ -263,9 +372,7 @@ npm run release:readiness
 npm run rc:check
 ```
 
-`release:check` now runs the full tests, API compatibility gate, release-readiness gate and release metadata validation.
-
-Do not tag or publish until the exact final release commit passes the complete RC sequence.
+Do not tag or publish until the exact final release commit passes the full RC sequence.
 
 ## Release history
 
@@ -297,12 +404,14 @@ Do not tag or publish until the exact final release commit passes the complete R
 | `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 |
 
 ## Roadmap
 
-`0.2.19` freezes the supported `0.2.x` application/runtime contract and becomes the compatibility reference for the next platform generation.
+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.
 
-The next planned milestone is **`0.3.0 — BCP Application Platform`**. Intentional public API changes should be made there with explicit migration documentation and compatibility metadata.
+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,86 +2,110 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.19 — Stability & API Freeze`
+> **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
-  -> frozen public/CLI/prepared-package compatibility contract
+  -> reviewed public/CLI/prepared-package API baseline
 ```
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## Current 0.2.x 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.2.19 — Stability & API Freeze
+## 0.3.1 — Dependency Injection & Service Container
 
-`0.2.19` freezes the supported `0.2.x` public package and CLI contract without adding a new application subsystem.
+New public entrypoint:
 
-Primary stability commands:
+```text
+bcp/container
+```
 
-```bash
-npm run api:check
-npm run api:snapshot
-npm run release:readiness
-npm run release:readiness:report
+Primary APIs:
+
+```text
+createServiceToken
+createServiceContainer
+provideValue
+provideFactory
+provideClass
 ```
 
-The freeze snapshot captures:
+The container provides typed service tokens, singleton/scoped/transient lifetimes, child scopes, testing overrides, dependency graph diagnostics, circular-dependency detection and reverse-order disposal.
 
-- public `bcp/*` entrypoints;
-- CLI command names;
-- prepared npm export targets;
-- browser poison boundaries;
-- API source/environment ownership;
-- compatibility with `0.2.18`.
+`bcp/application` now exposes:
 
-`npm run api:check` prepares the exact npm staging package and rejects drift from the committed snapshot.
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
+```
 
-New/updated sources:
+The Plugin Platform `services` registry remains available for compatibility. New typed dependency injection should prefer `container`.
 
-| Source | Purpose |
-| --- | --- |
-| `stability-api-freeze.md` | Freeze policy, compatibility checks and release readiness |
-| `api-freeze-snapshot.json` | Frozen public/CLI/package contract |
-| `platform-manifest.json` | Stability capability flags and `0.2.18` compatibility baseline |
-| `docs-web-manifest.json` | Stability guide and `0.2.19` release route |
-| `releases/0.2.19.md` | Stability & API Freeze release notes |
+Application lifecycle order is now:
+
+```text
+application.setup
+    ↓
+bcp:container
+    ↓
+bcp:plugins
+    ↓
+resources
+    ↓
+bcp:application
+```
+
+Shutdown reverses deployment resources so the DI container remains available until application resources and plugins have stopped.
+
+Read [Dependency Injection & Service Container](service-container.md), [Application Platform](application-platform.md) and [Migrating to 0.3.x](migration-0.3.md).
+
+## API baseline
+
+`0.3.1` advances the reviewed `0.3.0` baseline additively by adding `bcp/container`.
+
+```text
+previous baseline: 0.3.0
+intentional breaking changes: false
+```
+
+Validate:
+
+```bash
+npm run api:check
+npm run release:readiness
+```
+
+Regenerate `docs/api-freeze-snapshot.json` only for an intentional reviewed platform contract change:
+
+```bash
+npm run api:snapshot
+```
 
 ## Update rule
 
@@ -90,31 +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 `api-freeze-snapshot.json`; do not regenerate it casually during `0.2.19`.
+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.2.19` | `releases/0.2.19.md` |
-
-Every route/source pair is validated by unit tests.
+| `/releases/0.3.1` | `releases/0.3.1.md` |
 
 ## Public entrypoints
 
@@ -135,16 +155,18 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/container
+bcp/application
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-The API-manifest entrypoint set, platform public-entrypoint set and freeze snapshot must remain aligned.
+The API manifest, platform manifest and API snapshot must remain aligned.
 
 ## Release validation
 
-Before publishing `0.2.19`:
+Before publishing `0.3.1`:
 
 ```bash
 npm run typecheck
@@ -157,6 +179,4 @@ npm run release:readiness
 npm run rc:check
 ```
 
-Stability validation covers public/CLI/export parity, prepared-package browser/runtime boundaries, release metadata and deployment lifecycle idempotency in addition to all existing subsystem suites.
-
 The final release tag must point to the exact commit that passed the complete RC sequence.