@chidchanun/bcp 0.3.0 → 0.3.2

package/docs/application-platform.md

@@ -1,8 +1,8 @@
 # BCP Application Platform
 
-BCP Framework `0.3.0` adds a framework-level application runtime that composes the infrastructure platforms introduced throughout `0.2.x` without replacing their individual APIs.
+BCP Framework `0.3.x` provides a server-side application composition root that coordinates the infrastructure platforms introduced throughout `0.2.x` without replacing their independent APIs.
 
-> **Release state:** unreleased development target until the complete RC workflow passes, the `v0.3.0` tag is created and npm publication succeeds.
+`0.3.1` extends the original `0.3.0` runtime with typed dependency injection through `bcp/container`.
 
 ## Public entrypoint
 
@@ -13,34 +13,23 @@ import {
 } from "bcp/application";
 ```
 
-`bcp/application` is server-only and is blocked from browser/page dependency graphs.
+`bcp/application` is server-only and blocked from browser/page dependency graphs.
 
-## Why an application runtime
-
-Before `0.3.0`, applications could use BCP databases, jobs, workflows, events, realtime, plugins, cache, observability and deployment independently. That remains supported.
-
-The Application Platform adds one composition root for applications that want those systems to share lifecycle and services:
+## Composition model
 
 ```text
 BCP Application
     |
     +-- typed application config
-    +-- shared service registry
-    +-- plugin/modules host
+    +-- typed DI container
+    +-- legacy plugin service registry
+    +-- plugin/module host
     +-- infrastructure resources
     +-- deployment metadata/readiness/diagnostics
     +-- graceful shutdown
-    |
-    +-- database
-    +-- cache / Redis
-    +-- jobs / scheduler
-    +-- workflow
-    +-- events / outbox
-    +-- realtime
-    +-- observability
 ```
 
-The application runtime does not create hidden database/job/cache implementations. Applications continue constructing the provider/runtime objects they need and register them with the composition root.
+Applications still construct database, cache, jobs, workflow, event, realtime and observability implementations explicitly. The application root composes their lifecycle; it does not hide provider creation.
 
 ## Basic application
 
@@ -96,245 +85,228 @@ const app =
 
 The schema may be an object with `parse()` or a parser function.
 
-## Shared services
-
-The application service registry is the same registry used by BCP plugins.
+## Typed dependency injection — 0.3.1
 
-Register before startup:
+Define providers with `bcp/container`:
 
 ```ts
-app.provide(
-    "database",
-    database
-);
+import {
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
 
-app.provide(
-    "cache",
-    cache
-);
-```
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
 
-Consume from application hooks:
+const repositoryToken =
+    createServiceToken<UserRepository>(
+        "user-repository"
+    );
 
-```ts
 const app =
     createApp({
         name: "orders-api",
-
-        start(context) {
-            const database =
-                context.services.get(
-                    "database"
-                );
-        },
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                repositoryToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) =>
+                    createRepository(
+                        config.apiUrl
+                    )
+            ),
+        ],
     });
 ```
 
-Plugins receive the same registry through their normal `PluginContext`.
+Resolve from application hooks:
 
-## Plugins and modules
+```ts
+createApp({
+    name: "orders-api",
+    providers: [
+        repositoryProvider,
+    ],
+
+    async setup(context) {
+        const repository =
+            await context.container.resolve(
+                repositoryToken
+            );
+    },
+});
+```
 
-Existing `bcp/plugins` definitions plug directly into the application runtime:
+Application DI APIs:
 
-```ts
-import {
-    definePlugin,
-} from "bcp/plugins";
-import {
-    createApp,
-} from "bcp/application";
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
+```
 
-const mailPlugin =
-    definePlugin({
-        name: "mail",
+`app.register()` follows the same deterministic mutation boundary as plugins/resources and is only allowed before startup begins.
 
-        setup(context) {
-            context.services.provide(
-                "mail",
-                mailer
-            );
-        },
-    });
+For request/job/test boundaries:
 
-const app =
-    createApp({
-        name: "orders-api",
-        plugins: [
-            mailPlugin,
-        ],
+```ts
+const scope =
+    app.createScope({
+        name: "request:123",
     });
 ```
 
-Existing `defineModule()` plugin modules can be passed through `modules` without conversion.
+Testing overrides can be supplied to the scope without modifying the application root.
 
-Before startup, applications may also register extensions fluently:
+See [Dependency Injection & Service Container](service-container.md).
+
+## Legacy plugin services
+
+`app.services` / `context.services` remain the registry used by `bcp/plugins`:
 
 ```ts
-app.use(mailPlugin);
+app.provide(
+    "database",
+    database
+);
 ```
 
-## Infrastructure resources
+This remains supported for compatibility. New typed application dependencies should prefer `app.container`.
+
+The two registries are intentionally not silently synchronized because typed `ServiceToken<T>` values and plugin string/symbol service keys have different contracts.
+
+## Plugins and modules
 
-Register lifecycle resources using the existing Deployment Platform resource contract:
+Existing `bcp/plugins` definitions plug directly into the application runtime:
 
 ```ts
 const app =
     createApp({
         name: "orders-api",
-        resources: [
-            {
-                name: "database",
-
-                async start() {
-                    await database.connect();
-                },
-
-                ready() {
-                    return database.ready;
-                },
-
-                async stop() {
-                    await database.close();
-                },
-            },
+        modules: [
+            backendModule,
         ],
     });
 ```
 
-Or before `start()`:
+Before startup:
+
+```ts
+app.use(mailPlugin);
+```
+
+## Infrastructure resources
+
+Use the existing Deployment Platform resource contract:
 
 ```ts
 app.addResource({
-    name: "workers",
+    name: "database",
 
-    start() {
-        worker = jobs.startWorker();
+    async start() {
+        await database.connect();
     },
 
-    stop() {
-        return worker.stop();
+    ready() {
+        return database.ready;
+    },
+
+    async stop() {
+        await database.close();
     },
 });
 ```
 
 ## Lifecycle order
 
-Application startup has one deterministic order:
+`setup()` runs before deployment startup, allowing config and DI services to be resolved before resource startup.
+
+Deployment order in `0.3.1`:
 
 ```text
 application.setup()
         |
         v
-plugin setup/start
+bcp:container
         |
         v
-resource 1 start
-resource 2 start
+bcp:plugins
+        |
+        v
+resource 1
+resource 2
 ...
         |
         v
-application.start()
+bcp:application / application.start()
         |
         v
 state = ready
 ```
 
-Shutdown reverses the dependency order:
+Shutdown reverses deployment dependencies:
 
 ```text
 application.stop()
         |
         v
-resource N stop
+resource N
 ...
-resource 1 stop
+resource 1
+        |
+        v
+plugins stop/dispose
         |
         v
-plugin stop/dispose
+container dispose
         |
         v
 application.dispose()
 ```
 
-This allows application logic and workers to stop before their shared database/cache/Redis dependencies disappear.
-
-Startup failures use Deployment Platform rollback. Already-started resources are stopped in reverse order and application/plugin disposal still runs.
+This keeps injected services alive while application resources and plugins are shutting down.
 
-## Setup versus start
-
-`setup()` runs before the deployment resource graph starts. It is useful for service registration and in-process configuration:
-
-```ts
-createApp({
-    name: "orders-api",
-
-    setup(context) {
-        context.services.provide(
-            "feature-flags",
-            flags
-        );
-    },
-});
-```
-
-`start()` runs after plugins and infrastructure resources have started:
-
-```ts
-createApp({
-    name: "orders-api",
-
-    start(context) {
-        const database =
-            context.services.get(
-                "database"
-            );
-
-        // Application-level startup after infrastructure is available.
-    },
-});
-```
+Startup failures use Deployment Platform rollback. Application cleanup also closes plugins and disposes the DI container idempotently when startup fails before the deployment graph becomes active.
 
 ## Readiness and diagnostics
 
-Application readiness delegates to the Deployment Platform:
-
 ```ts
-const report =
+const readiness =
     await app.readiness();
-```
 
-The report includes the internal plugin host, registered resources and the application lifecycle resource.
-
-Diagnostics:
-
-```ts
 const diagnostics =
     await app.diagnostics();
 ```
 
-Application diagnostics include deployment identity plus lifecycle information for every registered resource.
+Readiness now includes internal `bcp:container`, `bcp:plugins`, application resources and `bcp:application` entries.
 
-## Signals and framework shutdown hooks
+Application diagnostics expose registered container provider descriptions in addition to plugin/service/deployment information.
 
-If this process owns termination signals:
+## Signals and framework shutdown hooks
 
 ```ts
 const removeSignals =
     app.installSignalHandlers();
-```
-
-The default deployment signals remain `SIGTERM` and `SIGINT`.
 
-To participate in the existing BCP production shutdown registry:
-
-```ts
 const unregister =
     app.registerShutdownHook();
 ```
 
-## Application state
+Both paths perform full application shutdown, including application stop hooks and container disposal.
 
-The public state model is:
+## Application state
 
 ```text
 created
@@ -345,34 +317,32 @@ stopped
 failed
 ```
 
-Startup and shutdown are idempotent for concurrent/repeated calls while the application remains in the corresponding active/terminal lifecycle.
-
-A stopped application is terminal and cannot be started again. Create a new application runtime for a new process lifecycle.
+Concurrent/repeated start and shutdown calls are idempotent in their supported states. A stopped application is terminal and cannot be restarted.
 
 ## Mutation boundary
 
-Plugins, services and deployment resources must be registered before `start()`.
-
-The following are intentionally rejected after startup begins:
+The following are rejected once startup begins:
 
 ```ts
 app.use(...)
 app.provide(...)
+app.register(...)
 app.addResource(...)
 ```
 
-This keeps the production lifecycle graph deterministic.
+Creating child scopes is allowed while the container is active. Resolving/creating scopes after container disposal is rejected.
 
-## Relationship to 0.2.19 API freeze
+## Compatibility
 
-`0.2.19` froze the `0.2.x` package/API baseline. `0.3.0` intentionally establishes the next baseline by adding one public server-only entrypoint:
+`0.3.1` is additive over `0.3.0`:
 
 ```text
-bcp/application
+previous baseline: 0.3.0
+intentional breaking changes: false
 ```
 
-Existing `0.2.19` public entrypoints remain available. `0.3.0` does not intentionally remove them.
+Existing applications that use only `app.services` continue to work. DI adoption can be incremental.
 
 ## Next platform work
 
-The next planned milestone is `0.3.1 — Dependency Injection & Service Container`, which can build typed service tokens, scopes and testing overrides on top of the shared service composition introduced here.
+The next planned milestone is `0.3.2 — Module System v2`, using the Application Platform and DI container as the composition foundation for reusable application-native modules.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.3.0",
+  "versionTarget": "0.3.2",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,9 +58,11 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Application composition, middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed caching, security and production hardening.",
+      "description": "Application composition, dependency injection, modules, middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed caching, security and production hardening.",
       "pages": [
         { "route": "/docs/application-platform", "source": "application-platform.md", "title": "Application Platform" },
+        { "route": "/docs/service-container", "source": "service-container.md", "title": "Dependency Injection & Service Container" },
+        { "route": "/docs/module-system-v2", "source": "module-system-v2.md", "title": "Module System v2" },
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
         { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
@@ -97,7 +99,7 @@
         { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
         { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" },
         { "route": "/docs/testing-platform", "source": "testing-platform.md", "title": "Testing Platform" },
-        { "route": "/docs/plugin-module-platform", "source": "plugin-module-platform.md", "title": "Plugin & Module Platform" }
+        { "route": "/docs/plugin-module-platform", "source": "plugin-module-platform.md", "title": "Plugin & Legacy Module Platform" }
       ]
     },
     {
@@ -108,7 +110,7 @@
         { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
         { "route": "/docs/stability-api-freeze", "source": "stability-api-freeze.md", "title": "0.2 Stability & API Freeze" },
         { "route": "/docs/documentation-platform", "source": "documentation-platform.md", "title": "Documentation Platform" },
-        { "route": "/docs/migration-0.3", "source": "migration-0.3.md", "title": "Migrating to 0.3.0" },
+        { "route": "/docs/migration-0.3", "source": "migration-0.3.md", "title": "Migrating to 0.3.x" },
         { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.x" }
       ]
     },
@@ -122,7 +124,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.3.0", "source": "releases/0.3.0.md", "version": "0.3.0", "state": "unreleased" },
+    { "route": "/releases/0.3.2", "source": "releases/0.3.2.md", "version": "0.3.2", "state": "unreleased" },
+    { "route": "/releases/0.3.1", "source": "releases/0.3.1.md", "version": "0.3.1" },
+    { "route": "/releases/0.3.0", "source": "releases/0.3.0.md", "version": "0.3.0" },
     { "route": "/releases/0.2.19", "source": "releases/0.2.19.md", "version": "0.2.19" },
     { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18" },
     { "route": "/releases/0.2.17", "source": "releases/0.2.17.md", "version": "0.2.17" },