bazis 0.96.1

package/core/di/module/encapsulationHooks.ts

@@ -0,0 +1,36 @@
+import type { Token } from "../token";
+
+export interface NamedDependencyEncapsulationContext {
+  readonly depName: string;
+  readonly consumer: string;
+  readonly moduleName: string;
+  readonly visible: ReadonlySet<Token<unknown>>;
+  readonly familiesVisible: ReadonlySet<symbol>;
+}
+
+/**
+ * Return `true` when the named dependency is allowed despite encapsulation rules.
+ * Return `undefined` to fall through to default DI validation.
+ */
+export type NamedDependencyEncapsulationHook = (
+  context: NamedDependencyEncapsulationContext,
+) => boolean | undefined;
+
+const namedDependencyHooks: NamedDependencyEncapsulationHook[] = [];
+
+/** Infrastructure extensions (ORM open generics, …) plug in named-dep rules here. */
+export function registerNamedDependencyEncapsulationHook(hook: NamedDependencyEncapsulationHook): void {
+  namedDependencyHooks.push(hook);
+}
+
+export function applyNamedDependencyEncapsulationHooks(
+  context: NamedDependencyEncapsulationContext,
+): boolean {
+  for (let index = 0; index < namedDependencyHooks.length; index += 1) {
+    const result = namedDependencyHooks[index]!(context);
+    if (result === true) {
+      return true;
+    }
+  }
+  return false;
+}

package/core/di/module/generatedProviderAttachments.ts

@@ -0,0 +1,102 @@
+import type { Class } from "../token";
+
+/** Package-internal capability used only as an exact-class generated metadata key. */
+export interface GeneratedProviderAttachmentChannel<T> {
+  readonly kind: "generatedProviderAttachment";
+  readonly description: string;
+  normalize(target: Class<object>, value: unknown): T;
+  equals?(left: T, right: T): boolean;
+}
+
+export interface GeneratedProviderAttachmentV1 {
+  readonly channel: GeneratedProviderAttachmentChannel<unknown>;
+  readonly target: Class<object>;
+  readonly value: unknown;
+}
+
+type AnyChannel = GeneratedProviderAttachmentChannel<unknown>;
+type Store = Map<AnyChannel, Map<Class<object>, unknown>>;
+type PreparedEntry = Readonly<{ channel: AnyChannel; target: Class<object>; value: unknown }>;
+export interface PreparedGeneratedProviderAttachments { readonly entries: readonly PreparedEntry[]; }
+
+let attachments: Store = new Map();
+
+export function createGeneratedProviderAttachmentChannel<T>(input: Readonly<{
+  description: string;
+  normalize(target: Class<object>, value: unknown): T;
+  equals?(left: T, right: T): boolean;
+}>): GeneratedProviderAttachmentChannel<T> {
+  const description = input.description.trim();
+  if (description.length === 0 || typeof input.normalize !== "function") {
+    throw new TypeError("Generated provider attachment channel is invalid.");
+  }
+  return Object.freeze({
+    kind: "generatedProviderAttachment" as const,
+    description,
+    normalize: input.normalize,
+    equals: input.equals,
+  }) as GeneratedProviderAttachmentChannel<T>;
+}
+
+/** Exact-class query only; intentionally no channel or attachment enumeration API exists. */
+export function getGeneratedProviderAttachment<T>(
+  channel: GeneratedProviderAttachmentChannel<T>,
+  target: Class<object>,
+): T | undefined {
+  return attachments.get(channel as AnyChannel)?.get(target) as T | undefined;
+}
+
+/** @internal Snapshot participates in generated-target atomic commit/rollback. */
+export function snapshotGeneratedProviderAttachments(): Store {
+  return new Map([...attachments].map(([channel, entries]) => [channel, new Map(entries)]));
+}
+
+/** @internal Restores generated attachment state after failed target publication. */
+export function restoreGeneratedProviderAttachments(snapshot: Store): void {
+  attachments = new Map([...snapshot].map(([channel, entries]) => [channel, new Map(entries)]));
+}
+
+/** @internal Validates and publishes a target's complete exact-class attachment slice. */
+/** @internal Validates every attachment before any generated target owner is mutated. */
+export function prepareGeneratedProviderAttachments(
+  entries: readonly GeneratedProviderAttachmentV1[] | undefined,
+): PreparedGeneratedProviderAttachments {
+  if (entries === undefined) return Object.freeze({ entries: Object.freeze([]) });
+  if (!Array.isArray(entries)) throw new TypeError("Generated provider attachments must be an array.");
+  const normalized: readonly PreparedEntry[] = entries.map((entry) => {
+    if (entry === null || typeof entry !== "object" || entry.channel?.kind !== "generatedProviderAttachment"
+      || typeof entry.target !== "function") {
+      throw new TypeError("Generated provider attachment is invalid.");
+    }
+    const channel = entry.channel as AnyChannel;
+    return Object.freeze({ channel, target: entry.target, value: channel.normalize(entry.target, entry.value) });
+  });
+  const own = new Map<AnyChannel, Set<Class<object>>>();
+  for (const entry of normalized) {
+    const targets = own.get(entry.channel) ?? new Set<Class<object>>();
+    if (targets.has(entry.target)) throw new TypeError(`Generated provider attachment is duplicated for ${entry.channel.description}.`);
+    targets.add(entry.target); own.set(entry.channel, targets);
+    const current = attachments.get(entry.channel)?.get(entry.target);
+    if (current !== undefined && !(entry.channel.equals?.(current, entry.value) ?? Object.is(current, entry.value))) {
+      throw new TypeError(`Generated provider attachment diverges for ${entry.channel.description}.`);
+    }
+  }
+  return Object.freeze({ entries: Object.freeze([...normalized]) });
+}
+
+/** @internal Commits a previously validated attachment slice inside the target transaction. */
+export function commitGeneratedProviderAttachments(prepared: PreparedGeneratedProviderAttachments): void {
+  for (const entry of prepared.entries) {
+    let targets = attachments.get(entry.channel);
+    if (targets === undefined) {
+      targets = new Map();
+      attachments.set(entry.channel, targets);
+    }
+    if (!targets.has(entry.target)) targets.set(entry.target, entry.value);
+  }
+}
+
+/** @internal Convenience only for isolated tests; generated target runtime uses prepare + commit. */
+export function registerGeneratedProviderAttachments(entries: readonly GeneratedProviderAttachmentV1[] | undefined): void {
+  commitGeneratedProviderAttachments(prepareGeneratedProviderAttachments(entries));
+}

package/core/di/module/index.ts

@@ -0,0 +1,41 @@
+export { DI } from "./DI";
+export { Global, markGlobal } from "./Global";
+export { Module } from "./Module";
+export type { DiRegistrar, ModuleConfig, ModuleExport, BazisModule, BazisModuleMetadata, BazisModuleRef } from "./types";
+export { ModuleRegistrar } from "./ModuleRegistrar";
+export {
+  registerModuleMetadataExpander,
+  expandModuleMetadata,
+  type ModuleMetadataExpander,
+} from "./moduleExtensions";
+export {
+  createModuleOwnedMetadataChannel,
+  createModuleOwnedProviderChannel,
+  registerModuleOwnedContributionValidator,
+  registerModuleOwnedProviderContributor,
+  type ModuleOwnedContributionChannel,
+  type ModuleOwnedContributionSnapshot,
+  type ModuleOwnedValidationSnapshot,
+  type ModuleOwnedContributionValidator,
+  type ModuleOwnedMetadataChannel,
+  type ModuleOwnedMetadataContribution,
+  type ModuleOwnedProviderActivation,
+  type ModuleOwnedProviderChannel,
+  type ModuleOwnedProviderContribution,
+  type ModuleOwnedProviderContributionContext,
+  type ModuleOwnedProviderContributor,
+} from "./moduleOwnedProviderContributors";
+export { createContainer } from "./createContainer";
+export { collectModuleControllers } from "./collectModuleControllers";
+export { collectModuleConfigs } from "./collectModuleConfigs";
+export { collectModuleUiProfiles } from "./collectModuleUiProfiles";
+export {
+  scoped,
+  singleton,
+  singletonAsyncFactory,
+  singletonAsyncFactoryWithResolver,
+  singletonFactory,
+  singletonFactoryWithResolver,
+  singletonValue,
+  transient,
+} from "./shortcuts";

package/core/di/module/moduleExtensions.ts

@@ -0,0 +1,35 @@
+import type { BazisModuleMetadata, BazisModuleRef } from "./types";
+
+/**
+ * Turns extra `@Module` metadata keys into imported modules.
+ *
+ * The DI core is the foundation layer and must not know about higher modules
+ * (ORM, HTTP, …). To keep ergonomic, declarative keys like `ormBazis` without
+ * inverting that dependency, higher layers register an expander here (via a
+ * side-effect import, like the repository encapsulation hook). At build time
+ * `createContainer` runs every expander over each module's metadata and loads
+ * the returned modules as if they were listed in `imports`.
+ */
+export type ModuleMetadataExpander = (metadata: BazisModuleMetadata) => readonly BazisModuleRef[];
+
+const expanders: ModuleMetadataExpander[] = [];
+
+/** Registers a metadata expander (idempotent per function reference). */
+export function registerModuleMetadataExpander(expander: ModuleMetadataExpander): void {
+  if (!expanders.includes(expander)) {
+    expanders.push(expander);
+  }
+}
+
+/** Collects extra module refs contributed by registered expanders for a module. */
+export function expandModuleMetadata(metadata: BazisModuleMetadata): readonly BazisModuleRef[] {
+  if (expanders.length === 0) {
+    return [];
+  }
+  const extra: BazisModuleRef[] = [];
+  for (let index = 0; index < expanders.length; index += 1) {
+    const expander = expanders[index] as ModuleMetadataExpander;
+    extra.push(...expander(metadata));
+  }
+  return extra;
+}

package/core/di/module/moduleNameBinding.ts

@@ -0,0 +1,136 @@
+import { AmbiguousNamedDependencyError } from "../errors";
+import { getProviderDeps, withProviderDeps } from "../internal/providerDeps";
+import {
+  isLazyDependency,
+  isNamedDependency,
+  lazyDependency,
+  ProviderDefinition,
+} from "../provider";
+import type { ProviderDependencyList } from "../provider";
+import { tokenToDebugName, type Token } from "../token";
+import { computeModuleVisibleTokens, type ModuleGraphRecord } from "./encapsulation";
+
+type Dependency = ProviderDependencyList[number];
+
+/**
+ * Module-scoped resolution of name-based auto dependencies.
+ *
+ * Auto deps are reflection-free, so they bind by *type name*. Resolving those
+ * names globally would force every token's debug name to be unique across the
+ * whole application — a real tax at enterprise scale (two bounded contexts each
+ * with an `IRepository`). Instead we resolve each provider's named dependencies
+ * against the tokens visible to the module that declared it:
+ *
+ * - exactly one visible token with that name -> bind to it (becomes a concrete
+ *   token, so the hot resolve path skips the name lookup entirely);
+ * - several visible tokens share the name -> {@link AmbiguousNamedDependencyError}
+ *   at build time (fail fast), instead of a late surprise on first resolve;
+ * - none visible -> leave the named dependency untouched so the container's
+ *   global index can still resolve it. This preserves the fully-open default
+ *   where a service may depend on a sibling module's token without importing it.
+ *
+ * Runs once at `createContainer`, after encapsulation validation; the resolution
+ * hot path is untouched.
+ */
+export function bindModuleScopedNames(
+  definitions: readonly ProviderDefinition[],
+  recordOf: ReadonlyMap<ProviderDefinition, ModuleGraphRecord>,
+  records: readonly ModuleGraphRecord[],
+): ProviderDefinition[] {
+  const bind = createModuleScopedNameBinder(records);
+  return definitions.map((definition) => {
+    const record = recordOf.get(definition);
+    return record ? bind(definition, record) : definition;
+  });
+}
+
+/** Reuses module visibility for ordinary and later materialized providers. */
+export function createModuleScopedNameBinder(
+  records: readonly ModuleGraphRecord[],
+): (definition: ProviderDefinition, record: ModuleGraphRecord) => ProviderDefinition {
+  const visibleByRecord = computeModuleVisibleTokens(records);
+  const nameMapCache = new Map<ModuleGraphRecord, Map<string, Token<unknown>[]>>();
+
+  const nameMapFor = (record: ModuleGraphRecord): Map<string, Token<unknown>[]> => {
+    const cached = nameMapCache.get(record);
+    if (cached) {
+      return cached;
+    }
+    const map = new Map<string, Token<unknown>[]>();
+    const visible = visibleByRecord.get(record);
+    if (visible) {
+      for (const token of visible) {
+        const name = tokenToDebugName(token);
+        const bucket = map.get(name);
+        if (bucket) {
+          if (!bucket.includes(token)) {
+            bucket.push(token);
+          }
+        } else {
+          map.set(name, [token]);
+        }
+      }
+    }
+    nameMapCache.set(record, map);
+    return map;
+  };
+
+  return (definition, record) => rebindDefinition(definition, nameMapFor(record));
+}
+
+function rebindDefinition(
+  definition: ProviderDefinition,
+  nameMap: Map<string, Token<unknown>[]>,
+): ProviderDefinition {
+  const provider = definition.provider;
+  const deps = getProviderDeps(provider);
+  if (deps.length === 0) {
+    return definition;
+  }
+
+  let changed = false;
+  const next: Dependency[] = new Array(deps.length);
+  for (let index = 0; index < deps.length; index += 1) {
+    const dep = deps[index] as Dependency;
+    const rebound = rebindDependency(dep, nameMap);
+    next[index] = rebound;
+    if (rebound !== dep) {
+      changed = true;
+    }
+  }
+  if (!changed) {
+    return definition;
+  }
+
+  const nextProvider = withProviderDeps(provider, next);
+  return new ProviderDefinition(nextProvider, definition.lifetime, definition.key);
+}
+
+function rebindDependency(dep: Dependency, nameMap: Map<string, Token<unknown>[]>): Dependency {
+  if (dep === undefined) {
+    return dep;
+  }
+  if (isLazyDependency(dep)) {
+    const inner = dep.inner;
+    if (isNamedDependency(inner)) {
+      const token = resolveName(inner.name, nameMap);
+      return token ? lazyDependency(token) : dep;
+    }
+    return dep;
+  }
+  if (isNamedDependency(dep)) {
+    return resolveName(dep.name, nameMap) ?? dep;
+  }
+  return dep;
+}
+
+function resolveName(name: string, nameMap: Map<string, Token<unknown>[]>): Token<unknown> | undefined {
+  const tokens = nameMap.get(name);
+  if (!tokens || tokens.length === 0) {
+    return undefined;
+  }
+  if (tokens.length > 1) {
+    throw new AmbiguousNamedDependencyError(name);
+  }
+  return tokens[0];
+}