@chidchanun/bcp 0.3.0 → 0.3.1

package/docs/migration-0.3.md

@@ -1,142 +1,263 @@
-# Migrating to BCP Framework 0.3.0
+# Migrating to BCP Framework 0.3.x
 
-BCP Framework `0.3.0` establishes the Application Platform baseline while preserving the public entrypoints frozen in `0.2.19`.
+BCP Framework `0.3.0` established the Application Platform baseline. `0.3.1` extends it additively with typed dependency injection through `bcp/container`.
 
-> **Release state:** unreleased until RC validation, tagging and npm publication complete.
+## Compatibility
 
-## Compatibility goal
+Current target:
 
-`0.3.0` intentionally adds one public server-only package entrypoint:
+```text
+0.3.1 — Dependency Injection & Service Container
+```
+
+Previous baseline:
 
 ```text
-bcp/application
+0.3.0
 ```
 
-No `0.2.19` public entrypoint is intentionally removed. Existing applications do not have to adopt the new application runtime immediately.
+Intentional breaking changes:
 
-## Upgrade
+```text
+false
+```
+
+Existing `0.3.0` applications do not have to adopt dependency injection immediately.
 
-After `0.3.0` is published:
+## Upgrade to 0.3.1
+
+After publication:
 
 ```powershell
 npm exec -- bcp-framework update --check
-npm run update -- 0.3.0
+npm run update -- 0.3.1
 ```
 
-Then rebuild the application:
+Then validate the application:
 
 ```powershell
 npm run typecheck
 npm run build
+npm exec -- bcp-framework routes
 npm exec -- bcp-framework doctor
 ```
 
-Do not reuse a `.bcp-framework/build` directory produced by `0.2.x`.
+## Existing Application Platform code remains valid
 
-## Existing 0.2.x composition remains valid
-
-These imports remain public:
+This remains supported:
 
 ```ts
-import { db } from "bcp/database";
-import { createAuth } from "bcp/auth";
-import { createJobQueue } from "bcp/jobs";
-import { createWorkflow } from "bcp/workflow";
-import { createTransactionalOutbox } from "bcp/events";
-import { createRealtime } from "bcp/realtime";
-import { createCacheStore } from "bcp/cache";
-import { createPluginHost } from "bcp/plugins";
-import { createTracer } from "bcp/observability";
-import { createDeploymentRuntime } from "bcp/deployment";
+import {
+    createApp,
+} from "bcp/application";
+
+const app =
+    createApp({
+        name: "my-app",
+    });
+
+app.provide(
+    "database",
+    database
+);
 ```
 
-You can continue owning lifecycle manually if that is already appropriate for the project.
+`app.services` and `context.services` continue to use the Plugin Platform registry.
 
-## Optional migration to createApp
+## Optional migration to typed DI
 
-New or gradually modernized applications can centralize composition:
+New typed dependencies can use `bcp/container`:
 
 ```ts
 import {
-    createApp,
-} from "bcp/application";
+    createServiceToken,
+    provideValue,
+} from "bcp/container";
 
-export const app =
+const databaseToken =
+    createServiceToken<typeof database>(
+        "database"
+    );
+
+const app =
     createApp({
         name: "my-app",
-        version: "1.0.0",
+        providers: [
+            provideValue(
+                databaseToken,
+                database
+            ),
+        ],
     });
 ```
 
-Register shared service instances before startup:
+Then resolve from application hooks or server composition code:
 
 ```ts
-app.provide("database", database);
-app.provide("cache", cache);
-app.provide("jobs", jobs);
+const database =
+    await app.container.resolve(
+        databaseToken
+    );
 ```
 
-Register lifecycle-owned resources:
+You do not need to migrate every plugin service at once.
+
+## Factory dependencies
+
+Replace manual service construction:
 
 ```ts
-app.addResource({
-    name: "database",
-    start: () => database.connect(),
-    stop: () => database.close(),
-});
+const repository =
+    createRepository(
+        database,
+        logger
+    );
 ```
 
-Then:
+with explicit typed provider dependencies when useful:
 
 ```ts
-await app.start();
+const repositoryProvider =
+    provideFactory(
+        repositoryToken,
+        [
+            databaseToken,
+            loggerToken,
+        ] as const,
+        (
+            _context,
+            [database, logger]
+        ) =>
+            createRepository(
+                database,
+                logger
+            )
+    );
 ```
 
-## Lifecycle ownership
+No decorators or reflection metadata are required.
+
+## Request/job/test scopes
 
-Do not allow both the application runtime and separate application code to independently start/stop the same resource.
+Use child scopes for dependencies that should not be application singletons:
+
+```ts
+const requestScope =
+    app.createScope({
+        name: `request:${requestId}`,
+    });
 
-Choose one lifecycle owner for each database pool, worker, scheduler, broker or other long-running resource.
+try {
+    const service =
+        await requestScope.resolve(
+            requestServiceToken
+        );
+} finally {
+    await requestScope.dispose();
+}
+```
 
-The Application Platform starts:
+Testing overrides:
+
+```ts
+const testScope =
+    app.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                mailerToken,
+                fakeMailer
+            ),
+        ],
+    });
+```
+
+## Lifetimes
+
+Provider lifetimes are:
 
 ```text
-plugins
-resources
-application hook
+singleton
+scoped
+transient
 ```
 
-and stops them in reverse dependency order.
+The default is `singleton`.
+
+A common mapping is:
+
+```text
+database pool      singleton
+cache client       singleton
+repository         scoped or singleton depending on state
+request context    scoped
+small stateless factory output  transient when required
+```
 
-## Plugins and modules
+## Disposal ownership
 
-Existing `definePlugin()` and `defineModule()` values work directly:
+If the DI container owns a resource through a provider `dispose()` callback, avoid also registering an independent shutdown owner for the same instance unless the cleanup operation is explicitly idempotent.
+
+Example:
 
 ```ts
-const app =
-    createApp({
-        name: "my-app",
-        modules: [
-            backendModule,
-        ],
-    });
+provideFactory(
+    databaseToken,
+    [] as const,
+    createDatabase,
+    {
+        dispose(database) {
+            return database.close();
+        },
+    }
+);
+```
+
+The Application Platform keeps the container alive until application resources/plugins stop, then disposes injected services in reverse creation order.
+
+## Application resource lifecycle
+
+Long-running components can still use `app.addResource()`:
+
+```ts
+app.addResource({
+    name: "worker",
+    start: () => worker.start(),
+    stop: () => worker.stop(),
+});
 ```
 
-No plugin rewrite is required for `0.3.0`.
+DI and Deployment resources solve different concerns:
+
+```text
+container provider  -> construct/resolve/dispose dependencies
+application resource -> start/readiness/stop long-running runtime components
+```
+
+A provider may construct the worker while an application resource starts/stops it.
 
 ## Server-only boundary
 
-`bcp/application` owns process lifecycle and infrastructure composition. Do not import it from React client pages or islands.
+Both entrypoints are server-only:
+
+```text
+bcp/container
+bcp/application
+```
 
-Use it from server bootstrap/application composition modules.
+Do not import them into React client pages/islands.
 
 ## API baseline
 
-`0.2.19` remains the previous compatibility baseline. The reviewed `0.3.0` API snapshot adds `bcp/application` and becomes the new release contract used by `npm run api:check`.
+`0.3.1` adds one public entrypoint over `0.3.0`:
+
+```text
+bcp/container
+```
 
-## Validation checklist
+The reviewed API snapshot records the new `container.mjs` prepared runtime and browser poison boundary.
 
-For framework development:
+## Framework validation checklist
 
 ```powershell
 npm run typecheck
@@ -149,7 +270,7 @@ npm run release:readiness
 npm run rc:check
 ```
 
-For an application upgrading from `0.2.19`:
+For application upgrades:
 
 ```powershell
 npm run typecheck

package/docs/platform-contract.md

@@ -2,7 +2,7 @@
 
 BCP Framework exposes an explicit, machine-readable application-platform contract rather than relying on private repository structure.
 
-The current development baseline is **`0.3.0 — BCP Application Platform`** and remains unreleased until the complete RC sequence passes, the exact release commit is tagged and npm publication completes.
+The current development baseline is **`0.3.1 — Dependency Injection & Service Container`** and remains unreleased until the complete RC sequence passes, the exact release commit is tagged and npm publication completes.
 
 ## Sources of truth
 
@@ -20,11 +20,11 @@ docs/docs-web-manifest.json
   -> documentation routes and release navigation
 ```
 
-Framework source and tests remain authoritative for runtime behavior. The manifests make the supported surface testable during release validation.
+Framework source and tests remain authoritative for runtime behavior.
 
 ## Public entrypoints
 
-The `0.3.0` baseline supports:
+The `0.3.1` baseline supports:
 
 ```text
 bcp
@@ -43,43 +43,57 @@ bcp/testing
 bcp/plugins
 bcp/observability
 bcp/deployment
+bcp/container
 bcp/application
 bcp/server
 bcp/server-only
 bcp/middleware
 ```
 
-`bcp/application` is the one new entrypoint relative to the `0.2.19` baseline. No existing `0.2.19` public entrypoint is intentionally removed.
+`bcp/container` is the new entrypoint relative to `0.3.0`. No `0.3.0` public entrypoint is intentionally removed.
 
-Application code should use these entrypoints instead of private `packages/*` implementation paths.
+The prepared package also exposes `./package.json`; it is part of package-export snapshot validation but is not an application API module.
 
-The prepared npm package also exposes `./package.json`; that package export is included in the API snapshot even though it is not an application API module.
+## Application and DI baseline
 
-## Application Platform baseline
+`bcp/application` remains the composition root while `bcp/container` adds typed dependency injection:
 
-`bcp/application` adds a server-only composition root:
+```text
+ServiceToken<T>
+value providers
+factory providers
+class providers
+singleton/scoped/transient lifetimes
+child/request scopes
+test overrides
+dependency graph diagnostics
+circular dependency detection
+reverse disposal
+```
+
+Application integration exposes:
 
-```ts
-import {
-    createApp,
-    defineApp,
-} from "bcp/application";
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
 ```
 
-The Application Platform reuses the existing Plugin and Deployment platforms for:
+The existing Plugin Platform registry remains available through `app.services` / `context.services` for compatibility.
+
+## Lifecycle contract
+
+Application deployment resources start in this order:
 
 ```text
-typed application config
-shared services and hooks
-plugins/modules
-resource lifecycle
-startup rollback
-readiness/diagnostics
-signal handling
-graceful shutdown
+bcp:container
+bcp:plugins
+application resources
+bcp:application
 ```
 
-It does not replace existing database, jobs, cache, events, realtime or other subsystem APIs. Applications may use those independently or compose selected instances through the application root.
+Shutdown reverses that order. This keeps injected dependencies available while workers/resources/plugins stop, then disposes injected services before final application disposal.
 
 ## CLI baseline
 
@@ -112,21 +126,25 @@ build target: standalone-node
 package target: standalone-node
 ```
 
-Prepared server/runtime entrypoints resolve to compiled ESM where required by the package contract. `0.3.0` adds compiled `application.mjs`.
+Prepared npm packages expose compiled server ESM. `0.3.1` adds:
+
+```text
+bcp/container -> container.mjs
+```
+
+and preserves compiled `application.mjs` from `0.3.0`.
 
 ## Compatibility policy
 
-For `0.3.0`:
+For `0.3.1`:
 
 ```text
-previous baseline: 0.2.19
+previous baseline: 0.3.0
 intentional breaking changes: false
-baseline: application-platform
+baseline: dependency-injection-service-container
 ```
 
-`0.2.19` remains the historical freeze point for `0.2.x`. `0.3.0` intentionally advances the reviewed API snapshot by adding `bcp/application` and becomes the next compatibility baseline.
-
-Bug fixes must not silently remove a documented public entrypoint or change its prepared package-resolution/browser-boundary contract.
+Bug fixes must not silently remove a documented entrypoint or change its prepared package-resolution/browser-boundary contract.
 
 ## API compatibility gate
 
@@ -134,16 +152,14 @@ Bug fixes must not silently remove a documented public entrypoint or change its
 npm run api:check
 ```
 
-The gate prepares the publish package, regenerates the current contract in memory and compares it to `docs/api-freeze-snapshot.json`.
+The gate prepares the publish package, regenerates the current contract in memory and compares it with `docs/api-freeze-snapshot.json`.
 
-To intentionally regenerate the snapshot for a reviewed platform-baseline change:
+Regenerate the snapshot only for an intentional reviewed baseline change:
 
 ```bash
 npm run api:snapshot
 ```
 
-Do not regenerate the snapshot merely to silence an unexpected compatibility failure.
-
 ## Release readiness
 
 ```bash
@@ -151,11 +167,11 @@ npm run release:readiness
 npm run release:readiness:report
 ```
 
-The readiness gate checks version/lock/manifests parity, compatibility metadata, application entrypoint ownership, API snapshot parity, release docs and Application Platform capability flags. The optional report is written to `.bcp-framework/release-readiness.json`.
+The readiness gate checks package/lock/manifests parity, the `0.3.0` previous baseline, public entrypoint/API snapshot parity, container/application ownership, release docs and DI/Application capability flags.
 
 ## Release validation
 
-Before `0.3.0` is tagged or published:
+Before `0.3.1` is tagged or published:
 
 ```bash
 npm run typecheck
@@ -170,4 +186,4 @@ npm run rc:check
 
 `rc:check` must pass on the exact commit used for the release tag.
 
-See [Application Platform](application-platform.md), [Migrating to 0.3.0](migration-0.3.md), and the historical [Stability & API Freeze](stability-api-freeze.md).
+See [Dependency Injection & Service Container](service-container.md), [Application Platform](application-platform.md), [Migrating to 0.3.x](migration-0.3.md), and the historical [Stability & API Freeze](stability-api-freeze.md).

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "releaseState": "unreleased",
-  "baseline": "application-platform",
+  "baseline": "dependency-injection-service-container",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -27,6 +27,7 @@
     "bcp/plugins",
     "bcp/observability",
     "bcp/deployment",
+    "bcp/container",
     "bcp/application",
     "bcp/server",
     "bcp/server-only",
@@ -109,6 +110,21 @@
     "applicationLifecycleRollback": true,
     "applicationLifecycleIdempotency": true,
     "compiledApplicationRuntime": true,
+    "dependencyInjectionContainer": true,
+    "typedServiceTokens": true,
+    "serviceValueProviders": true,
+    "serviceFactoryProviders": true,
+    "serviceClassProviders": true,
+    "serviceSingletonLifetime": true,
+    "serviceScopedLifetime": true,
+    "serviceTransientLifetime": true,
+    "serviceChildScopes": true,
+    "serviceScopeOverrides": true,
+    "serviceDependencyGraph": true,
+    "serviceCircularDependencyDetection": true,
+    "serviceReverseDisposal": true,
+    "applicationServiceContainer": true,
+    "compiledContainerRuntime": true,
     "stabilityApiFreeze": true,
     "apiFreezeSnapshot": true,
     "apiCompatibilityGate": true,
@@ -244,7 +260,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.19",
+    "previousBaseline": "0.3.0",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.3.md"
   },
@@ -258,6 +274,7 @@
     "apiReference": "api-reference.md",
     "stabilityApiFreeze": "stability-api-freeze.md",
     "applicationPlatform": "application-platform.md",
+    "serviceContainer": "service-container.md",
     "environmentValidation": "environment-validation.md",
     "applicationPackaging": "application-packaging.md",
     "authentication": "authentication.md",
@@ -276,6 +293,6 @@
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.3.md",
-    "releaseNotes": "releases/0.3.0.md"
+    "releaseNotes": "releases/0.3.1.md"
   }
 }