@chidchanun/bcp 0.3.1 → 0.3.2

package/docs/api-freeze-snapshot.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.3.1",
-  "baselineVersion": "0.3.0",
+  "version": "0.3.2",
+  "baselineVersion": "0.3.1",
   "state": "frozen",
   "intentionalBreakingChanges": false,
   "publicEntrypoints": [
@@ -23,6 +23,7 @@
     "bcp/observability",
     "bcp/deployment",
     "bcp/container",
+    "bcp/modules",
     "bcp/application",
     "bcp/server",
     "bcp/server-only",
@@ -103,6 +104,11 @@
       "default": "./packages/server/src/middleware.mjs",
       "types": "./packages/server/src/middleware.ts"
     },
+    "./modules": {
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/modules.mjs",
+      "types": "./packages/client/src/modules.ts"
+    },
     "./observability": {
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/observability.mjs",
@@ -230,6 +236,11 @@
       "source": "packages/client/src/container.ts",
       "environment": "server"
     },
+    {
+      "package": "bcp/modules",
+      "source": "packages/client/src/modules.ts",
+      "environment": "server"
+    },
     {
       "package": "bcp/application",
       "source": "packages/client/src/application.ts",

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -59,7 +59,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-database",
       "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
-      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/database", "/docs/database-migrations", "/docs/transactional-outbox-events", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/auth",
@@ -67,7 +67,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-auth",
       "summary": "Authentication Platform v2 plus permission checks, authorization policies and auth/guest/role/permission route guards, published with a compiled Node runtime.",
-      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/authentication", "/docs/auth-session-store", "/docs/auth-route-guards", "/docs/authorization-security", "/docs/session-auth", "/docs/testing-platform", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/jobs",
@@ -75,7 +75,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-jobs",
       "summary": "Background queues and schedules with visibility leases, heartbeats, stale recovery, DLQ maintenance and Redis-compatible durable adapters.",
-      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/background-jobs", "/docs/job-scheduling", "/docs/durable-jobs", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/workflow",
@@ -83,7 +83,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-workflow",
       "summary": "Persistent workflow orchestration with sequential and parallel steps, retries, delays, compensation, run leases and optional durable queue execution.",
-      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/workflow-orchestration", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/events",
@@ -91,7 +91,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-events",
       "summary": "Transactional outbox and event delivery APIs with SQL persistence, dispatcher leases, retries, stale recovery, queue handoff and in-process event bus delivery.",
-      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/transactional-outbox-events", "/docs/database", "/docs/durable-jobs", "/docs/realtime-platform", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/realtime",
@@ -99,7 +99,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-realtime",
       "summary": "Realtime channels, cross-hub broker delivery, presence, channel authorization, WebSocket adapter integration, heartbeat handling and built-in Server-Sent Events responses.",
-      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/realtime-platform", "/docs/authentication", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/testing",
@@ -107,15 +107,15 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-testing",
       "summary": "Framework-native testing utilities for Request/Response handlers, signed auth sessions, rollback transactions, page/server execution, middleware, jobs, workflows, outbox delivery, realtime sockets and SSE.",
-      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability-v3", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/testing-platform", "/docs/authentication", "/docs/database", "/docs/durable-jobs", "/docs/workflow-orchestration", "/docs/transactional-outbox-events", "/docs/realtime-platform", "/docs/observability-v3", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/plugins",
       "source": "packages/client/src/plugins.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-plugins",
-      "summary": "Plugin and module composition with dependency ordering, lifecycle hooks, typed config parsing, shared services and asynchronous extension hooks.",
-      "guides": ["/docs/plugin-module-platform", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
+      "summary": "Plugin composition with dependency ordering, lifecycle hooks, typed config parsing, shared services and asynchronous extension hooks. Legacy plugin-group modules remain supported.",
+      "guides": ["/docs/plugin-module-platform", "/docs/module-system-v2", "/docs/configuration", "/docs/testing-platform", "/docs/observability-v3", "/docs/deployment-platform-v2", "/docs/application-platform", "/docs/service-container"]
     },
     {
       "package": "bcp/observability",
@@ -131,7 +131,7 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-deployment",
       "summary": "Deployment Platform v2 runtime lifecycle with resource startup/shutdown ordering, readiness, diagnostics, deployment metadata, signal handling and framework shutdown-hook integration.",
-      "guides": ["/docs/deployment-platform-v2", "/docs/application-packaging", "/docs/production-hardening", "/docs/observability-v3", "/docs/application-platform", "/docs/service-container"]
+      "guides": ["/docs/deployment-platform-v2", "/docs/application-packaging", "/docs/production-hardening", "/docs/observability-v3", "/docs/application-platform", "/docs/service-container", "/docs/module-system-v2"]
     },
     {
       "package": "bcp/container",
@@ -139,15 +139,23 @@
       "environment": "server",
       "route": "/docs/api-reference#bcp-container",
       "summary": "Typed dependency injection and service container with value/factory/class providers, singleton/scoped/transient lifetimes, child scopes, test overrides, dependency graph diagnostics, circular-dependency detection and reverse disposal.",
-      "guides": ["/docs/service-container", "/docs/application-platform", "/docs/testing-platform", "/docs/migration-0.3"]
+      "guides": ["/docs/service-container", "/docs/module-system-v2", "/docs/application-platform", "/docs/testing-platform", "/docs/migration-0.3"]
+    },
+    {
+      "package": "bcp/modules",
+      "source": "packages/client/src/modules.ts",
+      "environment": "server",
+      "route": "/docs/api-reference#bcp-modules",
+      "summary": "Module System v2 definitions and composition with dependency imports, DI provider exports/re-exports, plugins, shared services, deployment resources, lifecycle hooks, diagnostics and application integration.",
+      "guides": ["/docs/module-system-v2", "/docs/application-platform", "/docs/service-container", "/docs/plugin-module-platform", "/docs/migration-0.3"]
     },
     {
       "package": "bcp/application",
       "source": "packages/client/src/application.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-application",
-      "summary": "Application Platform composition root for typed app config, dependency injection, legacy shared services, plugins/modules, deployment resources, lifecycle ordering, readiness, diagnostics and graceful shutdown.",
-      "guides": ["/docs/application-platform", "/docs/service-container", "/docs/plugin-module-platform", "/docs/deployment-platform-v2", "/docs/observability-v3", "/docs/migration-0.3"]
+      "summary": "Application Platform composition root for typed app config, dependency injection, Module System v2, legacy shared services/plugins/modules, deployment resources, lifecycle ordering, readiness, diagnostics and graceful shutdown.",
+      "guides": ["/docs/application-platform", "/docs/module-system-v2", "/docs/service-container", "/docs/plugin-module-platform", "/docs/deployment-platform-v2", "/docs/observability-v3", "/docs/migration-0.3"]
     },
     {
       "package": "bcp/server",

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.3.1",
+  "versionTarget": "0.3.2",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,10 +58,11 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Application composition, dependency injection, 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" },
@@ -98,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" }
       ]
     },
     {
@@ -123,7 +124,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.3.1", "source": "releases/0.3.1.md", "version": "0.3.1", "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" },

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-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "releaseState": "unreleased",
-  "baseline": "dependency-injection-service-container",
+  "baseline": "module-system-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -28,6 +28,7 @@
     "bcp/observability",
     "bcp/deployment",
     "bcp/container",
+    "bcp/modules",
     "bcp/application",
     "bcp/server",
     "bcp/server-only",
@@ -125,6 +126,19 @@
     "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,
@@ -260,7 +274,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.3.0",
+    "previousBaseline": "0.3.1",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.3.md"
   },
@@ -275,6 +289,7 @@
     "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",
@@ -293,6 +308,6 @@
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.3.md",
-    "releaseNotes": "releases/0.3.1.md"
+    "releaseNotes": "releases/0.3.2.md"
   }
 }