bazis 0.96.1

package/core/di/ServiceScope.ts

@@ -0,0 +1,61 @@
+import { ResolutionScopeState } from "./internal/ResolutionScopeState";
+import type { Token } from "./token";
+import type { ServiceKey } from "./types";
+
+interface ScopeResolver {
+  resolveForScope<T>(token: Token<T>, scopeState: ResolutionScopeState): T;
+  resolveAllForScope<T>(token: Token<T>, scopeState: ResolutionScopeState): readonly T[];
+  resolveKeyedForScope<T>(token: Token<T>, key: ServiceKey, scopeState: ResolutionScopeState): T;
+  resolveAllKeyedForScope<T>(
+    token: Token<T>,
+    key: ServiceKey | undefined,
+    scopeState: ResolutionScopeState,
+  ): readonly T[];
+  resolveAsyncForScope<T>(token: Token<T>, key: ServiceKey | undefined, scopeState: ResolutionScopeState): Promise<T>;
+  tryResolveForScope<T>(token: Token<T>, key: ServiceKey | undefined, scopeState: ResolutionScopeState): T | undefined;
+  has(token: Token<unknown>, key?: ServiceKey): boolean;
+  disposeScope(scopeState: ResolutionScopeState): Promise<void>;
+}
+
+export class ServiceScope {
+  public constructor(
+    private readonly provider: ScopeResolver,
+    private readonly state: ResolutionScopeState,
+  ) {}
+
+  public resolve<T>(token: Token<T>): T {
+    return this.provider.resolveForScope(token, this.state);
+  }
+
+  public resolveAll<T>(token: Token<T>): readonly T[] {
+    return this.provider.resolveAllForScope(token, this.state);
+  }
+
+  public resolveKeyed<T>(token: Token<T>, key: ServiceKey): T {
+    return this.provider.resolveKeyedForScope(token, key, this.state);
+  }
+
+  public resolveAllKeyed<T>(token: Token<T>, key: ServiceKey): readonly T[] {
+    return this.provider.resolveAllKeyedForScope(token, key, this.state);
+  }
+
+  public resolveAsync<T>(token: Token<T>): Promise<T> {
+    return this.provider.resolveAsyncForScope(token, undefined, this.state);
+  }
+
+  public resolveKeyedAsync<T>(token: Token<T>, key: ServiceKey): Promise<T> {
+    return this.provider.resolveAsyncForScope(token, key, this.state);
+  }
+
+  public tryResolve<T>(token: Token<T>, key?: ServiceKey): T | undefined {
+    return this.provider.tryResolveForScope(token, key, this.state);
+  }
+
+  public has(token: Token<unknown>, key?: ServiceKey): boolean {
+    return this.provider.has(token, key);
+  }
+
+  public async dispose(): Promise<void> {
+    await this.provider.disposeScope(this.state);
+  }
+}

package/core/di/container.ts

@@ -0,0 +1,38 @@
+import type { OpenGenericRegistration } from "./internal/OpenGenericRegistration";
+import { ServiceProvider } from "./ServiceProvider";
+import type { BuildServiceProviderOptions } from "./types";
+import type { ProviderDefinition } from "./provider";
+import type {
+  ModuleOwnedMetadataChannel,
+  ModuleOwnedMetadataContribution,
+  ModuleOwnedProviderChannel,
+  ModuleOwnedProviderContribution,
+  ModuleOwnedContributionStore,
+} from "./module/moduleOwnedProviderContributors";
+
+const EMPTY_MODULE_OWNED_CONTRIBUTIONS: readonly never[] = Object.freeze([]);
+
+export class DiContainer extends ServiceProvider {
+  public constructor(
+    definitions: readonly ProviderDefinition[],
+    openGenericRegistrations: readonly OpenGenericRegistration[],
+    options?: BuildServiceProviderOptions,
+    private readonly moduleOwnedContributions?: ModuleOwnedContributionStore,
+  ) {
+    super(definitions, openGenericRegistrations, options);
+  }
+
+  /** Returns only records for the caller-held opaque provider channel. */
+  public getModuleOwnedProviderContributions<TPayload, TService>(
+    channel: ModuleOwnedProviderChannel<TPayload, TService>,
+  ): readonly ModuleOwnedProviderContribution<TPayload, TService>[] {
+    return this.moduleOwnedContributions?.getProvider(channel) ?? EMPTY_MODULE_OWNED_CONTRIBUTIONS;
+  }
+
+  /** Returns only records for the caller-held opaque metadata channel. */
+  public getModuleOwnedMetadataContributions<TPayload>(
+    channel: ModuleOwnedMetadataChannel<TPayload>,
+  ): readonly ModuleOwnedMetadataContribution<TPayload>[] {
+    return this.moduleOwnedContributions?.getMetadata(channel) ?? EMPTY_MODULE_OWNED_CONTRIBUTIONS;
+  }
+}

package/core/di/errors/AmbiguousNamedDependencyError.ts

@@ -0,0 +1,10 @@
+import { DiError } from "./DiError";
+
+export class AmbiguousNamedDependencyError extends DiError {
+  public constructor(name: string) {
+    super(
+      `Multiple provider tokens share the debug name "${name}", named dependency resolution is ambiguous. ` +
+        `Rename one of the tokens or declare deps explicitly.`,
+    );
+  }
+}

package/core/di/errors/AsyncResolutionRequiredError.ts

@@ -0,0 +1,12 @@
+import { tokenToDebugName } from "../token";
+import type { Token } from "../token";
+import { DiError } from "./DiError";
+
+export class AsyncResolutionRequiredError extends DiError {
+  public constructor(token: Token<unknown>, path?: readonly string[]) {
+    const pathSuffix = path && path.length > 0 ? ` Resolution path: ${path.join(" -> ")}.` : "";
+    super(
+      `Provider for token "${tokenToDebugName(token)}" is asynchronous. Use resolveAsync(...) instead of resolve(...).${pathSuffix}`,
+    );
+  }
+}

package/core/di/errors/CircularDependencyError.ts

@@ -0,0 +1,10 @@
+import { tokenToDebugName } from "../token";
+import type { Token } from "../token";
+import { DiError } from "./DiError";
+
+export class CircularDependencyError extends DiError {
+  public constructor(path: readonly Token<unknown>[]) {
+    const chain = path.map((token) => tokenToDebugName(token)).join(" -> ");
+    super(`Circular dependency detected: ${chain}`);
+  }
+}

package/core/di/errors/ClassDependenciesMismatchError.ts

@@ -0,0 +1,15 @@
+import { tokenToDebugName } from "../token";
+import type { Token } from "../token";
+import { DiError } from "./DiError";
+
+export class ClassDependenciesMismatchError extends DiError {
+  public constructor(
+    token: Token<unknown>,
+    requiredConstructorParams: number,
+    declaredDeps: number,
+  ) {
+    super(
+      `Class provider "${tokenToDebugName(token)}" requires at least ${requiredConstructorParams} constructor deps, but only ${declaredDeps} declared.`,
+    );
+  }
+}

package/core/di/errors/DiError.ts

@@ -0,0 +1,6 @@
+export class DiError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}

package/core/di/errors/InvalidProviderError.ts

@@ -0,0 +1,9 @@
+import { DiError } from "./DiError";
+
+export class InvalidProviderError extends DiError {
+  public constructor(tokenName: string) {
+    super(
+      `Provider for "${tokenName}" has unknown shape: expected one of useClass/useFactory/useValue.`,
+    );
+  }
+}

package/core/di/errors/ModuleEncapsulationError.ts

@@ -0,0 +1,7 @@
+import { DiError } from "./DiError";
+
+export class ModuleEncapsulationError extends DiError {
+  public constructor(public readonly issues: readonly string[]) {
+    super(`Module encapsulation violated:\n${issues.join("\n")}`);
+  }
+}

package/core/di/errors/ModuleOwnedProviderConflictError.ts

@@ -0,0 +1,8 @@
+import { DiError } from "./DiError";
+
+/** A module-owned provider was also registered through another DI path. */
+export class ModuleOwnedProviderConflictError extends DiError {
+  public constructor(public readonly issues: readonly string[]) {
+    super(`Module-owned provider registration conflict:\n${issues.join("\n")}`);
+  }
+}

package/core/di/errors/NamedDependencyNotFoundError.ts

@@ -0,0 +1,7 @@
+import { DiError } from "./DiError";
+
+export class NamedDependencyNotFoundError extends DiError {
+  public constructor(name: string) {
+    super(`No provider token found for named dependency "${name}".`);
+  }
+}

package/core/di/errors/OptionsValidationError.ts

@@ -0,0 +1,7 @@
+import { DiError } from "./DiError";
+
+export class OptionsValidationError extends DiError {
+  public constructor(public readonly issues: readonly string[]) {
+    super(`Options validation failed:\n${issues.join("\n")}`);
+  }
+}

package/core/di/errors/ProviderNotFoundError.ts

@@ -0,0 +1,10 @@
+import { tokenToDebugName } from "../token";
+import type { Token } from "../token";
+import { DiError } from "./DiError";
+
+export class ProviderNotFoundError extends DiError {
+  public constructor(token: Token<unknown>, path?: readonly string[]) {
+    const pathSuffix = path && path.length > 0 ? ` Resolution path: ${path.join(" -> ")}.` : "";
+    super(`Provider for token "${tokenToDebugName(token)}" was not found.${pathSuffix}`);
+  }
+}

package/core/di/errors/ScopeDisposedError.ts

@@ -0,0 +1,7 @@
+import { DiError } from "./DiError";
+
+export class ScopeDisposedError extends DiError {
+  public constructor() {
+    super("Cannot use a disposed scope or container.");
+  }
+}

package/core/di/errors/ScopedServiceFromRootError.ts

@@ -0,0 +1,9 @@
+import { tokenToDebugName } from "../token";
+import type { Token } from "../token";
+import { DiError } from "./DiError";
+
+export class ScopedServiceFromRootError extends DiError {
+  public constructor(token: Token<unknown>) {
+    super(`Cannot resolve scoped service "${tokenToDebugName(token)}" from root provider.`);
+  }
+}

package/core/di/errors/ServiceValidationError.ts

@@ -0,0 +1,7 @@
+import { DiError } from "./DiError";
+
+export class ServiceValidationError extends DiError {
+  public constructor(public readonly issues: readonly string[]) {
+    super(`Service graph validation failed:\n${issues.join("\n")}`);
+  }
+}

package/core/di/errors/index.ts

@@ -0,0 +1,14 @@
+export { AmbiguousNamedDependencyError } from "./AmbiguousNamedDependencyError";
+export { AsyncResolutionRequiredError } from "./AsyncResolutionRequiredError";
+export { CircularDependencyError } from "./CircularDependencyError";
+export { ClassDependenciesMismatchError } from "./ClassDependenciesMismatchError";
+export { DiError } from "./DiError";
+export { InvalidProviderError } from "./InvalidProviderError";
+export { ModuleEncapsulationError } from "./ModuleEncapsulationError";
+export { ModuleOwnedProviderConflictError } from "./ModuleOwnedProviderConflictError";
+export { NamedDependencyNotFoundError } from "./NamedDependencyNotFoundError";
+export { OptionsValidationError } from "./OptionsValidationError";
+export { ProviderNotFoundError } from "./ProviderNotFoundError";
+export { ScopeDisposedError } from "./ScopeDisposedError";
+export { ScopedServiceFromRootError } from "./ScopedServiceFromRootError";
+export { ServiceValidationError } from "./ServiceValidationError";

package/core/di/extensions/activator.ts

@@ -0,0 +1,39 @@
+import { isKeyedDependency, type KeyedDependency } from "../provider";
+import type { Class, Token } from "../token";
+import type { ServiceResolver } from "../types";
+
+/** A DI dependency accepted by {@link createInstance}: a plain token or a keyed one. */
+export type ActivatorDependency<T = unknown> = Token<T> | KeyedDependency<T>;
+
+/**
+ * Reflection-free analog of .NET `ActivatorUtilities.CreateInstance`: resolves
+ * the listed DI dependencies from `resolver` and constructs `useClass` with them,
+ * followed by the explicit runtime arguments.
+ *
+ * Convention (DI deps first, runtime args last):
+ *
+ * ```ts
+ * class ReportJob {
+ *   constructor(private readonly db: Db, private readonly title: string) {}
+ * }
+ * const job = createInstance(resolver, ReportJob, [DB], "Q3 revenue");
+ * ```
+ *
+ * The resolver's scope is honored: scoped dependencies come from the active
+ * scope, so call it with the scope's resolver inside a request, not the root.
+ * Unlike the codegen-based auto deps, the dependency list is explicit, which
+ * keeps the design free of runtime reflection while mixing DI and manual args.
+ */
+export function createInstance<T>(
+  resolver: ServiceResolver,
+  useClass: Class<T>,
+  deps: readonly ActivatorDependency[] = [],
+  ...runtimeArgs: unknown[]
+): T {
+  const resolved = new Array<unknown>(deps.length);
+  for (let index = 0; index < deps.length; index += 1) {
+    const dep = deps[index] as ActivatorDependency;
+    resolved[index] = isKeyedDependency(dep) ? resolver.resolveKeyed(dep.token, dep.key) : resolver.resolve(dep);
+  }
+  return new useClass(...resolved, ...runtimeArgs);
+}

package/core/di/extensions/application.ts

@@ -0,0 +1,117 @@
+import type { Token } from "../token";
+import { resolveHostedServices, validateHostedServicePlan, type HostedService } from "./hosted-service";
+import { validateOptionsOnStart } from "./options";
+
+interface ApplicationHost {
+  resolveAll<T>(token: Token<T>): readonly T[];
+  dispose(): Promise<void>;
+}
+
+export interface RunApplicationOptions {
+  /** Signals that trigger graceful shutdown. Default: SIGINT, SIGTERM. */
+  readonly signals?: readonly NodeJS.Signals[];
+}
+
+/**
+ * Lifecycle wrapper over the DI container:
+ * - `Application.start` resolves and starts all hosted services in registration order;
+ * - `stop` stops them in reverse order and disposes the container.
+ *
+ * Fault tolerance: a failed start rolls back already-started services; a failed
+ * stop continues stopping the rest and reports all errors at the end.
+ */
+export class Application {
+  private stopPromise: Promise<void> | undefined;
+
+  private constructor(
+    private readonly host: ApplicationHost,
+    private readonly hosted: readonly HostedService[],
+  ) {}
+
+  public static async start(host: ApplicationHost): Promise<Application> {
+    const started: HostedService[] = [];
+    let hosted: readonly HostedService[];
+    try {
+      // Validate before starting services; all startup failures share cleanup
+      // so disposal errors cannot replace the original failure.
+      validateOptionsOnStart(host);
+      hosted = resolveHostedServices(host);
+      const validation = validateHostedServicePlan(hosted);
+      if (validation) await validation;
+      for (let index = 0; index < hosted.length; index += 1) {
+        const service = hosted[index] as HostedService;
+        await service.start();
+        started.push(service);
+      }
+    } catch (error) {
+      await stopInReverse(started, []);
+      try {
+        await host.dispose();
+      } catch {
+        // Startup's construction/start failure remains the primary error.
+      }
+      throw error;
+    }
+    return new Application(host, hosted);
+  }
+
+  public stop(): Promise<void> {
+    if (!this.stopPromise) {
+      // Publish before invoking user cleanup, including a reentrant stop().
+      this.stopPromise = Promise.resolve().then(() => this.stopCore());
+    }
+    return this.stopPromise;
+  }
+
+  private async stopCore(): Promise<void> {
+    const errors: unknown[] = [];
+    await stopInReverse(this.hosted, errors);
+    try {
+      await this.host.dispose();
+    } catch (error) {
+      errors.push(error);
+    }
+
+    if (errors.length === 1) {
+      throw errors[0];
+    }
+    if (errors.length > 1) {
+      throw new AggregateError(errors, "Application shutdown finished with errors.");
+    }
+  }
+}
+
+/** Starts the application and blocks until a shutdown signal, then stops gracefully. */
+export async function runApplication(host: ApplicationHost, options?: RunApplicationOptions): Promise<void> {
+  const app = await Application.start(host);
+  const signals = options?.signals ?? ["SIGINT", "SIGTERM"];
+
+  const handlers: Array<{ readonly signal: NodeJS.Signals; readonly handler: () => void }> = [];
+  try {
+    await new Promise<void>((resolve) => {
+      for (let index = 0; index < signals.length; index += 1) {
+        const signal = signals[index] as NodeJS.Signals;
+        const handler = (): void => resolve();
+        handlers.push({ signal, handler });
+        process.once(signal, handler);
+      }
+    });
+  } finally {
+    for (let index = 0; index < handlers.length; index += 1) {
+      const entry = handlers[index]!;
+      process.off(entry.signal, entry.handler);
+    }
+  }
+
+  await app.stop();
+}
+
+async function stopInReverse(services: readonly HostedService[], errors: unknown[]): Promise<void> {
+  for (let index = services.length - 1; index >= 0; index -= 1) {
+    try {
+      await (services[index] as HostedService).stop();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+}

package/core/di/extensions/hosted-service.ts

@@ -0,0 +1,124 @@
+import type { ServiceCollection } from "../ServiceCollection";
+import { createToken } from "../token";
+import { prepareHostedServicePlan } from "../internal/HostedServicePlan";
+// Framework-only composition hook; not part of the DI root barrel.
+export { registerHostedServiceWrapper, type HostedServicePlanAdmission } from "../internal/HostedServicePlan";
+
+/**
+ * Pure, repeatable configuration checks, once by identity per plan version.
+ * Initial admission precedes every hook/start; a retry replacement validates
+ * the full new plan again, which may include already-started services.
+ */
+export interface HostedServicePlanValidator {
+  validate(services: readonly HostedService[], signal?: AbortSignal): void | Promise<void>;
+}
+
+export interface HostedService {
+  /** Shared validators see real service identities, including inside supervised wrappers. */
+  readonly planValidator?: HostedServicePlanValidator;
+  start(signal?: AbortSignal): void | Promise<void>;
+  stop(): void | Promise<void>;
+  /**
+   * Startup phase (Spring SmartLifecycle): lower phases start first, stop
+   * last. Services without a phase belong to phase 0. The kernel starts
+   * phases in ascending order and stops everything in reverse start order.
+   */
+  readonly phase?: number;
+}
+
+export const HOSTED_SERVICE = createToken<HostedService>("IHostedService");
+
+interface HostedServiceResolver {
+  resolveAll(token: typeof HOSTED_SERVICE): readonly HostedService[];
+}
+
+interface HostedServiceRun {
+  readonly started: HostedService[];
+  starting?: Promise<void>;
+  stopping?: Promise<void>;
+  stopped: boolean;
+}
+
+// A resolver owns one helper-managed run. Retaining its actual instances keeps
+// transient registrations safe without changing their public DI lifetime.
+const hostedRuns = new WeakMap<HostedServiceResolver, HostedServiceRun>();
+
+/**
+ * Hosted services in registration order, each instance once. Several
+ * registrations may legitimately resolve one singleton (for example the shared
+ * owned-store admission plan of every `ownedStore` context); it is one service
+ * and starts/stops once. Distinct supervised wrappers that materialize one
+ * concrete service are still rejected by plan validation.
+ */
+export function resolveHostedServices(services: HostedServiceResolver): readonly HostedService[] {
+  return [...new Set(services.resolveAll(HOSTED_SERVICE))];
+}
+
+/** Shared by the kernel and the lightweight host; validators never start services. */
+export function validateHostedServicePlan(services: readonly HostedService[], signal?: AbortSignal): void | Promise<void> {
+  return prepareHostedServicePlan(services, signal);
+}
+
+export async function startHostedServices(services: HostedServiceResolver): Promise<void> {
+  const previous = hostedRuns.get(services);
+  if (previous?.stopping && !previous.stopped) {
+    await previous.stopping;
+    return startHostedServices(services);
+  }
+  if (previous?.starting && !previous.stopped) return previous.starting;
+
+  const run: HostedServiceRun = { started: [], stopped: false };
+  hostedRuns.set(services, run);
+  // Publish the run before entering user callbacks, including a concurrent stop.
+  run.starting = Promise.resolve().then(async () => {
+    const hosted = resolveHostedServices(services);
+    const validation = validateHostedServicePlan(hosted);
+    if (validation) await validation;
+    for (const service of hosted) {
+      // A failed start may already own resources that the paired stop must release.
+      run.started.push(service);
+      await service.start();
+    }
+  });
+  return run.starting;
+}
+
+export async function stopHostedServices(services: HostedServiceResolver): Promise<void> {
+  let run = hostedRuns.get(services);
+  if (!run) {
+    run = { started: [], stopped: false };
+    hostedRuns.set(services, run);
+  }
+  if (!run.stopping) {
+    const current = run;
+    current.stopping = Promise.resolve().then(async () => {
+      if (current.starting) {
+        // Startup reports its own error; stop also cleans up a partially started service.
+        await current.starting.catch(() => undefined);
+      } else {
+        // Keep the existing standalone stop helper for manually started services.
+        current.started.push(...resolveHostedServices(services));
+      }
+      const errors: unknown[] = [];
+      for (let index = current.started.length - 1; index >= 0; index -= 1) {
+        try {
+          await (current.started[index] as HostedService).stop();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      current.started.length = 0;
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) throw new AggregateError(errors, "Hosted service shutdown finished with errors.");
+    }).finally(() => { current.stopped = true; });
+  }
+  return run.stopping;
+}
+
+export function addHostedService(services: ServiceCollection, factory: () => HostedService): void {
+  services.addTransient({
+    provide: HOSTED_SERVICE,
+    useFactory: factory,
+    deps: [],
+  });
+}

package/core/di/extensions/index.ts

@@ -0,0 +1,23 @@
+export { createInstance, type ActivatorDependency } from "./activator";
+export { Application, runApplication, type RunApplicationOptions } from "./application";
+export { addHostedService, HOSTED_SERVICE, startHostedServices, stopHostedServices, type HostedService, type HostedServicePlanValidator } from "./hosted-service";
+export { SERVICE_PROVIDER } from "./service-provider-token";
+export {
+  addOptions,
+  addValidatedOptions,
+  createOptionsToken,
+  OPTIONS_STARTUP_VALIDATOR,
+  validateOptionsOnStart,
+  type Options,
+  type ValidatedOptionsConfig,
+} from "./options";
+export {
+  addReloadableOptions,
+  createOptionsMonitorToken,
+  createOptionsSnapshotToken,
+  createReloadableOptionsTokens,
+  type OptionsChangeSubscription,
+  type OptionsMonitor,
+  type OptionsSnapshot,
+  type ReloadableOptionsTokens,
+} from "./options-reloadable";