@chidchanun/bcp 0.3.0 → 0.3.2

package/packages/client/src/application.mjs

@@ -1,3 +1,506 @@
+// packages/server/src/container.ts
+var ServiceNotFoundError = class extends Error {
+  token;
+  constructor(token) {
+    super(
+      `BCP Container: service "${token.description}" is not registered.`
+    );
+    this.name = "ServiceNotFoundError";
+    this.token = token;
+  }
+};
+var ServiceResolutionError = class extends Error {
+  token;
+  cause;
+  constructor(token, message, cause) {
+    super(
+      `BCP Container: could not resolve "${token.description}". ${message}`
+    );
+    this.name = "ServiceResolutionError";
+    this.token = token;
+    this.cause = cause;
+  }
+};
+var ServiceDisposalError = class extends AggregateError {
+  constructor(errors) {
+    super(
+      errors,
+      "BCP Container: one or more services failed to dispose."
+    );
+    this.name = "ServiceDisposalError";
+  }
+};
+function createServiceContainer(options = {}) {
+  const root = new ScopeImpl(
+    normalizeOptionalName(
+      options.name
+    ) ?? "root",
+    void 0
+  );
+  root.root = root;
+  const container = {
+    get name() {
+      return root.name;
+    },
+    get state() {
+      return root.state;
+    },
+    get parent() {
+      return void 0;
+    },
+    has(token) {
+      return root.has(token);
+    },
+    resolve(token) {
+      return root.resolve(token);
+    },
+    optional(token) {
+      return root.optional(token);
+    },
+    createScope(scopeOptions = {}) {
+      return root.createScope(
+        scopeOptions
+      );
+    },
+    graph() {
+      return root.graph();
+    },
+    dispose() {
+      return root.dispose();
+    },
+    register(provider, registerOptions = {}) {
+      root.registerProvider(
+        provider,
+        registerOptions.replace === true
+      );
+      return container;
+    },
+    registerMany(providers) {
+      for (const provider of providers) {
+        root.registerProvider(
+          provider,
+          false
+        );
+      }
+      return container;
+    },
+    providers() {
+      return Array.from(
+        root.providersMap.values()
+      );
+    }
+  };
+  for (const provider of options.providers ?? []) {
+    root.registerProvider(
+      provider,
+      false
+    );
+  }
+  return container;
+}
+var ScopeImpl = class _ScopeImpl {
+  constructor(name, parent) {
+    this.name = name;
+    this.parent = parent;
+    if (parent) {
+      this.root = parent.root;
+      parent.children.add(this);
+    }
+  }
+  name;
+  parent;
+  root;
+  providersMap = /* @__PURE__ */ new Map();
+  overrideProviders = /* @__PURE__ */ new Map();
+  singletonCache = /* @__PURE__ */ new Map();
+  scopedCache = /* @__PURE__ */ new Map();
+  disposals = [];
+  children = /* @__PURE__ */ new Set();
+  state = "active";
+  disposePromise;
+  has(token) {
+    assertToken(token);
+    return this.findProvider(token) !== void 0;
+  }
+  resolve(token) {
+    return this.resolveWithPath(
+      token,
+      []
+    );
+  }
+  async optional(token) {
+    if (!this.has(token)) {
+      return void 0;
+    }
+    return this.resolve(token);
+  }
+  createScope(options = {}) {
+    this.assertActive();
+    const scope = new _ScopeImpl(
+      normalizeOptionalName(
+        options.name
+      ) ?? `${this.name}:scope-${this.children.size + 1}`,
+      this
+    );
+    for (const provider of options.overrides ?? []) {
+      scope.registerOverride(
+        provider
+      );
+    }
+    return scope;
+  }
+  graph() {
+    const effective = /* @__PURE__ */ new Map();
+    let current = this;
+    while (current) {
+      for (const [id, provider] of current.overrideProviders) {
+        if (!effective.has(id)) {
+          effective.set(
+            id,
+            {
+              provider,
+              owner: current,
+              overridden: true
+            }
+          );
+        }
+      }
+      current = current.parent;
+    }
+    for (const [id, provider] of this.root.providersMap) {
+      if (!effective.has(id)) {
+        effective.set(
+          id,
+          {
+            provider,
+            owner: this.root,
+            overridden: false
+          }
+        );
+      }
+    }
+    return Array.from(
+      effective.values(),
+      (record) => ({
+        token: record.provider.token,
+        description: record.provider.token.description,
+        lifetime: normalizeLifetime(
+          record.provider.lifetime
+        ),
+        dependencies: (record.provider.dependencies ?? []).map(
+          (dependency) => dependency.description
+        ),
+        overridden: record.overridden
+      })
+    ).sort(
+      (left, right) => left.description.localeCompare(
+        right.description
+      )
+    );
+  }
+  dispose() {
+    if (this.disposePromise) {
+      return this.disposePromise;
+    }
+    if (this.state === "disposed") {
+      return Promise.resolve();
+    }
+    this.disposePromise = this.disposeInternal();
+    return this.disposePromise;
+  }
+  registerProvider(provider, replace) {
+    this.assertActive();
+    if (this.parent) {
+      throw new Error(
+        "BCP Container: providers can only be registered on the root container. Use scope overrides for child scopes."
+      );
+    }
+    validateProvider(provider);
+    const id = provider.token.id;
+    if (this.providersMap.has(id) && !replace) {
+      throw new Error(
+        `BCP Container: service "${provider.token.description}" is already registered.`
+      );
+    }
+    if (replace && this.hasResolved(id)) {
+      throw new Error(
+        `BCP Container: service "${provider.token.description}" cannot be replaced after it has been resolved.`
+      );
+    }
+    this.providersMap.set(
+      id,
+      provider
+    );
+  }
+  registerOverride(provider) {
+    validateProvider(provider);
+    const id = provider.token.id;
+    if (this.overrideProviders.has(id)) {
+      throw new Error(
+        `BCP Container: scope override for "${provider.token.description}" is already registered.`
+      );
+    }
+    this.overrideProviders.set(
+      id,
+      provider
+    );
+  }
+  async resolveWithPath(token, path) {
+    this.assertActive();
+    assertToken(token);
+    if (path.some(
+      (item) => item.id === token.id
+    )) {
+      throw new ServiceResolutionError(
+        token,
+        `Circular dependency detected: ${[
+          ...path,
+          token
+        ].map(
+          (item) => item.description
+        ).join(" -> ")}.`
+      );
+    }
+    const record = this.findProvider(token);
+    if (!record) {
+      throw new ServiceNotFoundError(
+        token
+      );
+    }
+    const lifetime = normalizeLifetime(
+      record.provider.lifetime
+    );
+    const cache = lifetime === "singleton" ? record.owner.singletonCache : lifetime === "scoped" ? this.scopedCache : void 0;
+    const existing = cache?.get(token.id);
+    if (existing) {
+      return existing;
+    }
+    const resolution = this.instantiate(
+      record.provider,
+      [
+        ...path,
+        token
+      ],
+      lifetime,
+      record.owner
+    );
+    cache?.set(
+      token.id,
+      resolution
+    );
+    try {
+      return await resolution;
+    } catch (error) {
+      cache?.delete(token.id);
+      if (error instanceof ServiceNotFoundError || error instanceof ServiceResolutionError) {
+        throw error;
+      }
+      throw new ServiceResolutionError(
+        token,
+        error instanceof Error ? error.message : String(error),
+        error
+      );
+    }
+  }
+  async instantiate(provider, path, lifetime, providerOwner) {
+    const dependencies = await Promise.all(
+      (provider.dependencies ?? []).map(
+        (dependency) => this.resolveWithPath(
+          dependency,
+          path
+        )
+      )
+    );
+    const context = {
+      scope: this,
+      resolve: (dependency) => this.resolveWithPath(
+        dependency,
+        path
+      ),
+      optional: async (dependency) => {
+        if (!this.has(dependency)) {
+          return void 0;
+        }
+        return this.resolveWithPath(
+          dependency,
+          path
+        );
+      }
+    };
+    const value = await provider.factory(
+      context,
+      dependencies
+    );
+    if (provider.dispose) {
+      const disposalOwner = lifetime === "singleton" ? providerOwner : this;
+      disposalOwner.disposals.push({
+        provider,
+        value
+      });
+    }
+    return value;
+  }
+  findProvider(token) {
+    let current = this;
+    while (current) {
+      const override = current.overrideProviders.get(
+        token.id
+      );
+      if (override) {
+        return {
+          provider: override,
+          owner: current,
+          overridden: true
+        };
+      }
+      current = current.parent;
+    }
+    const provider = this.root.providersMap.get(
+      token.id
+    );
+    if (!provider) {
+      return void 0;
+    }
+    return {
+      provider,
+      owner: this.root,
+      overridden: false
+    };
+  }
+  async disposeInternal() {
+    this.state = "disposing";
+    const errors = [];
+    for (const child of Array.from(
+      this.children
+    ).reverse()) {
+      try {
+        await child.dispose();
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    for (const record of [...this.disposals].reverse()) {
+      if (!record.provider.dispose) {
+        continue;
+      }
+      try {
+        await record.provider.dispose(
+          record.value
+        );
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    this.disposals.length = 0;
+    this.singletonCache.clear();
+    this.scopedCache.clear();
+    this.children.clear();
+    this.parent?.children.delete(this);
+    this.state = "disposed";
+    if (errors.length > 0) {
+      throw new ServiceDisposalError(
+        errors
+      );
+    }
+  }
+  hasResolved(id) {
+    if (this.singletonCache.has(id) || this.scopedCache.has(id)) {
+      return true;
+    }
+    for (const child of this.children) {
+      if (child.hasResolved(id)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  assertActive() {
+    if (this.state !== "active") {
+      throw new Error(
+        `BCP Container: scope "${this.name}" is ${this.state}.`
+      );
+    }
+  }
+};
+function validateProvider(provider) {
+  if (!provider || typeof provider !== "object") {
+    throw new TypeError(
+      "BCP Container: provider must be an object."
+    );
+  }
+  assertToken(provider.token);
+  if (typeof provider.factory !== "function") {
+    throw new TypeError(
+      `BCP Container: provider "${provider.token.description}" must define factory().`
+    );
+  }
+  normalizeLifetime(
+    provider.lifetime
+  );
+  assertDependencies(
+    provider.dependencies ?? []
+  );
+  if (provider.dispose !== void 0 && typeof provider.dispose !== "function") {
+    throw new TypeError(
+      `BCP Container: provider "${provider.token.description}" dispose must be a function.`
+    );
+  }
+}
+function assertToken(token) {
+  if (!token || typeof token !== "object" || typeof token.id !== "symbol" || typeof token.description !== "string" || token.description.trim() === "") {
+    throw new TypeError(
+      "BCP Container: invalid service token. Use createServiceToken()."
+    );
+  }
+}
+function assertDependencies(dependencies) {
+  if (!Array.isArray(dependencies)) {
+    throw new TypeError(
+      "BCP Container: provider dependencies must be an array."
+    );
+  }
+  for (const dependency of dependencies) {
+    assertToken(dependency);
+  }
+}
+function normalizeLifetime(lifetime) {
+  const normalized = lifetime ?? "singleton";
+  if (normalized !== "singleton" && normalized !== "scoped" && normalized !== "transient") {
+    throw new TypeError(
+      "BCP Container: service lifetime must be singleton, scoped or transient."
+    );
+  }
+  return normalized;
+}
+function normalizeName(value, label) {
+  if (typeof value !== "string") {
+    throw new TypeError(
+      `BCP Container: ${label} must be a string.`
+    );
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new TypeError(
+      `BCP Container: ${label} cannot be empty.`
+    );
+  }
+  if (normalized.length > 256 || /[\r\n]/.test(normalized)) {
+    throw new TypeError(
+      `BCP Container: ${label} must be at most 256 characters without line breaks.`
+    );
+  }
+  return normalized;
+}
+function normalizeOptionalName(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return normalizeName(
+    value,
+    "scope name"
+  );
+}
+
 // packages/server/src/deployment.ts
 import {
   randomUUID
@@ -73,7 +576,7 @@ function createDeploymentRuntime(options) {
     "runtime start timestamp"
   );
   const metadata = {
-    serviceName: normalizeName(
+    serviceName: normalizeName2(
       options.serviceName,
       "serviceName"
     ),
@@ -84,7 +587,7 @@ function createDeploymentRuntime(options) {
         options.version
       )
     } : {},
-    deploymentId: normalizeName(
+    deploymentId: normalizeName2(
       options.deploymentId ?? environment.BCP_DEPLOYMENT_ID ?? idFactory(),
       "deploymentId"
     ),
@@ -132,7 +635,7 @@ function createDeploymentRuntime(options) {
           "BCP Deployment: resources can only be registered before runtime start."
         );
       }
-      const name = normalizeName(
+      const name = normalizeName2(
         resource.name,
         "resource name"
       );
@@ -496,7 +999,7 @@ function normalizeSignals(signals) {
     new Set(signals)
   );
 }
-function normalizeName(value, field) {
+function normalizeName2(value, field) {
   const normalized = String(value ?? "").trim();
   if (!normalized) {
     throw new TypeError(
@@ -579,6 +1082,382 @@ function withTimeout(promise, timeoutMs, label) {
   );
 }
 
+// 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 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 = normalizeName3(
+        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().`
+    );
+  }
+  normalizeName3(
+    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 normalizeName3(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);
+}
+
 // packages/server/src/plugins.ts
 var PluginDependencyError = class extends Error {
   constructor(message) {
@@ -592,7 +1471,7 @@ var PluginLifecycleError = class extends Error {
   cause;
   constructor(plugin, phase, cause) {
     super(
-      `BCP Plugins: ${phase} failed for plugin "${plugin}": ${formatError(cause)}`
+      `BCP Plugins: ${phase} failed for plugin "${plugin}": ${formatError2(cause)}`
     );
     this.name = "PluginLifecycleError";
     this.plugin = plugin;
@@ -606,7 +1485,7 @@ function defineModule(module) {
       "BCP Plugins: module must be an object."
     );
   }
-  normalizeName2(
+  normalizeName4(
     module.name,
     "module name"
   );
@@ -627,7 +1506,7 @@ function createPluginServiceRegistry(initial) {
       assertServiceKey(key);
       if (values.has(key)) {
         throw new Error(
-          `BCP Plugins: duplicate initial service ${formatServiceKey(key)}.`
+          `BCP Plugins: duplicate initial service ${formatServiceKey2(key)}.`
         );
       }
       values.set(key, value);
@@ -638,7 +1517,7 @@ function createPluginServiceRegistry(initial) {
       assertServiceKey(key);
       if (values.has(key) && !options.replace) {
         throw new Error(
-          `BCP Plugins: service ${formatServiceKey(key)} is already registered.`
+          `BCP Plugins: service ${formatServiceKey2(key)} is already registered.`
         );
       }
       values.set(key, value);
@@ -647,7 +1526,7 @@ function createPluginServiceRegistry(initial) {
       assertServiceKey(key);
       if (!values.has(key)) {
         throw new Error(
-          `BCP Plugins: service ${formatServiceKey(key)} is not registered.`
+          `BCP Plugins: service ${formatServiceKey2(key)} is not registered.`
         );
       }
       return values.get(key);
@@ -676,7 +1555,7 @@ function createPluginHookBus() {
   const hooks = /* @__PURE__ */ new Map();
   const bus = {
     on(name, handler) {
-      const normalized = normalizeName2(
+      const normalized = normalizeName4(
         name,
         "hook name"
       );
@@ -706,7 +1585,7 @@ function createPluginHookBus() {
       };
     },
     async emit(name, payload) {
-      const normalized = normalizeName2(
+      const normalized = normalizeName4(
         name,
         "hook name"
       );
@@ -722,7 +1601,7 @@ function createPluginHookBus() {
     },
     listenerCount(name) {
       return hooks.get(
-        normalizeName2(
+        normalizeName4(
           name,
           "hook name"
         )
@@ -734,7 +1613,7 @@ function createPluginHookBus() {
         return;
       }
       hooks.delete(
-        normalizeName2(
+        normalizeName4(
           name,
           "hook name"
         )
@@ -967,7 +1846,7 @@ function createPluginHost(options = {}) {
     },
     plugin(name) {
       const entry = entries.get(
-        normalizeName2(
+        normalizeName4(
           name,
           "plugin name"
         )
@@ -1001,7 +1880,7 @@ function createPluginHost(options = {}) {
     validatePluginDefinition(
       definition
     );
-    const name = normalizeName2(
+    const name = normalizeName4(
       definition.name,
       "plugin name"
     );
@@ -1218,7 +2097,7 @@ function validatePluginDefinition(definition) {
       "BCP Plugins: plugin definition must be an object."
     );
   }
-  const name = normalizeName2(
+  const name = normalizeName4(
     definition.name,
     "plugin name"
   );
@@ -1261,7 +2140,7 @@ function normalizeDependencyList(value, plugin, field) {
     );
   }
   const normalized = value.map(
-    (item) => normalizeName2(
+    (item) => normalizeName4(
       item,
       `${field} dependency`
     )
@@ -1302,7 +2181,7 @@ function requireContext(entry) {
 }
 function markFailed(entry, error) {
   entry.record.state = "failed";
-  entry.record.error = formatError(error);
+  entry.record.error = formatError2(error);
 }
 function cloneRecord(record) {
   return {
@@ -1322,7 +2201,7 @@ function isPluginModule(value) {
     )
   );
 }
-function normalizeName2(value, field) {
+function normalizeName4(value, field) {
   const text = String(value ?? "").trim();
   if (!text) {
     throw new TypeError(
@@ -1340,14 +2219,14 @@ function normalizeOptionalVersion(value) {
   if (value === void 0) {
     return void 0;
   }
-  return normalizeName2(
+  return normalizeName4(
     value,
     "plugin version"
   );
 }
 function assertServiceKey(key) {
   if (typeof key === "string") {
-    normalizeName2(
+    normalizeName4(
       key,
       "service key"
     );
@@ -1359,10 +2238,10 @@ function assertServiceKey(key) {
     );
   }
 }
-function formatServiceKey(key) {
+function formatServiceKey2(key) {
   return typeof key === "symbol" ? String(key) : `"${key}"`;
 }
-function formatError(error) {
+function formatError2(error) {
   if (error instanceof Error) {
     return error.message || error.name;
   }
@@ -1386,7 +2265,7 @@ var ApplicationLifecycleError = class extends Error {
   cause;
   constructor(phase, cause) {
     super(
-      `BCP Application: ${phase} failed: ${formatError2(cause)}`
+      `BCP Application: ${phase} failed: ${formatError3(cause)}`
     );
     this.name = "ApplicationLifecycleError";
     this.phase = phase;
@@ -1399,7 +2278,7 @@ function defineApp(definition) {
 }
 function createApp(definition) {
   defineApp(definition);
-  const name = normalizeName3(
+  const name = normalizeName5(
     definition.name,
     "application name"
   );
@@ -1410,11 +2289,33 @@ function createApp(definition) {
     definition.schema,
     definition.config
   );
+  const moduleInputs = definition.modules ?? [];
+  const modules = composeModules(
+    moduleInputs.filter(
+      isModuleDefinition
+    )
+  );
+  const legacyModules = moduleInputs.filter(
+    (module) => !isModuleDefinition(module)
+  );
+  const container = createServiceContainer({
+    name: `${name}:container`,
+    providers: [
+      ...modules.providers,
+      ...definition.providers ?? []
+    ]
+  });
   const plugins = createPluginHost({
-    plugins: definition.plugins,
-    modules: definition.modules,
+    plugins: [
+      ...modules.plugins,
+      ...definition.plugins ?? []
+    ],
+    modules: legacyModules,
     configs: definition.pluginConfigs,
-    services: definition.services
+    services: [
+      ...modules.services,
+      ...definition.services ?? []
+    ]
   });
   const deployment = createDeploymentRuntime({
     ...definition.deployment ?? {},
@@ -1436,6 +2337,8 @@ function createApp(definition) {
       version
     } : {},
     config,
+    container,
+    modules,
     services: plugins.services,
     hooks: plugins.hooks,
     plugins,
@@ -1447,6 +2350,29 @@ function createApp(definition) {
       return state;
     }
   };
+  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",
     async start() {
@@ -1468,6 +2394,13 @@ function createApp(definition) {
       };
     }
   });
+  for (const resource of modules.createLifecycleResources({
+    container,
+    services: plugins.services,
+    hooks: plugins.hooks
+  })) {
+    deployment.addResource(resource);
+  }
   for (const resource of definition.resources ?? []) {
     deployment.addResource(resource);
   }
@@ -1478,6 +2411,8 @@ function createApp(definition) {
     } : {},
     config,
     context,
+    container,
+    modules,
     services: plugins.services,
     hooks: plugins.hooks,
     plugins,
@@ -1499,6 +2434,19 @@ function createApp(definition) {
       );
       return app;
     },
+    register(provider, options = {}) {
+      assertMutable();
+      container.register(
+        provider,
+        options
+      );
+      return app;
+    },
+    createScope(options = {}) {
+      return container.createScope(
+        options
+      );
+    },
     addResource(resource) {
       assertMutable();
       deployment.addResource(
@@ -1675,6 +2623,13 @@ function createApp(definition) {
           errors.push(error);
         }
       }
+      if (container.state !== "disposed") {
+        try {
+          await container.dispose();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
       try {
         await disposeApplication();
       } catch (error) {
@@ -1720,8 +2675,12 @@ function createApp(definition) {
           } : {},
           state,
           services: plugins.services.keys().map(
-            formatServiceKey2
+            formatServiceKey3
           ),
+          containerProviders: container.graph().map(
+            (node) => node.description
+          ),
+          modules: modules.records(),
           pluginCount: plugins.plugins().length
         };
       }
@@ -1741,6 +2700,12 @@ function createApp(definition) {
       await plugins.close();
     } catch {
     }
+    if (container.state !== "disposed") {
+      try {
+        await container.dispose();
+      } catch {
+      }
+    }
     try {
       await disposeApplication();
     } catch {
@@ -1772,7 +2737,7 @@ function createApp(definition) {
   function assertMutable() {
     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()."
       );
     }
   }
@@ -1797,13 +2762,18 @@ function validateDefinition(definition) {
       "BCP Application: definition must be an object."
     );
   }
-  normalizeName3(
+  normalizeName5(
     definition.name,
     "application name"
   );
   normalizeOptionalText2(
     definition.version
   );
+  if (definition.providers !== void 0 && !Array.isArray(definition.providers)) {
+    throw new TypeError(
+      "BCP Application: providers must be an array."
+    );
+  }
   if (definition.plugins !== void 0 && !Array.isArray(definition.plugins)) {
     throw new TypeError(
       "BCP Application: plugins must be an array."
@@ -1832,7 +2802,7 @@ function validateDefinition(definition) {
     }
   }
 }
-function normalizeName3(value, label) {
+function normalizeName5(value, label) {
   if (typeof value !== "string") {
     throw new TypeError(
       `BCP Application: ${label} must be a string.`
@@ -1857,10 +2827,10 @@ function normalizeOptionalText2(value) {
   }
   return value.trim() || void 0;
 }
-function formatServiceKey2(key) {
+function formatServiceKey3(key) {
   return typeof key === "symbol" ? key.description ? `Symbol(${key.description})` : key.toString() : key;
 }
-function formatError2(value) {
+function formatError3(value) {
   if (value instanceof Error) {
     return value.message;
   }