bazis 0.96.1

package/core/di/internal/disposal.ts

@@ -0,0 +1,58 @@
+const symbolDispose = Symbol.dispose as symbol | undefined;
+const symbolAsyncDispose = Symbol.asyncDispose as symbol | undefined;
+
+export async function disposeTracked(disposables: readonly unknown[]): Promise<void> {
+  const errors: unknown[] = [];
+  for (let index = disposables.length - 1; index >= 0; index -= 1) {
+    const instance = disposables[index];
+    try {
+      await disposeOne(instance);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "Service disposal finished with errors.");
+  }
+}
+
+async function disposeOne(instance: unknown): Promise<void> {
+  if (!instance || (typeof instance !== "object" && typeof instance !== "function")) {
+    return;
+  }
+
+  const value = instance as Record<PropertyKey, unknown>;
+
+  const asyncBySymbol =
+    symbolAsyncDispose && typeof value[symbolAsyncDispose] === "function"
+      ? (value[symbolAsyncDispose] as () => Promise<void>)
+      : undefined;
+  if (asyncBySymbol) {
+    await asyncBySymbol.call(instance);
+    return;
+  }
+
+  const asyncByName =
+    typeof value.disposeAsync === "function" ? (value.disposeAsync as () => Promise<void>) : undefined;
+  if (asyncByName) {
+    await asyncByName.call(instance);
+    return;
+  }
+
+  const syncBySymbol =
+    symbolDispose && typeof value[symbolDispose] === "function"
+      ? (value[symbolDispose] as () => void)
+      : undefined;
+  if (syncBySymbol) {
+    syncBySymbol.call(instance);
+    return;
+  }
+
+  const syncByName = typeof value.dispose === "function" ? (value.dispose as () => unknown) : undefined;
+  if (syncByName) {
+    await Promise.resolve(syncByName.call(instance));
+  }
+}

package/core/di/internal/providerDeps.ts

@@ -0,0 +1,26 @@
+import { getClassDeps } from "./classDeps";
+import { getGeneratedClassDeps } from "../module/autoDeps";
+import { isClassProvider, isValueProvider, type ClassProvider, type Provider, type ProviderDependencyList } from "../provider";
+
+/** Constructor binding has one precedence rule in validation and activation. */
+export function getConstructorDeps(provider: ClassProvider<unknown, ProviderDependencyList>): ProviderDependencyList {
+  return provider.deps ?? getClassDeps(provider.useClass) ?? getGeneratedClassDeps(provider.useClass) ?? [];
+}
+
+export function getProviderDeps(provider: Provider<unknown>): ProviderDependencyList {
+  if (isValueProvider(provider)) return [];
+  if (!isClassProvider(provider)) return provider.deps;
+  const deps = getConstructorDeps(provider);
+  return provider.activation ? [...deps, ...provider.activation.deps] : deps;
+}
+
+/** Preserve the constructor/wrapper boundary when rebinding named deps. */
+export function withProviderDeps(provider: Provider<unknown>, deps: ProviderDependencyList): Provider<unknown> {
+  if (!isClassProvider(provider) || !provider.activation) return { ...provider, deps } as Provider<unknown>;
+  const count = getConstructorDeps(provider).length;
+  return {
+    ...provider,
+    deps: deps.slice(0, count),
+    activation: { ...provider.activation, deps: deps.slice(count) },
+  };
+}

package/core/di/module/DI.ts

@@ -0,0 +1,146 @@
+import { setClassDeps } from "../internal/classDeps";
+import type { Token } from "../token";
+import type { ServiceKey, ServiceResolver } from "../types";
+import type {
+  AsyncFactoryProvider,
+  ClassProvider,
+  FactoryProvider,
+  Provider,
+  ProviderDefinition,
+  ProviderDependencyList,
+  ResolvedDeps,
+  ValueProvider,
+  KeyedDependency,
+} from "../provider";
+import { ProviderDefinition as ProviderDefinitionClass, keyedDependency } from "../provider";
+
+export class DI {
+  /** Marks a provider result as lifecycle-owned so the container will not dispose it. */
+  public static externallyOwned<T, D extends ProviderDependencyList>(provider: FactoryProvider<T, D>): FactoryProvider<T, D>;
+  public static externallyOwned<T, D extends ProviderDependencyList>(provider: AsyncFactoryProvider<T, D>): AsyncFactoryProvider<T, D>;
+  public static externallyOwned<T, D extends ProviderDependencyList>(provider: ClassProvider<T, D>): ClassProvider<T, D>;
+  public static externallyOwned<T>(provider: ValueProvider<T>): ValueProvider<T>;
+  public static externallyOwned(provider: Provider<unknown>): Provider<unknown> {
+    return { ...provider, ownership: "external" } as Provider<unknown>;
+  }
+
+  public static singleton<T>(provider: Provider<T>): ProviderDefinition<T> {
+    return new ProviderDefinitionClass(provider, "singleton");
+  }
+
+  public static scoped<T>(provider: Provider<T>): ProviderDefinition<T> {
+    return new ProviderDefinitionClass(provider, "scoped");
+  }
+
+  public static transient<T>(provider: Provider<T>): ProviderDefinition<T> {
+    return new ProviderDefinitionClass(provider, "transient");
+  }
+
+  public static keyedSingleton<T>(key: ServiceKey, provider: Provider<T>): ProviderDefinition<T> {
+    return new ProviderDefinitionClass(provider, "singleton", key);
+  }
+
+  public static keyedScoped<T>(key: ServiceKey, provider: Provider<T>): ProviderDefinition<T> {
+    return new ProviderDefinitionClass(provider, "scoped", key);
+  }
+
+  public static keyedTransient<T>(key: ServiceKey, provider: Provider<T>): ProviderDefinition<T> {
+    return new ProviderDefinitionClass(provider, "transient", key);
+  }
+
+  public static classProvider<T, D extends ProviderDependencyList = []>(
+    provide: Token<T>,
+    useClass: ClassProvider<T, D>["useClass"],
+    deps?: D,
+  ): ClassProvider<T, D> {
+    return {
+      provide,
+      useClass,
+      deps,
+    };
+  }
+
+  public static factoryProvider<T, D extends ProviderDependencyList>(
+    provide: Token<T>,
+    deps: D,
+    useFactory: (...args: ResolvedDeps<D>) => T,
+  ): FactoryProvider<T, D> {
+    return {
+      provide,
+      deps,
+      useFactory,
+    };
+  }
+
+  public static factoryProviderWithResolver<T, D extends ProviderDependencyList>(
+    provide: Token<T>,
+    deps: D,
+    useFactory: (resolver: ServiceResolver, ...args: ResolvedDeps<D>) => T,
+  ): FactoryProvider<T, D> {
+    return {
+      provide,
+      deps,
+      useFactory,
+      withResolver: true,
+    };
+  }
+
+  public static asyncFactoryProvider<T, D extends ProviderDependencyList>(
+    provide: Token<T>,
+    deps: D,
+    useAsyncFactory: (...args: ResolvedDeps<D>) => Promise<T>,
+  ): AsyncFactoryProvider<T, D> {
+    return {
+      provide,
+      deps,
+      useAsyncFactory,
+    };
+  }
+
+  public static asyncFactoryProviderWithResolver<T, D extends ProviderDependencyList>(
+    provide: Token<T>,
+    deps: D,
+    useAsyncFactory: (resolver: ServiceResolver, ...args: ResolvedDeps<D>) => Promise<T>,
+  ): AsyncFactoryProvider<T, D> {
+    return {
+      provide,
+      deps,
+      useAsyncFactory,
+      withResolver: true,
+    };
+  }
+
+  public static valueProvider<T>(provide: Token<T>, useValue: T): ValueProvider<T> {
+    return {
+      provide,
+      useValue,
+    };
+  }
+
+  public static keyed<T>(token: Token<T>, key: ServiceKey): KeyedDependency<T> {
+    return keyedDependency(token, key);
+  }
+
+  public static bindDeps<TCtorArgs extends unknown[], TInstance, D extends ProviderDependencyList>(
+    useClass: CtorClass<TCtorArgs, TInstance>,
+    ...deps: DepsCompatibleWithCtor<TCtorArgs, D>
+  ): CtorClass<TCtorArgs, TInstance> {
+    setClassDeps(useClass, deps);
+    return useClass;
+  }
+
+  public static injectFor<TCtorArgs extends unknown[], TInstance, D extends ProviderDependencyList>(
+    useClass: CtorClass<TCtorArgs, TInstance>,
+    ...deps: DepsCompatibleWithCtor<TCtorArgs, D>
+  ): D {
+    setClassDeps(useClass, deps);
+    return deps as D;
+  }
+}
+
+type CtorClass<TArgs extends unknown[], TInstance> = new (...args: TArgs) => TInstance;
+
+type DepsCompatibleWithCtor<TCtorArgs extends unknown[], D extends ProviderDependencyList> =
+  ResolvedDeps<D> extends Readonly<TCtorArgs>
+    ? D
+    : never;

package/core/di/module/Global.ts

@@ -0,0 +1,25 @@
+import type { BazisModule, BazisModuleRef } from "./types";
+
+/**
+ * Marks a module as global (NestJS `@Global()`): its exports are visible to every
+ * module without an explicit import. Apply above `@Module`:
+ *
+ * ```ts
+ * @Global()
+ * @Module({ providers: [...], exports: [DATABASE_PROVIDER] })
+ * class OrmRootModule {}
+ * ```
+ */
+export function Global() {
+  return (target: abstract new (...args: never) => unknown, _context: ClassDecoratorContext): void => {
+    markGlobal(target as BazisModule);
+  };
+}
+
+/** Marks a dynamically created module (class or plain metadata) as global, e.g. connection-mode `ormModule({ provider })`. */
+export function markGlobal<T extends BazisModuleRef>(module: T): T {
+  if (module.global !== true) {
+    Object.assign(module, { global: true });
+  }
+  return module;
+}

package/core/di/module/Module.ts

@@ -0,0 +1,44 @@
+import type { BazisModuleMetadata } from "./types";
+
+const BAZIS_MODULE_MARKER = Symbol.for("bazis/core/di/module");
+
+/**
+ * Registers module metadata on the decorated class (NestJS-style).
+ *
+ * ```ts
+ * @Module({
+ *   imports: [ormModule({ context: UsersDbContext, entities: [User] })],
+ *   controllers: [UsersController],
+ *   providers: [scoped(IUserStore, UserService)],
+ *   exports: [IUserStore],
+ * })
+ * export class UsersModule {}
+ * ```
+ *
+ * Combine with {@link Global} for infrastructure modules:
+ *
+ * ```ts
+ * @Global()
+ * @Module({ providers: [...], exports: [DATABASE_PROVIDER] })
+ * export class OrmRootModule {}
+ * ```
+ *
+ * Static modules: `@Module` on the exported class (`OpenSearchLoggingModule`).
+ * Inline overrides: factory `openSearchLoggingModule(config)` (see `@/core/infra/opensearch`).
+ */
+export function Module(metadata: BazisModuleMetadata) {
+  return (target: abstract new (...args: never) => unknown, _context: ClassDecoratorContext): void => {
+    Object.assign(target, metadata);
+    Object.defineProperty(target, BAZIS_MODULE_MARKER, {
+      configurable: false,
+      enumerable: false,
+      value: true,
+      writable: false,
+    });
+  };
+}
+
+/** @internal Distinguishes decorated module classes from profile factory functions. */
+export function isBazisModuleClass(value: unknown): value is abstract new (...args: never) => unknown {
+  return typeof value === "function" && Reflect.get(value, BAZIS_MODULE_MARKER) === true;
+}

package/core/di/module/ModuleRegistrar.ts

@@ -0,0 +1,69 @@
+import { ServiceCollection } from "../ServiceCollection";
+import type { Provider, ProviderDefinition } from "../provider";
+import { DI } from "./DI";
+import type { Token } from "../token";
+import type { ProviderLifetime } from "../provider";
+import type { ServiceKey } from "../types";
+import type { OpenGenericTokenFamily } from "../token";
+import type { DiRegistrar } from "./types";
+
+export class ModuleRegistrar implements DiRegistrar {
+  public constructor(private readonly collection: ServiceCollection) {}
+
+  public singleton<T>(provider: Provider<T>): void {
+    this.collection.add(DI.singleton(provider));
+  }
+
+  public scoped<T>(provider: Provider<T>): void {
+    this.collection.add(DI.scoped(provider));
+  }
+
+  public transient<T>(provider: Provider<T>): void {
+    this.collection.add(DI.transient(provider));
+  }
+
+  public keyedSingleton<T>(key: ServiceKey, provider: Provider<T>): void {
+    this.collection.add(DI.keyedSingleton(key, provider));
+  }
+
+  public keyedScoped<T>(key: ServiceKey, provider: Provider<T>): void {
+    this.collection.add(DI.keyedScoped(key, provider));
+  }
+
+  public keyedTransient<T>(key: ServiceKey, provider: Provider<T>): void {
+    this.collection.add(DI.keyedTransient(key, provider));
+  }
+
+  public trySingleton<T>(provider: Provider<T>): boolean {
+    return this.collection.tryAddSingleton(provider);
+  }
+
+  public tryScoped<T>(provider: Provider<T>): boolean {
+    return this.collection.tryAddScoped(provider);
+  }
+
+  public tryTransient<T>(provider: Provider<T>): boolean {
+    return this.collection.tryAddTransient(provider);
+  }
+
+  public tryAddEnumerable(definition: ProviderDefinition): boolean {
+    return this.collection.tryAddEnumerable(definition);
+  }
+
+  public replace<T>(token: Token<T>, provider: Provider<T>, lifetime: ProviderLifetime, key?: ServiceKey): void {
+    this.collection.replace(token, provider, lifetime, key);
+  }
+
+  public remove(token: Token<unknown>, key?: ServiceKey): number {
+    return this.collection.remove(token, key);
+  }
+
+  public addOpenGeneric(
+    family: OpenGenericTokenFamily<unknown, unknown>,
+    lifetime: ProviderLifetime,
+    providerFactory: (argument: Token<unknown>) => Provider<unknown>,
+    key?: ServiceKey,
+  ): void {
+    this.collection.addOpenGeneric(family, lifetime, providerFactory, key);
+  }
+}

package/core/di/module/autoDeps.ts

@@ -0,0 +1,39 @@
+import { lazyDependency, namedDependency, type ProviderDependencyList } from "../provider";
+import type { Class } from "../token";
+
+const LAZY_PREFIX = "lazy:";
+// These registrations live for the process lifetime just like their
+// constructors. A Map, rather than a WeakMap, lets the generated-runtime
+// owner take an exact rollback snapshot before publishing a target slice.
+export type GeneratedClassDependency = string | ProviderDependencyList[number];
+let targetClassDeps = new Map<Class<unknown>, readonly GeneratedClassDependency[]>();
+
+/** Project-owned target runtimes bind inferred dependencies by constructor identity. */
+export function registerGeneratedClassDeps(target: Class<unknown>, deps: readonly GeneratedClassDependency[]): void {
+  targetClassDeps.set(target, deps);
+}
+
+export function getGeneratedClassDeps(useClass: Class<unknown>): ProviderDependencyList | undefined {
+  // Names are not class identities: package consumers may use the same names
+  // as the application that generated the framework's compatibility files.
+  const dependencies = targetClassDeps.get(useClass);
+  if (dependencies === undefined) {
+    return undefined;
+  }
+  return dependencies.map((dependency) =>
+    typeof dependency !== "string" ? dependency
+      : dependency.startsWith(LAZY_PREFIX)
+        ? lazyDependency(namedDependency(dependency.slice(LAZY_PREFIX.length)))
+        : namedDependency(dependency),
+  );
+}
+
+/** Internal generated-runtime transaction support. */
+export function snapshotGeneratedClassDeps(): typeof targetClassDeps {
+  return new Map(targetClassDeps);
+}
+
+/** Internal generated-runtime transaction support. */
+export function restoreGeneratedClassDeps(snapshot: ReturnType<typeof snapshotGeneratedClassDeps>): void {
+  targetClassDeps = snapshot;
+}

package/core/di/module/classProviderHooks.ts

@@ -0,0 +1,66 @@
+import { createToken, type Class, type Token } from "../token";
+import { ProviderDefinition, isClassProvider, isValueProvider, type ProviderDependencyList } from "../provider";
+
+export type ClassProviderLifetime = "singleton" | "scoped" | "transient";
+
+export interface ClassProviderRegistration {
+  readonly lifetime: ClassProviderLifetime;
+  readonly provide: Token<unknown>;
+  readonly useClass: Class<unknown>;
+  readonly deps: ProviderDependencyList | undefined;
+}
+
+export type ClassProviderHook = (request: ClassProviderRegistration) => ProviderDefinition | undefined;
+
+/** Container-local build extension. Register an unkeyed singleton value, not a runtime factory. */
+export const CLASS_PROVIDER_HOOK = createToken<ClassProviderHook>("ClassProviderHook");
+
+export function collectClassProviderHooks(definitions: readonly ProviderDefinition[]): readonly ClassProviderHook[] {
+  const hooks = new Set<ClassProviderHook>();
+  for (const definition of definitions) {
+    if (definition.provider.provide !== CLASS_PROVIDER_HOOK) continue;
+    if (definition.lifetime !== "singleton" || definition.key !== undefined
+      || !isValueProvider(definition.provider) || typeof definition.provider.useValue !== "function") {
+      throw new TypeError("ClassProviderHook requires an unkeyed singleton value provider.");
+    }
+    hooks.add(definition.provider.useValue as ClassProviderHook);
+  }
+  return [...hooks];
+}
+
+export function applyClassProviderHooks(
+  request: ClassProviderRegistration,
+  hooks: readonly ClassProviderHook[],
+): ProviderDefinition | undefined {
+  for (let index = 0; index < hooks.length; index += 1) {
+    const result = hooks[index]!(request);
+    if (result !== undefined) {
+      return result;
+    }
+  }
+  return undefined;
+}
+
+/** Applies hooks when a definition enters a collection, not only when shortcut syntax created it. */
+export function applyClassProviderHooksToDefinition(
+  definition: ProviderDefinition,
+  hooks: readonly ClassProviderHook[],
+): ProviderDefinition {
+  if (!isClassProvider(definition.provider) || definition.provider.activation !== undefined) {
+    return definition;
+  }
+  const hooked = applyClassProviderHooks({
+    lifetime: definition.lifetime,
+    provide: definition.provider.provide,
+    useClass: definition.provider.useClass,
+    deps: definition.provider.deps,
+  }, hooks);
+  if (hooked === undefined) {
+    return definition;
+  }
+  // A hook changes the implementation, not the keyed-registration identity.
+  return new ProviderDefinition(
+    { ...hooked.provider, ...(definition.provider.ownership ? { ownership: definition.provider.ownership } : {}) },
+    hooked.lifetime, definition.key ?? hooked.key,
+  );
+}

package/core/di/module/collectModuleConfigs.ts

@@ -0,0 +1,57 @@
+import { expandModuleMetadata } from "./moduleExtensions";
+import type { ModuleConfig, BazisModuleRef } from "./types";
+
+function appendConfig(
+  config: ModuleConfig | readonly ModuleConfig[] | undefined,
+  out: ModuleConfig[],
+  seen: Set<ModuleConfig>,
+): void {
+  if (config === undefined) {
+    return;
+  }
+  const configs = Array.isArray(config) ? config : [config];
+  for (let index = 0; index < configs.length; index += 1) {
+    const item = configs[index] as ModuleConfig;
+    if (!seen.has(item)) {
+      seen.add(item);
+      out.push(item);
+    }
+  }
+}
+
+/**
+ * Collects module-owned configs from a module tree. Used by `runApp` for
+ * fail-fast validation before the DI container is created.
+ */
+export function collectModuleConfigs(roots: readonly BazisModuleRef[]): readonly ModuleConfig[] {
+  const loaded = new Set<BazisModuleRef>();
+  const seenConfigs = new Set<ModuleConfig>();
+  const configs: ModuleConfig[] = [];
+
+  const visit = (moduleRef: BazisModuleRef): void => {
+    if (loaded.has(moduleRef)) {
+      return;
+    }
+    loaded.add(moduleRef);
+
+    appendConfig(moduleRef.config, configs, seenConfigs);
+
+    const imports = moduleRef.imports;
+    if (imports) {
+      for (let index = 0; index < imports.length; index += 1) {
+        visit(imports[index] as BazisModuleRef);
+      }
+    }
+
+    const expanded = expandModuleMetadata(moduleRef);
+    for (let index = 0; index < expanded.length; index += 1) {
+      visit(expanded[index] as BazisModuleRef);
+    }
+  };
+
+  for (let index = 0; index < roots.length; index += 1) {
+    visit(roots[index] as BazisModuleRef);
+  }
+
+  return configs;
+}

package/core/di/module/collectModuleControllers.ts

@@ -0,0 +1,53 @@
+import type { Class } from "../token";
+import type { BazisModuleRef } from "./types";
+
+/**
+ * Collects controller classes from the module tree (the module itself plus `imports`,
+ * recursively). Duplicates by class reference are dropped.
+ */
+export function collectModuleControllers(
+  roots: readonly BazisModuleRef[],
+  extraControllers?: readonly Class<object>[],
+): Class<object>[] {
+  const seen = new Set<Class<object>>();
+  const result: Class<object>[] = [];
+
+  const visit = (moduleRef: BazisModuleRef, loaded: Set<BazisModuleRef>): void => {
+    if (loaded.has(moduleRef)) {
+      return;
+    }
+    loaded.add(moduleRef);
+
+    const imports = moduleRef.imports;
+    if (imports) {
+      for (let index = 0; index < imports.length; index += 1) {
+        visit(imports[index] as BazisModuleRef, loaded);
+      }
+    }
+
+    const controllers = moduleRef.controllers;
+    if (controllers) {
+      for (let index = 0; index < controllers.length; index += 1) {
+        const controller = controllers[index] as Class<object>;
+        if (!seen.has(controller)) {
+          seen.add(controller);
+          result.push(controller);
+        }
+      }
+    }
+  };
+
+  for (let index = 0; index < roots.length; index += 1) {
+    visit(roots[index] as BazisModuleRef, new Set());
+  }
+  if (extraControllers) {
+    for (let index = 0; index < extraControllers.length; index += 1) {
+      const controller = extraControllers[index] as Class<object>;
+      if (!seen.has(controller)) {
+        seen.add(controller);
+        result.push(controller);
+      }
+    }
+  }
+  return result;
+}

package/core/di/module/collectModuleUiProfiles.ts

@@ -0,0 +1,53 @@
+import { expandModuleMetadata } from "./moduleExtensions";
+import type { BazisModuleRef } from "./types";
+
+function appendProfiles(value: readonly unknown[] | undefined, out: unknown[], seen: Set<unknown>): void {
+  if (value === undefined) {
+    return;
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const profile = value[index];
+    if (!seen.has(profile)) {
+      seen.add(profile);
+      out.push(profile);
+    }
+  }
+}
+
+/**
+ * Collects opaque `uiProfiles` declarations from a module tree. The DI core
+ * intentionally does not interpret `@UiProfile`; the application composition
+ * layer resolves the references against HTTP/OpenAPI metadata.
+ */
+export function collectModuleUiProfiles(roots: readonly BazisModuleRef[]): readonly unknown[] {
+  const loaded = new Set<BazisModuleRef>();
+  const seen = new Set<unknown>();
+  const profiles: unknown[] = [];
+
+  const visit = (moduleRef: BazisModuleRef): void => {
+    if (loaded.has(moduleRef)) {
+      return;
+    }
+    loaded.add(moduleRef);
+
+    appendProfiles(moduleRef.uiProfiles, profiles, seen);
+
+    const imports = moduleRef.imports;
+    if (imports) {
+      for (let index = 0; index < imports.length; index += 1) {
+        visit(imports[index] as BazisModuleRef);
+      }
+    }
+
+    const expanded = expandModuleMetadata(moduleRef);
+    for (let index = 0; index < expanded.length; index += 1) {
+      visit(expanded[index] as BazisModuleRef);
+    }
+  };
+
+  for (let index = 0; index < roots.length; index += 1) {
+    visit(roots[index] as BazisModuleRef);
+  }
+
+  return Object.freeze(profiles);
+}