@chidchanun/bcp 0.3.0 → 0.3.2

package/docs/module-system-v2.md

@@ -0,0 +1,386 @@
+# BCP Module System v2
+
+BCP Framework `0.3.2` adds a server-only application module system on top of the `0.3.0` Application Platform and `0.3.1` dependency-injection container.
+
+> **Release state:** unreleased until the complete RC workflow passes, the exact `v0.3.2` release commit is tagged and npm publication succeeds.
+
+## Public entrypoint
+
+```ts
+import {
+    defineModule,
+    composeModules,
+} from "bcp/modules";
+```
+
+`bcp/modules` is server-only and is blocked from browser/page dependency graphs.
+
+The old `defineModule()` exported by `bcp/plugins` remains supported as the legacy plugin-group module API. Module System v2 lives in `bcp/modules` so existing imports do not change behavior.
+
+## Basic module
+
+```ts
+import {
+    defineModule,
+} from "bcp/modules";
+import {
+    createServiceToken,
+    provideValue,
+} from "bcp/container";
+
+export const databaseToken =
+    createServiceToken<Database>(
+        "database"
+    );
+
+export const databaseModule =
+    defineModule({
+        name: "database",
+        providers: [
+            provideValue(
+                databaseToken,
+                database
+            ),
+        ],
+        exports: [
+            databaseToken,
+        ],
+    });
+```
+
+Pass modules to the application composition root:
+
+```ts
+import {
+    createApp,
+} from "bcp/application";
+
+export const app =
+    createApp({
+        name: "orders-api",
+        modules: [
+            databaseModule,
+        ],
+    });
+```
+
+## Imports and dependency ordering
+
+Modules can import other v2 modules:
+
+```ts
+export const ordersModule =
+    defineModule({
+        name: "orders",
+        imports: [
+            databaseModule,
+        ],
+    });
+```
+
+The graph is resolved dependency-first:
+
+```text
+database
+   ↓
+orders
+   ↓
+application
+```
+
+Repeated references to the same module definition are de-duplicated. Two different definitions using the same module name are rejected. Circular imports are rejected with `ModuleDependencyError`.
+
+## Providers and exports
+
+A module can own DI providers:
+
+```ts
+const repositoryToken =
+    createServiceToken<OrderRepository>(
+        "orders.repository"
+    );
+
+export const ordersModule =
+    defineModule({
+        name: "orders",
+        imports: [
+            databaseModule,
+        ],
+        providers: [
+            provideFactory(
+                repositoryToken,
+                [
+                    databaseToken,
+                ] as const,
+                (_context, [database]) =>
+                    new OrderRepository(
+                        database
+                    )
+            ),
+        ],
+        exports: [
+            repositoryToken,
+        ],
+    });
+```
+
+An exported token must either:
+
+- be provided by the module itself; or
+- be exported by one of its imported modules.
+
+That allows explicit re-export:
+
+```ts
+export const applicationDataModule =
+    defineModule({
+        name: "application-data",
+        imports: [
+            databaseModule,
+        ],
+        exports: [
+            databaseToken,
+        ],
+    });
+```
+
+The current `0.3.2` runtime uses the application container as the physical provider store. Export metadata defines the reviewed module boundary and is available for diagnostics/introspection; it does not create a second DI container per module.
+
+## Plugins
+
+Modules may contribute existing BCP plugins:
+
+```ts
+const auditPlugin =
+    definePlugin({
+        name: "audit",
+    });
+
+export const auditModule =
+    defineModule({
+        name: "audit-module",
+        plugins: [
+            auditPlugin,
+        ],
+    });
+```
+
+All module plugins are composed into the application Plugin Host before deployment resources start.
+
+## Shared legacy services
+
+For compatibility with `bcp/plugins`, a module may contribute entries to the legacy shared service registry:
+
+```ts
+export const featureModule =
+    defineModule({
+        name: "feature",
+        services: [
+            [
+                "feature-flags",
+                featureFlags,
+            ],
+        ],
+    });
+```
+
+New typed dependencies should generally prefer `bcp/container` providers/tokens. `services` exists for interoperability with existing plugins.
+
+## Resources
+
+Modules can own Deployment Platform resources:
+
+```ts
+export const jobsModule =
+    defineModule({
+        name: "jobs",
+        resources: [
+            {
+                name: "jobs-worker",
+
+                start() {
+                    return worker.start();
+                },
+
+                ready() {
+                    return worker.ready;
+                },
+
+                stop() {
+                    return worker.stop();
+                },
+            },
+        ],
+    });
+```
+
+Resources from imported modules are registered before resources from importing modules.
+
+## Module lifecycle
+
+Each module may define:
+
+```text
+setup
+start
+stop
+dispose
+```
+
+Example:
+
+```ts
+export const mailModule =
+    defineModule({
+        name: "mail",
+
+        setup(context) {
+            // Providers/services are already registered.
+        },
+
+        start(context) {
+            // Module resources and imported modules are available.
+        },
+
+        stop(context) {
+            // Stop module-level work before its resources disappear.
+        },
+
+        dispose(context) {
+            // Release module-only in-process state.
+        },
+    });
+```
+
+For each module, its deployment resources are registered before its lifecycle resource. Therefore startup is:
+
+```text
+imported module resources/lifecycle
+        ↓
+module resources
+        ↓
+module setup/start
+```
+
+Shutdown is the reverse:
+
+```text
+module stop/dispose
+        ↓
+module resources stop (reverse)
+        ↓
+imported module stop/dispose
+```
+
+If `setup()` or `start()` fails, Module System v2 runs that module's `dispose()` before propagating the startup error. Deployment Platform then rolls back resources/modules that were already started earlier.
+
+Lifecycle errors use `ModuleLifecycleError`.
+
+## Typed module config
+
+Modules support parser functions or schema objects with `parse()`:
+
+```ts
+export const mailModule =
+    defineModule({
+        name: "mail",
+        config: {
+            from:
+                process.env.MAIL_FROM,
+        },
+        schema: {
+            parse(value) {
+                const raw =
+                    value as {
+                        from?: string;
+                    };
+
+                if (!raw.from) {
+                    throw new Error(
+                        "MAIL_FROM is required"
+                    );
+                }
+
+                return {
+                    from: raw.from,
+                };
+            },
+        },
+        start(context) {
+            console.log(
+                context.config.from
+            );
+        },
+    });
+```
+
+## Composition diagnostics
+
+Application instances expose the resolved composition:
+
+```ts
+app.modules.records();
+```
+
+A record includes:
+
+```text
+name
+version
+imports
+providers
+exports
+plugins
+resources
+```
+
+Inspect one module's exports:
+
+```ts
+app.modules.exportedTokens(
+    "orders"
+);
+```
+
+Application diagnostics also include the module records.
+
+## Legacy plugin modules
+
+Existing code remains valid:
+
+```ts
+import {
+    defineModule,
+} from "bcp/plugins";
+
+const legacy =
+    defineModule({
+        name: "legacy",
+        plugins: [
+            plugin,
+        ],
+    });
+```
+
+`createApp({ modules: [...] })` accepts both legacy plugin modules and Module System v2 definitions. The two formats are distinguished by the v2 module marker created by `bcp/modules` `defineModule()`.
+
+## Package/runtime contract
+
+Prepared npm packages expose:
+
+```text
+bcp/modules -> packages/client/src/modules.mjs
+```
+
+Types remain in `packages/client/src/modules.ts`, and browser builds resolve to the standard server-only poison module.
+
+## Compatibility
+
+`0.3.2` is additive relative to `0.3.1`:
+
+- existing `bcp/plugins` module behavior remains available;
+- existing `createApp()` definitions without v2 modules behave as before;
+- `bcp/modules` is a new public entrypoint;
+- `ApplicationContext` and `Application` gain the additive `modules` composition view.
+
+No intentional breaking change is introduced from `0.3.1`.

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.2",
   "releaseState": "unreleased",
-  "baseline": "application-platform",
+  "baseline": "module-system-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -27,6 +27,8 @@
     "bcp/plugins",
     "bcp/observability",
     "bcp/deployment",
+    "bcp/container",
+    "bcp/modules",
     "bcp/application",
     "bcp/server",
     "bcp/server-only",
@@ -109,6 +111,34 @@
     "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,
+    "moduleSystemV2": true,
+    "applicationModulesV2": true,
+    "moduleDependencyGraph": true,
+    "moduleImports": true,
+    "moduleExports": true,
+    "moduleProviderComposition": true,
+    "modulePluginComposition": true,
+    "moduleServiceComposition": true,
+    "moduleResourceComposition": true,
+    "moduleLifecycle": true,
+    "moduleConfigSchemas": true,
+    "moduleDiagnostics": true,
+    "compiledModulesRuntime": true,
     "stabilityApiFreeze": true,
     "apiFreezeSnapshot": true,
     "apiCompatibilityGate": true,
@@ -244,7 +274,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.19",
+    "previousBaseline": "0.3.1",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.3.md"
   },
@@ -258,6 +288,8 @@
     "apiReference": "api-reference.md",
     "stabilityApiFreeze": "stability-api-freeze.md",
     "applicationPlatform": "application-platform.md",
+    "serviceContainer": "service-container.md",
+    "moduleSystemV2": "module-system-v2.md",
     "environmentValidation": "environment-validation.md",
     "applicationPackaging": "application-packaging.md",
     "authentication": "authentication.md",
@@ -276,6 +308,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.2.md"
   }
 }