@chidchanun/bcp 0.3.0 → 0.3.2

package/docs/releases/0.3.1.md

@@ -0,0 +1,116 @@
+# BCP Framework 0.3.1 — Dependency Injection & Service Container
+
+**State:** unreleased
+
+`0.3.1` adds typed dependency injection to the Application Platform without removing the Plugin Platform service registry introduced in `0.2.x`.
+
+## Highlights
+
+- new server-only `bcp/container` public entrypoint;
+- typed `ServiceToken<T>` values;
+- value, factory and class providers;
+- singleton, scoped and transient lifetimes;
+- child/request scopes;
+- scope-local provider overrides for tests;
+- dependency graph diagnostics;
+- circular dependency detection;
+- reverse-order disposal and aggregate disposal errors;
+- concurrent/repeated disposal idempotency;
+- `createApp()` integration through `providers`, `container`, `register()` and `createScope()`;
+- compiled `container.mjs` production runtime;
+- server-only browser poison boundary;
+- unit and prepared-package smoke coverage.
+
+## Public APIs
+
+```text
+createServiceToken
+createServiceContainer
+provideValue
+provideFactory
+provideClass
+ServiceNotFoundError
+ServiceResolutionError
+ServiceDisposalError
+```
+
+Important types:
+
+```text
+ServiceToken<T>
+ServiceProvider<T>
+ServiceLifetime
+ServiceFactoryContext
+ServiceContainer
+ServiceScope
+ServiceScopeOptions
+ServiceGraphNode
+```
+
+## Application Platform changes
+
+`ApplicationDefinition` now accepts:
+
+```ts
+providers?: readonly ServiceProvider<any>[];
+```
+
+`Application` and `ApplicationContext` now expose:
+
+```text
+container
+```
+
+Applications can also call:
+
+```text
+app.register(provider)
+app.createScope(options)
+```
+
+The existing `app.services` / `context.services` Plugin Platform registry remains supported for compatibility.
+
+## Lifecycle
+
+The application deployment chain now starts the DI container resource before the plugin host and application infrastructure. Shutdown reverses the chain so disposable injected services remain alive until application/plugin/resource shutdown completes.
+
+## Compatibility
+
+Previous baseline:
+
+```text
+0.3.0
+```
+
+Intentional breaking changes:
+
+```text
+false
+```
+
+`0.3.1` is additive. Existing `0.3.0` applications do not need to adopt dependency injection immediately.
+
+## Packaging
+
+Prepared npm packages expose:
+
+```text
+bcp/container -> packages/client/src/container.mjs
+```
+
+with TypeScript declarations sourced from `packages/client/src/container.ts` and browser builds redirected to the server-only poison module.
+
+## Validation
+
+Before publication run the complete framework RC sequence on the final commit:
+
+```bash
+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
+```

package/docs/releases/0.3.2.md

@@ -0,0 +1,125 @@
+# BCP Framework 0.3.2 — Module System v2
+
+**State:** unreleased
+
+BCP Framework `0.3.2` adds a first-class server-side application module system on top of the Application Platform and Dependency Injection container introduced in `0.3.0` and `0.3.1`.
+
+## Highlights
+
+- new server-only `bcp/modules` public entrypoint;
+- dependency-first module import graph;
+- duplicate-name and circular-dependency detection;
+- typed DI providers owned by modules;
+- explicit token exports and imported-token re-exports;
+- existing BCP plugin contribution from modules;
+- legacy shared-service contribution for plugin interoperability;
+- module-owned Deployment Platform resources;
+- module `setup/start/stop/dispose` lifecycle;
+- startup cleanup when a module setup/start hook fails;
+- module config parser/schema support;
+- module graph/record diagnostics;
+- `createApp()` integration with both Module System v2 and legacy `bcp/plugins` modules;
+- compiled `modules.mjs` production runtime;
+- browser poison boundary for `bcp/modules`;
+- unit and prepared-package smoke coverage.
+
+## Public API
+
+```ts
+import {
+    MODULE_V2_KIND,
+    ModuleDependencyError,
+    ModuleLifecycleError,
+    composeModules,
+    defineModule,
+    isModuleDefinition,
+    resolveModuleOrder,
+} from "bcp/modules";
+```
+
+Important public types:
+
+```text
+ModuleDefinition
+ModuleInput
+ModuleContext
+ModuleComposition
+ModuleRecord
+ModuleConfigSchema
+ModuleConfigParser
+```
+
+## Application integration
+
+`ApplicationDefinition.modules` now accepts both:
+
+```text
+legacy PluginModule from bcp/plugins
+ModuleDefinition from bcp/modules
+```
+
+The application exposes:
+
+```ts
+app.modules
+app.context.modules
+```
+
+Module providers are registered into `app.container`; module plugins are composed into `app.plugins`; module shared services are composed into `app.services`; and module resources/lifecycle are registered into `app.deployment`.
+
+## Lifecycle ordering
+
+For v2 modules, imports are resolved before importers. Within each module, resources start before the module lifecycle hook:
+
+```text
+imported modules
+    ↓
+module resources
+    ↓
+module setup/start
+```
+
+Shutdown reverses this order:
+
+```text
+module stop/dispose
+    ↓
+module resources
+    ↓
+imported modules
+```
+
+If a module's own setup/start fails, its dispose hook is run before the error propagates and Deployment Platform rolls back previously started resources.
+
+## Compatibility
+
+Previous baseline: `0.3.1`.
+
+Intentional breaking changes from `0.3.1`: **none**.
+
+The existing `defineModule()` from `bcp/plugins` remains supported and unchanged. New application modules should import `defineModule()` from `bcp/modules`.
+
+## Packaging
+
+Prepared npm packages add:
+
+```text
+bcp/modules -> packages/client/src/modules.mjs
+```
+
+with TypeScript types from `packages/client/src/modules.ts` and the standard server-only browser boundary.
+
+## Validation
+
+Before tagging or publishing `0.3.2`:
+
+```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
+```

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "BCP Framework - a React full-stack application platform with routing, SSR, APIs, lifecycle composition and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -17,6 +17,8 @@
     "react",
     "framework",
     "application-platform",
+    "dependency-injection",
+    "module-system",
     "ssr",
     "routing",
     "fullstack"
@@ -103,6 +105,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"
+    },
+    "./modules": {
+      "types": "./packages/client/src/modules.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/modules.mjs"
+    },
     "./application": {
       "types": "./packages/client/src/application.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/modules",
         "bcp/application",
     ]);