@chidchanun/bcp 0.3.0 → 0.3.2

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