@chidchanun/bcp 0.2.19 → 0.3.1

package/docs/service-container.md

@@ -0,0 +1,333 @@
+# Dependency Injection & Service Container — 0.3.1
+
+BCP Framework `0.3.1` adds a typed, server-only dependency injection container through `bcp/container` and integrates it with `bcp/application`.
+
+The container is intentionally provider-neutral. It does not require decorators or reflection metadata.
+
+## Create typed service tokens
+
+```ts
+import {
+    createServiceToken,
+} from "bcp/container";
+
+export interface UserRepository {
+    findById(id: string): Promise<unknown>;
+}
+
+export const userRepositoryToken =
+    createServiceToken<UserRepository>(
+        "user-repository"
+    );
+```
+
+The token carries its value type at compile time, so `resolve(userRepositoryToken)` resolves as `UserRepository`.
+
+## Provider kinds
+
+### Value provider
+
+```ts
+import {
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const configProvider =
+    provideValue(
+        configToken,
+        {
+            apiUrl: "https://api.example.com",
+        }
+    );
+```
+
+### Factory provider
+
+```ts
+const repositoryProvider =
+    provideFactory(
+        userRepositoryToken,
+        [
+            configToken,
+        ] as const,
+        (
+            context,
+            [config]
+        ) =>
+            createUserRepository(
+                config.apiUrl
+            )
+    );
+```
+
+Dependency tuples are typed from their tokens.
+
+A factory may also resolve dynamic dependencies:
+
+```ts
+provideFactory(
+    serviceToken,
+    [] as const,
+    async (context) => {
+        const logger =
+            await context.resolve(
+                loggerToken
+            );
+        return new Service(logger);
+    }
+);
+```
+
+### Class provider
+
+```ts
+provideClass(
+    userServiceToken,
+    [
+        userRepositoryToken,
+    ] as const,
+    UserService
+);
+```
+
+BCP does not inspect constructor metadata. Dependencies remain explicit and reviewable.
+
+## Lifetimes
+
+Providers support three lifetimes:
+
+```text
+singleton  one instance for the provider owner; shared across application scopes
+scoped     one instance per scope
+transient  a new instance for every resolve
+```
+
+Example:
+
+```ts
+provideFactory(
+    requestContextToken,
+    [] as const,
+    createRequestContext,
+    {
+        lifetime: "scoped",
+    }
+);
+```
+
+The default lifetime is `singleton`.
+
+## Create a standalone container
+
+```ts
+import {
+    createServiceContainer,
+} from "bcp/container";
+
+const container =
+    createServiceContainer({
+        name: "orders",
+        providers: [
+            configProvider,
+            repositoryProvider,
+        ],
+    });
+
+const repository =
+    await container.resolve(
+        userRepositoryToken
+    );
+```
+
+Optional resolution:
+
+```ts
+const feature =
+    await container.optional(
+        optionalFeatureToken
+    );
+```
+
+A missing required provider throws `ServiceNotFoundError`.
+
+## Child and request scopes
+
+Use `createScope()` for request/job/test lifetime boundaries:
+
+```ts
+const requestScope =
+    container.createScope({
+        name: "request:123",
+    });
+
+const requestContext =
+    await requestScope.resolve(
+        requestContextToken
+    );
+
+await requestScope.dispose();
+```
+
+Singleton instances remain shared. Scoped instances are isolated per scope. Transient instances are never cached.
+
+Disposing a parent container disposes child scopes first.
+
+## Testing overrides
+
+Scopes can replace selected providers without mutating the application container:
+
+```ts
+const testScope =
+    container.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                mailerToken,
+                fakeMailer
+            ),
+        ],
+    });
+```
+
+This is the recommended dependency override mechanism for framework/application tests.
+
+## Dependency graph
+
+```ts
+const graph =
+    container.graph();
+```
+
+Each node reports:
+
+```text
+token
+description
+lifetime
+dependencies
+overridden
+```
+
+The graph is suitable for diagnostics and future developer tooling.
+
+## Circular dependencies
+
+Explicit and dynamic resolutions keep a resolution path. Circular graphs fail with `ServiceResolutionError`:
+
+```text
+A -> B -> C -> A
+```
+
+BCP does not silently inject partial instances.
+
+## Disposal
+
+Providers may define cleanup:
+
+```ts
+provideFactory(
+    databaseToken,
+    [] as const,
+    createDatabase,
+    {
+        async dispose(database) {
+            await database.close();
+        },
+    }
+);
+```
+
+Resolved disposable services are cleaned up in reverse creation order. Concurrent/repeated `dispose()` calls share the same disposal operation.
+
+If one or more disposers fail, the container completes the remaining cleanup and throws `ServiceDisposalError` containing the failures.
+
+## Application Platform integration
+
+`createApp()` accepts providers directly:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+const app =
+    createApp({
+        name: "orders-api",
+        providers: [
+            configProvider,
+            repositoryProvider,
+        ],
+        async setup(context) {
+            const repository =
+                await context.container
+                    .resolve(
+                        userRepositoryToken
+                    );
+        },
+    });
+```
+
+Application accessors:
+
+```text
+app.container
+app.context.container
+app.register(provider)
+app.createScope(options)
+```
+
+`app.register()` is only available before `start()`, matching plugin/resource registration semantics.
+
+The Application Platform deployment order is now:
+
+```text
+bcp:container
+  -> bcp:plugins
+  -> application infrastructure resources
+  -> bcp:application
+```
+
+Shutdown reverses that order:
+
+```text
+bcp:application
+  -> infrastructure resources
+  -> bcp:plugins
+  -> bcp:container
+```
+
+This keeps injected infrastructure alive until workers/plugins/application hooks have stopped.
+
+## Legacy plugin services
+
+`context.services` and `app.services` remain available for Plugin Platform compatibility. `0.3.1` does not silently translate string/symbol plugin-service keys into typed DI tokens.
+
+Use `context.container` for new typed dependency injection code. Existing plugins can migrate incrementally.
+
+## Packaging
+
+`bcp/container` is server-only and prepared npm packages expose:
+
+```text
+types   -> packages/client/src/container.ts
+default -> packages/client/src/container.mjs
+browser -> packages/client/src/server-only.browser.mjs
+```
+
+## Validation
+
+Framework maintainers should run:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:package
+npm run api:check
+npm run release:readiness
+npm run rc:check
+```

package/docs/stability-api-freeze.md

@@ -1,27 +1,12 @@
 # Stability & API Freeze — 0.2.19
 
-BCP Framework `0.2.19` is the final stabilization milestone for the `0.2.x` platform before the next `0.3.0` application-platform baseline.
+BCP Framework `0.2.19` is the final stabilization milestone for the `0.2.x` platform and the compatibility point used to establish the `0.3.0` Application Platform baseline.
 
-This release intentionally does **not** add a new application subsystem. Its purpose is to freeze the supported public package/CLI contract, strengthen release gates and catch accidental compatibility regressions before publication.
+This release intentionally did **not** add a new application subsystem. Its purpose was to freeze the supported public package/CLI contract, strengthen release gates and catch accidental compatibility regressions.
 
-## Frozen contract
+## Historical 0.2.19 contract
 
-The committed source of truth is:
-
-```text
-docs/api-freeze-snapshot.json
-```
-
-It records:
-
-- the supported `bcp/*` public entrypoint set;
-- the supported CLI command set;
-- prepared npm `exports` including `types`, `default` and `browser` targets;
-- API source/environment ownership from `docs/api-manifest.json`;
-- the compatibility baseline (`0.2.18`);
-- the no-intentional-breaking-change policy for `0.2.19`.
-
-The frozen public package entrypoints are:
+The `0.2.19` release froze these public package entrypoints:
 
 ```text
 bcp
@@ -45,7 +30,37 @@ bcp/server-only
 bcp/middleware
 ```
 
-`./package.json` is also frozen as a package export, although it is not an application API entrypoint.
+`./package.json` was also included in the prepared npm package contract, although it is not an application API module.
+
+The historical compatibility policy was:
+
+```text
+release: 0.2.19
+previous baseline: 0.2.18
+intentional breaking changes: false
+freeze state: frozen
+```
+
+## Current snapshot file
+
+The repository continues to use:
+
+```text
+docs/api-freeze-snapshot.json
+```
+
+as the **current reviewed API baseline**, not as a permanently immutable copy of the `0.2.19` file.
+
+After the Application Platform work begins, that file advances to the reviewed `0.3.0` baseline with:
+
+```text
+version: 0.3.0
+baselineVersion: 0.2.19
+```
+
+and adds `bcp/application` while preserving the `0.2.19` entrypoints.
+
+The historical `0.2.19` release notes and this guide document why the freeze exists; the current snapshot is the contract enforced by the active release gate.
 
 ## API compatibility gate
 
@@ -59,81 +74,49 @@ The compatibility checker prepares the exact npm staging package, generates the
 
 The check fails when, for example:
 
-- a public entrypoint is removed or added;
-- a CLI command changes without an explicit new platform baseline;
-- `bcp/server` stops resolving to `server.mjs` in the prepared package;
+- a public entrypoint changes unexpectedly;
+- a CLI command changes outside an intentional baseline update;
+- a compiled runtime target drifts;
 - a server-only browser poison target disappears;
 - an entrypoint changes API source/environment ownership;
-- the current version/baseline no longer matches the committed freeze.
-
-This prevents source metadata, prepared npm metadata and documentation metadata from drifting independently.
+- version/baseline metadata no longer matches the committed contract.
 
 ## Snapshot regeneration
 
-To intentionally regenerate the contract:
+To intentionally regenerate the current contract:
 
 ```bash
 npm run api:snapshot
 ```
 
-That command rewrites:
-
-```text
-docs/api-freeze-snapshot.json
-```
-
-For `0.2.19`, snapshot changes require explicit review because the milestone promises no intentional breaking changes from `0.2.18`.
+Do not regenerate the snapshot merely to silence an unexpected compatibility failure. Snapshot updates should accompany an intentional, reviewed platform-baseline change with migration documentation and regression coverage.
 
-Large or breaking public-surface changes should normally be deferred to `0.3.0` rather than silently updating the `0.2.19` snapshot.
+`0.3.0` is such an intentional additive baseline update: it adds `bcp/application` and uses `0.2.19` as its previous compatibility baseline.
 
 ## Release readiness
 
-Run:
+The current release uses:
 
 ```bash
 npm run release:readiness
-```
-
-The readiness report checks:
-
-- root/client/create-app version parity;
-- `package-lock.json` version parity;
-- platform/API/docs-web version parity;
-- `unreleased` release state;
-- `0.2.18` previous-baseline metadata;
-- no intentional breaking changes;
-- API freeze snapshot version/baseline;
-- public entrypoint parity;
-- CLI freeze parity;
-- current release notes and docs route;
-- stability capability flags.
-
-To also persist a local machine-readable report:
-
-```bash
 npm run release:readiness:report
 ```
 
-The report is written to:
+The readiness gate evolves with the active milestone. During `0.2.19` it validated freeze metadata; for `0.3.0` it validates the Application Platform baseline, `bcp/application` ownership, package/runtime parity and the `0.2.19` previous baseline.
+
+The optional report is written to:
 
 ```text
 .bcp-framework/release-readiness.json
 ```
 
-It is a local build artifact and is not the release source of truth.
-
 ## RC integration
 
-`0.2.19` strengthens the release pipeline:
+The stability infrastructure remains part of every later RC:
 
 ```text
 npm run typecheck
 npm test
-  -> unit
-  -> integration
-  -> e2e
-  -> prepared-package smoke
-      -> Stability & API Freeze smoke
 npm run api:check
 npm run release:readiness
 release metadata check
@@ -143,37 +126,25 @@ npm publish dry-run
 
 `npm run rc:check` must pass on the exact commit that will be tagged.
 
-## Lifecycle stabilization
-
-The stability suite adds explicit idempotency coverage for Deployment Platform v2:
-
-- concurrent/repeated `start()` calls must start a resource once;
-- concurrent/repeated `shutdown()` calls must stop a resource once;
-- shutdown remains reverse ordered;
-- a stopped runtime cannot be restarted.
-
-Existing subsystem-specific suites remain authoritative for jobs, workflows, outbox/events, realtime, cache, plugins and deployment behavior.
+## Lifecycle stabilization retained
 
-## Compatibility policy
+The `0.2.19` suite added explicit idempotency coverage for Deployment Platform v2:
 
-`0.2.19` declares:
-
-```text
-previous baseline: 0.2.18
-intentional breaking changes: false
-freeze state: frozen
-```
+- concurrent/repeated `start()` calls start a resource once;
+- concurrent/repeated `shutdown()` calls stop a resource once;
+- shutdown remains reverse ordered.
 
-Bug fixes may still change incorrect implementation behavior, but they must not silently remove documented public entrypoints or change their package-resolution contract.
+Those regressions remain part of the unit suite after the baseline advances.
 
-## Moving to 0.3.0
+## Relationship to 0.3.0
 
-`0.3.0` is the next platform baseline. That milestone may intentionally revise the frozen surface, but changes should be accompanied by:
+`0.3.0 — BCP Application Platform` follows the process established by this freeze:
 
-1. a reviewed API snapshot update;
-2. explicit compatibility/breaking-change metadata;
-3. migration documentation;
-4. updated package/docs manifests;
-5. regression and prepared-package coverage.
+1. use `0.2.19` as the previous baseline;
+2. add the intentional public surface (`bcp/application`);
+3. update and review the current API snapshot;
+4. add migration documentation;
+5. update package/platform/docs manifests;
+6. add unit and prepared-package regression coverage.
 
-The `0.2.19` snapshot therefore becomes the comparison point for the next platform-generation work.
+See [Application Platform](application-platform.md) and [Migrating to 0.3.0](migration-0.3.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.19",
-  "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
+  "version": "0.3.1",
+  "description": "BCP Framework - a React full-stack application platform with routing, SSR, APIs, lifecycle composition and standalone production builds.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,8 @@
     "bcp",
     "react",
     "framework",
+    "application-platform",
+    "dependency-injection",
     "ssr",
     "routing",
     "fullstack"
@@ -102,6 +104,16 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/deployment.mjs"
     },
+    "./container": {
+      "types": "./packages/client/src/container.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/container.mjs"
+    },
+    "./application": {
+      "types": "./packages/client/src/application.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/application.mjs"
+    },
     "./server": {
       "types": "./packages/client/src/server.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -36,6 +36,8 @@ const SERVER_ONLY_IMPORTS =
         "bcp/plugins",
         "bcp/observability",
         "bcp/deployment",
+        "bcp/container",
+        "bcp/application",
     ]);
 
 export function validateClientBoundaries(