@chidchanun/bcp 0.3.0 → 0.3.2

package/packages/client/src/modules.mjs

@@ -0,0 +1,392 @@
+// packages/server/src/modules.ts
+var MODULE_V2_KIND = "bcp-module-v2";
+var ModuleDependencyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ModuleDependencyError";
+  }
+};
+var ModuleLifecycleError = class extends Error {
+  module;
+  phase;
+  cause;
+  constructor(moduleName, phase, cause) {
+    super(
+      `BCP Modules: ${phase} failed for module "${moduleName}": ${formatError(cause)}`
+    );
+    this.name = "ModuleLifecycleError";
+    this.module = moduleName;
+    this.phase = phase;
+    this.cause = cause;
+  }
+};
+function defineModule(input) {
+  const definition = {
+    ...input,
+    kind: MODULE_V2_KIND
+  };
+  validateModuleDefinition(definition);
+  return definition;
+}
+function isModuleDefinition(value) {
+  return Boolean(
+    value && typeof value === "object" && value.kind === MODULE_V2_KIND
+  );
+}
+function composeModules(roots = []) {
+  const ordered = resolveModuleOrder(roots);
+  const providers = [];
+  const plugins = [];
+  const services = [];
+  const resources = [];
+  const serviceKeys = /* @__PURE__ */ new Set();
+  for (const module of ordered) {
+    providers.push(
+      ...module.providers ?? []
+    );
+    plugins.push(
+      ...module.plugins ?? []
+    );
+    resources.push(
+      ...module.resources ?? []
+    );
+    for (const entry of module.services ?? []) {
+      const [key] = entry;
+      if (serviceKeys.has(key)) {
+        throw new ModuleDependencyError(
+          `BCP Modules: duplicate shared service ${formatServiceKey(key)} while composing module "${module.name}".`
+        );
+      }
+      serviceKeys.add(key);
+      services.push(entry);
+    }
+    validateModuleExports(
+      module
+    );
+  }
+  return {
+    modules: ordered,
+    providers,
+    plugins,
+    services,
+    resources,
+    records() {
+      return ordered.map(
+        (module) => ({
+          name: module.name,
+          ...module.version ? {
+            version: module.version
+          } : {},
+          imports: (module.imports ?? []).map(
+            (dependency) => dependency.name
+          ),
+          providers: (module.providers ?? []).map(
+            (provider) => provider.token.description
+          ),
+          exports: (module.exports ?? []).map(
+            (token) => token.description
+          ),
+          plugins: (module.plugins ?? []).map(
+            (plugin) => plugin.name
+          ),
+          resources: (module.resources ?? []).map(
+            (resource) => resource.name
+          )
+        })
+      );
+    },
+    exportedTokens(moduleName) {
+      const normalized = normalizeName(
+        moduleName,
+        "module name"
+      );
+      const module = ordered.find(
+        (entry) => entry.name === normalized
+      );
+      if (!module) {
+        throw new ModuleDependencyError(
+          `BCP Modules: module "${normalized}" is not part of this composition.`
+        );
+      }
+      return [
+        ...module.exports ?? []
+      ];
+    },
+    createLifecycleResources(context) {
+      return ordered.flatMap(
+        (module) => [
+          ...module.resources ?? [],
+          createModuleLifecycleResource(
+            module,
+            context
+          )
+        ]
+      );
+    }
+  };
+}
+function resolveModuleOrder(roots) {
+  const byName = /* @__PURE__ */ new Map();
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const order = [];
+  const visit = (module, path) => {
+    validateModuleDefinition(module);
+    const name = module.name;
+    const existing = byName.get(name);
+    if (existing && existing !== module) {
+      throw new ModuleDependencyError(
+        `BCP Modules: duplicate module name "${name}" refers to different definitions.`
+      );
+    }
+    byName.set(name, module);
+    if (visited.has(name)) {
+      return;
+    }
+    if (visiting.has(name)) {
+      throw new ModuleDependencyError(
+        `BCP Modules: circular module dependency detected: ${[
+          ...path,
+          name
+        ].join(" -> ")}.`
+      );
+    }
+    visiting.add(name);
+    for (const dependency of module.imports ?? []) {
+      visit(
+        dependency,
+        [
+          ...path,
+          name
+        ]
+      );
+    }
+    visiting.delete(name);
+    visited.add(name);
+    order.push(module);
+  };
+  for (const root of roots) {
+    visit(root, []);
+  }
+  return order;
+}
+function createModuleLifecycleResource(module, shared) {
+  const config = parseModuleConfig(
+    module.schema,
+    module.config
+  );
+  const context = {
+    name: module.name,
+    config,
+    container: shared.container,
+    services: shared.services,
+    hooks: shared.hooks
+  };
+  let setupComplete = false;
+  let disposed = false;
+  return {
+    name: `bcp:module:${module.name}`,
+    async start() {
+      try {
+        if (!setupComplete) {
+          await runModuleHook(
+            module,
+            "setup",
+            module.setup,
+            context
+          );
+          setupComplete = true;
+        }
+        await runModuleHook(
+          module,
+          "start",
+          module.start,
+          context
+        );
+      } catch (error) {
+        if (!disposed) {
+          disposed = true;
+          try {
+            await runModuleHook(
+              module,
+              "dispose",
+              module.dispose,
+              context
+            );
+          } catch (disposeError) {
+            throw new AggregateError(
+              [
+                error,
+                disposeError
+              ],
+              `BCP Modules: startup and cleanup failed for module "${module.name}".`
+            );
+          }
+        }
+        throw error;
+      }
+    },
+    ready() {
+      return true;
+    },
+    async stop() {
+      const errors = [];
+      try {
+        await runModuleHook(
+          module,
+          "stop",
+          module.stop,
+          context
+        );
+      } catch (error) {
+        errors.push(error);
+      }
+      if (!disposed) {
+        disposed = true;
+        try {
+          await runModuleHook(
+            module,
+            "dispose",
+            module.dispose,
+            context
+          );
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      if (errors.length > 0) {
+        throw new AggregateError(
+          errors,
+          `BCP Modules: shutdown failed for module "${module.name}".`
+        );
+      }
+    },
+    diagnostics() {
+      return {
+        name: module.name,
+        ...module.version ? {
+          version: module.version
+        } : {},
+        imports: (module.imports ?? []).map(
+          (dependency) => dependency.name
+        ),
+        exports: (module.exports ?? []).map(
+          (token) => token.description
+        )
+      };
+    }
+  };
+}
+async function runModuleHook(module, phase, hook, context) {
+  if (!hook) {
+    return;
+  }
+  try {
+    await hook(context);
+  } catch (error) {
+    throw new ModuleLifecycleError(
+      module.name,
+      phase,
+      error
+    );
+  }
+}
+function validateModuleDefinition(module) {
+  if (!module || typeof module !== "object") {
+    throw new TypeError(
+      "BCP Modules: module must be an object."
+    );
+  }
+  if (module.kind !== MODULE_V2_KIND) {
+    throw new TypeError(
+      `BCP Modules: module kind must be "${MODULE_V2_KIND}". Use defineModule().`
+    );
+  }
+  normalizeName(
+    module.name,
+    "module name"
+  );
+  for (const [label, value] of [
+    ["imports", module.imports],
+    ["providers", module.providers],
+    ["exports", module.exports],
+    ["plugins", module.plugins],
+    ["resources", module.resources]
+  ]) {
+    if (value !== void 0 && !Array.isArray(value)) {
+      throw new TypeError(
+        `BCP Modules: ${label} must be an array.`
+      );
+    }
+  }
+  for (const [phase, hook] of [
+    ["setup", module.setup],
+    ["start", module.start],
+    ["stop", module.stop],
+    ["dispose", module.dispose]
+  ]) {
+    if (hook !== void 0 && typeof hook !== "function") {
+      throw new TypeError(
+        `BCP Modules: ${phase} must be a function.`
+      );
+    }
+  }
+}
+function validateModuleExports(module) {
+  const available = /* @__PURE__ */ new Set();
+  for (const provider of module.providers ?? []) {
+    available.add(
+      provider.token.id
+    );
+  }
+  for (const dependency of module.imports ?? []) {
+    for (const token of dependency.exports ?? []) {
+      available.add(token.id);
+    }
+  }
+  for (const token of module.exports ?? []) {
+    if (!available.has(token.id)) {
+      throw new ModuleDependencyError(
+        `BCP Modules: module "${module.name}" exports "${token.description}" but does not provide or import it.`
+      );
+    }
+  }
+}
+function parseModuleConfig(parser, value) {
+  if (!parser) {
+    return value;
+  }
+  if (typeof parser === "function") {
+    return parser(value);
+  }
+  return parser.parse(value);
+}
+function normalizeName(value, label) {
+  if (typeof value !== "string") {
+    throw new TypeError(
+      `BCP Modules: ${label} must be a string.`
+    );
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new TypeError(
+      `BCP Modules: ${label} cannot be empty.`
+    );
+  }
+  return normalized;
+}
+function formatServiceKey(key) {
+  return typeof key === "symbol" ? key.description ? `Symbol(${key.description})` : key.toString() : key;
+}
+function formatError(value) {
+  return value instanceof Error ? value.message : String(value);
+}
+export {
+  MODULE_V2_KIND,
+  ModuleDependencyError,
+  ModuleLifecycleError,
+  composeModules,
+  defineModule,
+  isModuleDefinition,
+  resolveModuleOrder
+};

package/packages/client/src/modules.ts

@@ -0,0 +1,17 @@
+export {
+    MODULE_V2_KIND,
+    ModuleDependencyError,
+    ModuleLifecycleError,
+    composeModules,
+    defineModule,
+    isModuleDefinition,
+    resolveModuleOrder,
+
+    type ModuleComposition,
+    type ModuleConfigParser,
+    type ModuleConfigSchema,
+    type ModuleContext,
+    type ModuleDefinition,
+    type ModuleInput,
+    type ModuleRecord,
+} from "../../server/src/modules.js";

package/packages/server/src/application.ts

@@ -1,3 +1,12 @@
+import {
+    createServiceContainer,
+
+    type ServiceContainer,
+    type ServiceProvider,
+    type ServiceScope,
+    type ServiceScopeOptions,
+} from "./container.js";
+
 import {
     createDeploymentRuntime,
 
@@ -11,6 +20,14 @@ import {
     type DeploymentSignalOptions,
 } from "./deployment.js";
 
+import {
+    composeModules,
+    isModuleDefinition,
+
+    type ModuleComposition,
+    type ModuleDefinition,
+} from "./modules.js";
+
 import {
     createPluginHost,
 
@@ -52,6 +69,8 @@ export interface ApplicationContext<TConfig = unknown> {
     readonly name: string;
     readonly version?: string;
     readonly config: TConfig;
+    readonly container: ServiceContainer;
+    readonly modules: ModuleComposition;
     readonly services: PluginServiceRegistry;
     readonly hooks: PluginHookBus;
     readonly plugins: PluginHost;
@@ -65,8 +84,12 @@ export interface ApplicationDefinition<TConfig = unknown> {
     version?: string;
     config?: unknown;
     schema?: ApplicationConfigParser<TConfig>;
+    providers?: readonly ServiceProvider<any>[];
     plugins?: readonly PluginDefinition<any>[];
-    modules?: readonly PluginModule[];
+    modules?: readonly (
+        | PluginModule
+        | ModuleDefinition<any>
+    )[];
     pluginConfigs?: Record<string, unknown>;
     services?: Iterable<
         readonly [PluginServiceKey, unknown]
@@ -96,6 +119,8 @@ export interface Application<TConfig = unknown> {
     readonly state: ApplicationState;
     readonly config: TConfig;
     readonly context: ApplicationContext<TConfig>;
+    readonly container: ServiceContainer;
+    readonly modules: ModuleComposition;
     readonly services: PluginServiceRegistry;
     readonly hooks: PluginHookBus;
     readonly plugins: PluginHost;
@@ -112,6 +137,15 @@ export interface Application<TConfig = unknown> {
             replace?: boolean;
         }
     ): Application<TConfig>;
+    register<T>(
+        provider: ServiceProvider<T>,
+        options?: {
+            replace?: boolean;
+        }
+    ): Application<TConfig>;
+    createScope(
+        options?: ServiceScopeOptions
+    ): ServiceScope;
     addResource(
         resource: DeploymentResource
     ): Application<TConfig>;
@@ -180,16 +214,42 @@ export function createApp<TConfig = unknown>(
             definition.schema,
             definition.config
         );
+    const moduleInputs =
+        definition.modules ?? [];
+    const modules =
+        composeModules(
+            moduleInputs.filter(
+                isModuleDefinition
+            )
+        );
+    const legacyModules =
+        moduleInputs.filter(
+            module =>
+                !isModuleDefinition(module)
+        ) as PluginModule[];
+    const container =
+        createServiceContainer({
+            name:
+                `${name}:container`,
+            providers: [
+                ...modules.providers,
+                ...(definition.providers ?? []),
+            ],
+        });
     const plugins =
         createPluginHost({
-            plugins:
-                definition.plugins,
+            plugins: [
+                ...modules.plugins,
+                ...(definition.plugins ?? []),
+            ],
             modules:
-                definition.modules,
+                legacyModules,
             configs:
                 definition.pluginConfigs,
-            services:
-                definition.services,
+            services: [
+                ...modules.services,
+                ...(definition.services ?? []),
+            ],
         });
     const deployment =
         createDeploymentRuntime({
@@ -229,6 +289,8 @@ export function createApp<TConfig = unknown>(
             }
             : {}),
         config,
+        container,
+        modules,
         services:
             plugins.services,
         hooks:
@@ -243,6 +305,38 @@ export function createApp<TConfig = unknown>(
         },
     };
 
+    deployment.addResource({
+        name:
+            "bcp:container",
+        ready() {
+            return {
+                ok:
+                    container.state ===
+                    "active",
+                detail:
+                    `Service container is ${container.state}.`,
+            };
+        },
+        async stop() {
+            await container.dispose();
+        },
+        diagnostics() {
+            return {
+                state:
+                    container.state,
+                providers:
+                    container.graph().map(
+                        node => ({
+                            token:
+                                node.description,
+                            lifetime:
+                                node.lifetime,
+                        })
+                    ),
+            };
+        },
+    });
+
     deployment.addResource({
         name:
             "bcp:plugins",
@@ -272,6 +366,19 @@ export function createApp<TConfig = unknown>(
         },
     });
 
+    for (
+        const resource
+        of modules.createLifecycleResources({
+            container,
+            services:
+                plugins.services,
+            hooks:
+                plugins.hooks,
+        })
+    ) {
+        deployment.addResource(resource);
+    }
+
     for (
         const resource
         of definition.resources ?? []
@@ -284,11 +391,13 @@ export function createApp<TConfig = unknown>(
         name,
         ...(version
             ? {
-                    version,
-                }
+                version,
+            }
             : {}),
         config,
         context,
+        container,
+        modules,
         services:
             plugins.services,
         hooks:
@@ -322,6 +431,26 @@ export function createApp<TConfig = unknown>(
             return app;
         },
 
+        register<T>(
+            provider: ServiceProvider<T>,
+            options: {
+                replace?: boolean;
+            } = {}
+        ) {
+            assertMutable();
+            container.register(
+                provider,
+                options
+            );
+            return app;
+        },
+
+        createScope(options = {}) {
+            return container.createScope(
+                options
+            );
+        },
+
         addResource(resource) {
             assertMutable();
             deployment.addResource(
@@ -562,6 +691,14 @@ export function createApp<TConfig = unknown>(
                 }
             }
 
+            if (container.state !== "disposed") {
+                try {
+                    await container.dispose();
+                } catch (error) {
+                    errors.push(error);
+                }
+            }
+
             try {
                 await disposeApplication();
             } catch (error) {
@@ -612,8 +749,8 @@ export function createApp<TConfig = unknown>(
                     name,
                     ...(version
                         ? {
-                                version,
-                            }
+                            version,
+                        }
                         : {}),
                     state,
                     services:
@@ -622,6 +759,13 @@ export function createApp<TConfig = unknown>(
                             .map(
                                 formatServiceKey
                             ),
+                    containerProviders:
+                        container.graph().map(
+                            node =>
+                                node.description
+                        ),
+                    modules:
+                        modules.records(),
                     pluginCount:
                         plugins.plugins().length,
                 };
@@ -654,6 +798,14 @@ export function createApp<TConfig = unknown>(
             // Preserve the original startup failure.
         }
 
+        if (container.state !== "disposed") {
+            try {
+                await container.dispose();
+            } catch {
+                // Preserve the original startup failure.
+            }
+        }
+
         try {
             await disposeApplication();
         } catch {
@@ -697,7 +849,7 @@ export function createApp<TConfig = unknown>(
     function assertMutable(): void {
         if (state !== "created") {
             throw new Error(
-                "BCP Application: plugins, services and resources must be registered before start()."
+                "BCP Application: plugins, services, providers and resources must be registered before start()."
             );
         }
     }
@@ -747,6 +899,14 @@ function validateDefinition<TConfig>(
         definition.version
     );
 
+    if (
+        definition.providers !== undefined &&
+        !Array.isArray(definition.providers)
+    ) {
+        throw new TypeError(
+            "BCP Application: providers must be an array."
+        );
+    }
     if (
         definition.plugins !== undefined &&
         !Array.isArray(definition.plugins)