@chidchanun/bcp 0.2.19 → 0.3.1

package/docs/application-platform.md

@@ -0,0 +1,348 @@
+# BCP Application Platform
+
+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.
+
+`0.3.1` extends the original `0.3.0` runtime with typed dependency injection through `bcp/container`.
+
+## Public entrypoint
+
+```ts
+import {
+    createApp,
+    defineApp,
+} from "bcp/application";
+```
+
+`bcp/application` is server-only and blocked from browser/page dependency graphs.
+
+## Composition model
+
+```text
+BCP Application
+    |
+    +-- typed application config
+    +-- typed DI container
+    +-- legacy plugin service registry
+    +-- plugin/module host
+    +-- infrastructure resources
+    +-- deployment metadata/readiness/diagnostics
+    +-- graceful shutdown
+```
+
+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
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "orders-api",
+        version: "1.0.0",
+    });
+
+await app.start();
+```
+
+Shutdown:
+
+```ts
+await app.stop();
+```
+
+`shutdown()` and `close()` are aliases for the same terminal application shutdown operation.
+
+## Typed application config
+
+```ts
+const app =
+    createApp<{
+        port: number;
+    }>({
+        name: "orders-api",
+        config: {
+            port: process.env.PORT,
+        },
+        schema: {
+            parse(value) {
+                const raw = value as {
+                    port?: string;
+                };
+
+                return {
+                    port:
+                        Number(
+                            raw.port ?? 3000
+                        ),
+                };
+            },
+        },
+    });
+```
+
+The schema may be an object with `parse()` or a parser function.
+
+## Typed dependency injection — 0.3.1
+
+Define providers with `bcp/container`:
+
+```ts
+import {
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const repositoryToken =
+    createServiceToken<UserRepository>(
+        "user-repository"
+    );
+
+const app =
+    createApp({
+        name: "orders-api",
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                repositoryToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) =>
+                    createRepository(
+                        config.apiUrl
+                    )
+            ),
+        ],
+    });
+```
+
+Resolve from application hooks:
+
+```ts
+createApp({
+    name: "orders-api",
+    providers: [
+        repositoryProvider,
+    ],
+
+    async setup(context) {
+        const repository =
+            await context.container.resolve(
+                repositoryToken
+            );
+    },
+});
+```
+
+Application DI APIs:
+
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
+```
+
+`app.register()` follows the same deterministic mutation boundary as plugins/resources and is only allowed before startup begins.
+
+For request/job/test boundaries:
+
+```ts
+const scope =
+    app.createScope({
+        name: "request:123",
+    });
+```
+
+Testing overrides can be supplied to the scope without modifying the application root.
+
+See [Dependency Injection & Service Container](service-container.md).
+
+## Legacy plugin services
+
+`app.services` / `context.services` remain the registry used by `bcp/plugins`:
+
+```ts
+app.provide(
+    "database",
+    database
+);
+```
+
+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
+
+Existing `bcp/plugins` definitions plug directly into the application runtime:
+
+```ts
+const app =
+    createApp({
+        name: "orders-api",
+        modules: [
+            backendModule,
+        ],
+    });
+```
+
+Before startup:
+
+```ts
+app.use(mailPlugin);
+```
+
+## Infrastructure resources
+
+Use the existing Deployment Platform resource contract:
+
+```ts
+app.addResource({
+    name: "database",
+
+    async start() {
+        await database.connect();
+    },
+
+    ready() {
+        return database.ready;
+    },
+
+    async stop() {
+        await database.close();
+    },
+});
+```
+
+## Lifecycle 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
+bcp:container
+        |
+        v
+bcp:plugins
+        |
+        v
+resource 1
+resource 2
+...
+        |
+        v
+bcp:application / application.start()
+        |
+        v
+state = ready
+```
+
+Shutdown reverses deployment dependencies:
+
+```text
+application.stop()
+        |
+        v
+resource N
+...
+resource 1
+        |
+        v
+plugins stop/dispose
+        |
+        v
+container dispose
+        |
+        v
+application.dispose()
+```
+
+This keeps injected services alive while application resources and plugins are shutting down.
+
+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
+
+```ts
+const readiness =
+    await app.readiness();
+
+const diagnostics =
+    await app.diagnostics();
+```
+
+Readiness now includes internal `bcp:container`, `bcp:plugins`, application resources and `bcp:application` entries.
+
+Application diagnostics expose registered container provider descriptions in addition to plugin/service/deployment information.
+
+## Signals and framework shutdown hooks
+
+```ts
+const removeSignals =
+    app.installSignalHandlers();
+
+const unregister =
+    app.registerShutdownHook();
+```
+
+Both paths perform full application shutdown, including application stop hooks and container disposal.
+
+## Application state
+
+```text
+created
+starting
+ready
+stopping
+stopped
+failed
+```
+
+Concurrent/repeated start and shutdown calls are idempotent in their supported states. A stopped application is terminal and cannot be restarted.
+
+## Mutation boundary
+
+The following are rejected once startup begins:
+
+```ts
+app.use(...)
+app.provide(...)
+app.register(...)
+app.addResource(...)
+```
+
+Creating child scopes is allowed while the container is active. Resolving/creating scopes after container disposal is rejected.
+
+## Compatibility
+
+`0.3.1` is additive over `0.3.0`:
+
+```text
+previous baseline: 0.3.0
+intentional breaking changes: false
+```
+
+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.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.2.19",
+  "versionTarget": "0.3.1",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,8 +58,10 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed caching, security and production hardening.",
+      "description": "Application composition, dependency injection, 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/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
         { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
@@ -102,11 +104,12 @@
     {
       "id": "platform-compatibility",
       "title": "Platform & Compatibility",
-      "description": "Supported platform contracts, API freeze, documentation integration and migration guidance.",
+      "description": "Supported platform contracts, API baselines, documentation integration and migration guidance.",
       "pages": [
         { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
-        { "route": "/docs/stability-api-freeze", "source": "stability-api-freeze.md", "title": "Stability & API Freeze" },
+        { "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.x" },
         { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.x" }
       ]
     },
@@ -120,7 +123,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.19", "source": "releases/0.2.19.md", "version": "0.2.19", "state": "unreleased" },
+    { "route": "/releases/0.3.1", "source": "releases/0.3.1.md", "version": "0.3.1", "state": "unreleased" },
+    { "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" },
     { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16" },

package/docs/migration-0.3.md

@@ -0,0 +1,280 @@
+# Migrating to BCP Framework 0.3.x
+
+BCP Framework `0.3.0` established the Application Platform baseline. `0.3.1` extends it additively with typed dependency injection through `bcp/container`.
+
+## Compatibility
+
+Current target:
+
+```text
+0.3.1 — Dependency Injection & Service Container
+```
+
+Previous baseline:
+
+```text
+0.3.0
+```
+
+Intentional breaking changes:
+
+```text
+false
+```
+
+Existing `0.3.0` applications do not have to adopt dependency injection immediately.
+
+## Upgrade to 0.3.1
+
+After publication:
+
+```powershell
+npm exec -- bcp-framework update --check
+npm run update -- 0.3.1
+```
+
+Then validate the application:
+
+```powershell
+npm run typecheck
+npm run build
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework doctor
+```
+
+## Existing Application Platform code remains valid
+
+This remains supported:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+const app =
+    createApp({
+        name: "my-app",
+    });
+
+app.provide(
+    "database",
+    database
+);
+```
+
+`app.services` and `context.services` continue to use the Plugin Platform registry.
+
+## Optional migration to typed DI
+
+New typed dependencies can use `bcp/container`:
+
+```ts
+import {
+    createServiceToken,
+    provideValue,
+} from "bcp/container";
+
+const databaseToken =
+    createServiceToken<typeof database>(
+        "database"
+    );
+
+const app =
+    createApp({
+        name: "my-app",
+        providers: [
+            provideValue(
+                databaseToken,
+                database
+            ),
+        ],
+    });
+```
+
+Then resolve from application hooks or server composition code:
+
+```ts
+const database =
+    await app.container.resolve(
+        databaseToken
+    );
+```
+
+You do not need to migrate every plugin service at once.
+
+## Factory dependencies
+
+Replace manual service construction:
+
+```ts
+const repository =
+    createRepository(
+        database,
+        logger
+    );
+```
+
+with explicit typed provider dependencies when useful:
+
+```ts
+const repositoryProvider =
+    provideFactory(
+        repositoryToken,
+        [
+            databaseToken,
+            loggerToken,
+        ] as const,
+        (
+            _context,
+            [database, logger]
+        ) =>
+            createRepository(
+                database,
+                logger
+            )
+    );
+```
+
+No decorators or reflection metadata are required.
+
+## Request/job/test scopes
+
+Use child scopes for dependencies that should not be application singletons:
+
+```ts
+const requestScope =
+    app.createScope({
+        name: `request:${requestId}`,
+    });
+
+try {
+    const service =
+        await requestScope.resolve(
+            requestServiceToken
+        );
+} finally {
+    await requestScope.dispose();
+}
+```
+
+Testing overrides:
+
+```ts
+const testScope =
+    app.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                mailerToken,
+                fakeMailer
+            ),
+        ],
+    });
+```
+
+## Lifetimes
+
+Provider lifetimes are:
+
+```text
+singleton
+scoped
+transient
+```
+
+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
+```
+
+## Disposal ownership
+
+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
+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(),
+});
+```
+
+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
+
+Both entrypoints are server-only:
+
+```text
+bcp/container
+bcp/application
+```
+
+Do not import them into React client pages/islands.
+
+## API baseline
+
+`0.3.1` adds one public entrypoint over `0.3.0`:
+
+```text
+bcp/container
+```
+
+The reviewed API snapshot records the new `container.mjs` prepared runtime and browser poison boundary.
+
+## Framework validation checklist
+
+```powershell
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run api:check
+npm run release:readiness
+npm run rc:check
+```
+
+For application upgrades:
+
+```powershell
+npm run typecheck
+npm run build
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework doctor
+```