@zudojs/container 0.0.1 → 1.0.0

package/dist/containerCore/containerCore.type.d.ts

@@ -2,6 +2,8 @@
  * Types for the core container.
  */
 import type { RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
+import type { ResolutionCache, ResolutionResult } from "../containerResolution/containerResolution.type.js";
+import type { ContainerScopeContext } from "./containerCore.scope.js";
 /**
  * Options used when creating a child container scope.
  */
@@ -16,25 +18,29 @@ export interface ContainerScopeOptions {
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 /**
- * Full Container interface including mixin methods.
- * Used by ContainerScopeContext to reference the parent container.
+ * The surface a ContainerScopeContext needs from its owning container.
+ * Implemented by Container; the `resolveInScope` / `createScopeCache` /
+ * `releaseScope` members are internal plumbing for scopes and should not be
+ * called by application code.
  */
 export interface ContainerLike {
     readonly name: string;
-    readonly resolver: {
-        createScope(): import("../containerResolution/containerResolution.type.js").ResolutionCache;
-        resolveDetailed(token: unknown, options: unknown): {
-            token: unknown;
-            value: unknown;
-        };
-        canResolve(token: unknown): boolean;
-    };
-    readonly resolutionOptions: {
-        autoRegisterClasses: boolean;
-        detectCircularDependencies: boolean;
-        maxResolutionDepth: number;
-    };
     has<T>(token: RegistrationToken<T>): boolean;
-    createScope(options?: ContainerScopeOptions): import("./containerCore.scope.js").ContainerScopeContext;
+    canResolve<T>(token: RegistrationToken<T>): boolean;
+    isDisposed(): boolean;
+    createScope(options?: ContainerScopeOptions): ContainerScopeContext;
+    /**
+     * @internal Creates a fresh scoped-instance cache, optionally chained to a
+     * parent scope's cache (nested scopes).
+     */
+    createScopeCache(parent?: ResolutionCache): ResolutionCache;
+    /**
+     * @internal Resolves a token using the given scope cache. `onInstanceCreated`
+     * is invoked for every instance created during the resolution (including
+     * transitively created dependencies) so the scope can track SCOPED ones.
+     */
+    resolveInScope<T>(token: RegistrationToken<T>, cache: ResolutionCache, onInstanceCreated?: (result: ResolutionResult<unknown>) => void): ResolutionResult<T>;
+    /** @internal Unregisters a top-level scope from the container's live-scope set. */
+    releaseScope(scope: ContainerScopeContext): void;
 }
 //# sourceMappingURL=containerCore.type.d.ts.map

package/dist/containerLifecycle/containerLifecycle.core.d.ts

@@ -1,16 +1,41 @@
 /**
  * Lifecycle management for resolved container instances.
- * Tracks instances that need cleanup and disposes them when a container or scope is destroyed.
+ *
+ * Tracks SINGLETON instances (container-owned) and SCOPED instances
+ * (scope-owned) that need cleanup and disposes them when their owner is
+ * destroyed, in reverse creation order.
+ *
+ * TRANSIENT instances are deliberately NOT tracked: the container creates a
+ * new transient per resolution, so tracking them per token would either leak
+ * (unbounded growth) or silently drop all but the last instance. Callers own
+ * the disposal of transient instances they resolve.
  */
 import type { Token } from "../containerToken/containerToken.type.js";
 import { ContainerLifecycleError } from "@zudojs/errors";
-export interface Disposable {
-    dispose(): void;
+/**
+ * An object disposable via a `dispose()` method (sync or async).
+ * Named `DisposableLike` to avoid shadowing the ES2023 `Disposable` built-in.
+ */
+export interface DisposableLike {
+    dispose(): void | Promise<void>;
+}
+/** An object disposable via the ES2023 `Symbol.dispose` protocol. */
+export interface SymbolDisposableLike {
+    [Symbol.dispose](): void;
 }
-export interface AsyncDisposable {
-    [Symbol.asyncDispose]?: () => Promise<void>;
+/**
+ * An object disposable via the ES2023 `Symbol.asyncDispose` protocol.
+ * Named `AsyncDisposableLike` to avoid shadowing the `AsyncDisposable`
+ * built-in.
+ */
+export interface AsyncDisposableLike {
+    [Symbol.asyncDispose](): Promise<void> | void;
 }
-export type DisposableInstance = Disposable | AsyncDisposable;
+/** @deprecated Use {@link DisposableLike} instead. */
+export type Disposable = DisposableLike;
+/** @deprecated Use {@link AsyncDisposableLike} instead. */
+export type AsyncDisposable = AsyncDisposableLike;
+export type DisposableInstance = DisposableLike | SymbolDisposableLike | AsyncDisposableLike;
 export declare enum ContainerLifecycleOwner {
     CONTAINER = "container",
     SCOPE = "scope"
@@ -30,26 +55,51 @@ export declare class ContainerDisposalError extends ContainerLifecycleError {
     readonly tokens: readonly Token<unknown>[];
     constructor(errors: readonly unknown[], tokens: readonly Token<unknown>[]);
 }
-export declare function isDisposable(value: unknown): value is Disposable;
-export declare function isAsyncDisposable(value: unknown): value is AsyncDisposable;
+export declare function isDisposable(value: unknown): value is DisposableLike;
+export declare function isSymbolDisposable(value: unknown): value is SymbolDisposableLike;
+export declare function isAsyncDisposable(value: unknown): value is AsyncDisposableLike;
 export declare function isDisposableInstance(value: unknown): value is DisposableInstance;
 export declare class ContainerLifecycle {
     private readonly instances;
     private readonly options;
     private disposed;
     constructor(options?: ContainerLifecycleOptions);
+    /**
+     * Tracks a disposable instance for later cleanup.
+     *
+     * Re-tracking a token removes the previous entry and re-inserts it at the
+     * end of the map, so reverse-creation disposal order stays sound.
+     * Non-disposable instances are ignored.
+     */
     track<T>(token: Token<T>, instance: T, owner?: ContainerLifecycleOwner): void;
     has<T>(token: Token<T>): boolean;
     get<T>(token: Token<T>): TrackedInstance<T> | undefined;
     getAll(): readonly TrackedInstance[];
     get size(): number;
     untrack<T>(token: Token<T>): boolean;
+    /**
+     * Disposes a single tracked instance and untracks it. Untracking happens
+     * even when disposal fails — a failed disposal is terminal for the entry.
+     */
     disposeInstance<T>(token: Token<T>): Promise<void>;
+    /**
+     * Disposes tracked instances in reverse creation order.
+     *
+     * Entries are untracked even when their disposal fails (terminal). When
+     * `owner` is omitted the whole lifecycle is marked disposed — this happens
+     * even on failure — and every failure is reported in the thrown
+     * ContainerDisposalError.
+     */
     dispose(owner?: ContainerLifecycleOwner): Promise<void>;
     disposeScope(): Promise<void>;
     disposeContainer(): Promise<void>;
+    /**
+     * Releases all tracked references WITHOUT disposing them and marks the
+     * lifecycle disposed so further `track()` calls are refused. Used when a
+     * container is disposed with `autoDispose: false`.
+     */
+    shutdown(): void;
     isDisposed(): boolean;
-    reset(): void;
     getTrackedTokens(): readonly Token<unknown>[];
 }
 export declare function createContainerLifecycle(options?: ContainerLifecycleOptions): ContainerLifecycle;

package/dist/containerLifecycle/containerLifecycle.core.js

@@ -1,6 +1,14 @@
 /**
  * Lifecycle management for resolved container instances.
- * Tracks instances that need cleanup and disposes them when a container or scope is destroyed.
+ *
+ * Tracks SINGLETON instances (container-owned) and SCOPED instances
+ * (scope-owned) that need cleanup and disposes them when their owner is
+ * destroyed, in reverse creation order.
+ *
+ * TRANSIENT instances are deliberately NOT tracked: the container creates a
+ * new transient per resolution, so tracking them per token would either leak
+ * (unbounded growth) or silently drop all but the last instance. Callers own
+ * the disposal of transient instances they resolve.
  */
 import { describeToken } from "../containerToken/containerToken.type.js";
 import { ContainerLifecycleError } from "@zudojs/errors";
@@ -24,6 +32,12 @@ export function isDisposable(value) {
         "dispose" in value &&
         typeof value.dispose === "function");
 }
+export function isSymbolDisposable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Symbol.dispose in value &&
+        typeof value[Symbol.dispose] === "function");
+}
 export function isAsyncDisposable(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -31,7 +45,7 @@ export function isAsyncDisposable(value) {
         typeof value[Symbol.asyncDispose] === "function");
 }
 export function isDisposableInstance(value) {
-    return isDisposable(value) || isAsyncDisposable(value);
+    return (isDisposable(value) || isSymbolDisposable(value) || isAsyncDisposable(value));
 }
 export class ContainerLifecycle {
     instances = new Map();
@@ -40,11 +54,19 @@ export class ContainerLifecycle {
     constructor(options = {}) {
         this.options = { failFast: options.failFast ?? false };
     }
+    /**
+     * Tracks a disposable instance for later cleanup.
+     *
+     * Re-tracking a token removes the previous entry and re-inserts it at the
+     * end of the map, so reverse-creation disposal order stays sound.
+     * Non-disposable instances are ignored.
+     */
     track(token, instance, owner = ContainerLifecycleOwner.CONTAINER) {
         if (this.disposed)
-            throw new Error("Cannot track an instance after the container lifecycle has been disposed.");
+            throw new ContainerLifecycleError("track", "Cannot track an instance after the container lifecycle has been disposed.");
         if (!isDisposableInstance(instance))
             return;
+        this.instances.delete(token);
         this.instances.set(token, {
             token,
             instance,
@@ -68,14 +90,18 @@ export class ContainerLifecycle {
     untrack(token) {
         return this.instances.delete(token);
     }
+    /**
+     * Disposes a single tracked instance and untracks it. Untracking happens
+     * even when disposal fails — a failed disposal is terminal for the entry.
+     */
     async disposeInstance(token) {
-        const tracked = this.get(token);
+        const tracked = this.instances.get(token);
         if (!tracked || tracked.disposed)
             return;
+        tracked.disposed = true;
+        this.instances.delete(token);
         try {
             await disposeValue(tracked.instance);
-            tracked.disposed = true;
-            this.instances.delete(token);
         }
         catch (error) {
             if (this.options.failFast)
@@ -83,6 +109,14 @@ export class ContainerLifecycle {
             throw new ContainerDisposalError([error], [token]);
         }
     }
+    /**
+     * Disposes tracked instances in reverse creation order.
+     *
+     * Entries are untracked even when their disposal fails (terminal). When
+     * `owner` is omitted the whole lifecycle is marked disposed — this happens
+     * even on failure — and every failure is reported in the thrown
+     * ContainerDisposalError.
+     */
     async dispose(owner) {
         if (this.disposed)
             return;
@@ -95,10 +129,10 @@ export class ContainerLifecycle {
         for (const entry of selected) {
             if (entry.disposed)
                 continue;
+            entry.disposed = true;
+            this.instances.delete(entry.token);
             try {
                 await disposeValue(entry.instance);
-                entry.disposed = true;
-                this.instances.delete(entry.token);
             }
             catch (error) {
                 errors.push(error);
@@ -107,10 +141,10 @@ export class ContainerLifecycle {
                     break;
             }
         }
-        if (errors.length > 0)
-            throw new ContainerDisposalError(errors, failedTokens);
         if (owner === undefined)
             this.disposed = true;
+        if (errors.length > 0)
+            throw new ContainerDisposalError(errors, failedTokens);
     }
     async disposeScope() {
         await this.dispose(ContainerLifecycleOwner.SCOPE);
@@ -118,13 +152,18 @@ export class ContainerLifecycle {
     async disposeContainer() {
         await this.dispose(ContainerLifecycleOwner.CONTAINER);
     }
+    /**
+     * Releases all tracked references WITHOUT disposing them and marks the
+     * lifecycle disposed so further `track()` calls are refused. Used when a
+     * container is disposed with `autoDispose: false`.
+     */
+    shutdown() {
+        this.instances.clear();
+        this.disposed = true;
+    }
     isDisposed() {
         return this.disposed;
     }
-    reset() {
-        this.instances.clear();
-        this.disposed = false;
-    }
     getTrackedTokens() {
         return [...this.instances.keys()];
     }
@@ -134,8 +173,12 @@ async function disposeValue(value) {
         await value[Symbol.asyncDispose]();
         return;
     }
+    if (isSymbolDisposable(value)) {
+        value[Symbol.dispose]();
+        return;
+    }
     if (isDisposable(value)) {
-        value.dispose();
+        await value.dispose();
         return;
     }
 }

package/dist/containerOptions/containerOptions.type.d.ts

@@ -4,26 +4,18 @@
 import type { ContainerLifecycleOptions } from "../containerLifecycle/containerLifecycle.core.js";
 import type { ContainerRegistryOptions } from "../containerRegistry/containerRegistry.type.js";
 import type { ResolutionOptions } from "../containerResolution/containerResolution.type.js";
-export declare enum ContainerLogLevel {
-    NONE = "none",
-    ERROR = "error",
-    WARN = "warn",
-    INFO = "info",
-    DEBUG = "debug",
-    TRACE = "trace"
-}
-export declare const DEFAULT_CONTAINER_LOG_LEVEL: ContainerLogLevel;
-export interface ContainerResolutionOptions extends ResolutionOptions {
-    readonly autoRegisterClasses?: boolean;
-    readonly detectCircularDependencies?: boolean;
-    readonly maxResolutionDepth?: number;
-}
+/**
+ * The subset of {@link ResolutionOptions} a container accepts at
+ * construction time. Per-call plumbing (`cache`, `path`,
+ * `allowRegistration`, `onInstanceCreated`) is managed by the container
+ * itself and deliberately not configurable here.
+ */
+export type ContainerResolutionOptions = Pick<ResolutionOptions, "autoRegisterClasses" | "detectCircularDependencies" | "maxResolutionDepth">;
 export interface ContainerOptions {
     readonly name?: string;
     readonly registry?: ContainerRegistryOptions;
     readonly lifecycle?: ContainerLifecycleOptions;
     readonly resolution?: ContainerResolutionOptions;
-    readonly logLevel?: ContainerLogLevel;
     readonly autoDispose?: boolean;
     readonly allowScopes?: boolean;
     readonly freezeRegistrations?: boolean;
@@ -34,7 +26,6 @@ export interface ResolvedContainerOptions {
     readonly registry: ContainerRegistryOptions;
     readonly lifecycle: ContainerLifecycleOptions;
     readonly resolution: ContainerResolutionOptions;
-    readonly logLevel: ContainerLogLevel;
     readonly autoDispose: boolean;
     readonly allowScopes: boolean;
     readonly freezeRegistrations: boolean;
@@ -47,7 +38,6 @@ export declare const DEFAULT_FREEZE_REGISTRATIONS = false;
 export declare const DEFAULT_RESOLUTION_OPTIONS: Required<Pick<ContainerResolutionOptions, "autoRegisterClasses" | "detectCircularDependencies" | "maxResolutionDepth">>;
 export declare function resolveContainerOptions(options?: ContainerOptions): ResolvedContainerOptions;
 export declare function validateResolutionOptions(options: ContainerResolutionOptions): void;
-export declare function isContainerLogLevel(value: unknown): value is ContainerLogLevel;
 export declare function allowsContainerScopes(options: ResolvedContainerOptions): boolean;
 export declare function shouldAutoDisposeContainer(options: ResolvedContainerOptions): boolean;
 export declare function canModifyRegistrations(options: ResolvedContainerOptions): boolean;

package/dist/containerOptions/containerOptions.type.js

@@ -1,16 +1,6 @@
 /**
  * Configuration options for the Zudojs dependency injection container.
  */
-export var ContainerLogLevel;
-(function (ContainerLogLevel) {
-    ContainerLogLevel["NONE"] = "none";
-    ContainerLogLevel["ERROR"] = "error";
-    ContainerLogLevel["WARN"] = "warn";
-    ContainerLogLevel["INFO"] = "info";
-    ContainerLogLevel["DEBUG"] = "debug";
-    ContainerLogLevel["TRACE"] = "trace";
-})(ContainerLogLevel || (ContainerLogLevel = {}));
-export const DEFAULT_CONTAINER_LOG_LEVEL = ContainerLogLevel.WARN;
 export const DEFAULT_CONTAINER_NAME = "zudojs-container";
 export const DEFAULT_AUTO_DISPOSE = true;
 export const DEFAULT_ALLOW_SCOPES = true;
@@ -39,7 +29,6 @@ export function resolveContainerOptions(options = {}) {
         registry: Object.freeze({ ...(options.registry ?? {}) }),
         lifecycle: Object.freeze({ ...(options.lifecycle ?? {}) }),
         resolution: Object.freeze({ ...resolution }),
-        logLevel: options.logLevel ?? DEFAULT_CONTAINER_LOG_LEVEL,
         autoDispose: options.autoDispose ?? DEFAULT_AUTO_DISPOSE,
         allowScopes: options.allowScopes ?? DEFAULT_ALLOW_SCOPES,
         freezeRegistrations: options.freezeRegistrations ?? DEFAULT_FREEZE_REGISTRATIONS,
@@ -53,14 +42,6 @@ export function validateResolutionOptions(options) {
         throw new RangeError("Container maxResolutionDepth must be a positive integer.");
     }
 }
-export function isContainerLogLevel(value) {
-    return (value === ContainerLogLevel.NONE ||
-        value === ContainerLogLevel.ERROR ||
-        value === ContainerLogLevel.WARN ||
-        value === ContainerLogLevel.INFO ||
-        value === ContainerLogLevel.DEBUG ||
-        value === ContainerLogLevel.TRACE);
-}
 export function allowsContainerScopes(options) {
     return options.allowScopes;
 }

package/dist/containerProvider/containerProvider.core.d.ts

@@ -6,6 +6,11 @@ import type { Constructor, InjectionToken, Token } from "../containerToken/conta
 export type ProviderToken<T = unknown> = Token<T> | InjectionToken<T>;
 export interface ClassProvider<T> {
     readonly useClass: Constructor<T>;
+    /**
+     * Tokens resolved and passed to the constructor, in order.
+     * Omit (or leave empty) for zero-argument constructors.
+     */
+    readonly inject?: readonly ProviderToken[];
 }
 export interface FactoryProvider<T> {
     readonly useFactory: (...dependencies: unknown[]) => T;
@@ -25,6 +30,7 @@ export interface TokenProvider<T = unknown> {
 export interface ClassRegistration<T = unknown> {
     readonly provide: ProviderToken<T>;
     readonly useClass: Constructor<T>;
+    readonly inject?: readonly ProviderToken[];
 }
 export interface FactoryRegistration<T = unknown> {
     readonly provide: ProviderToken<T>;
@@ -45,12 +51,14 @@ export declare function isFactoryProvider<T = unknown>(provider: Provider<T>): p
 export declare function isValueProvider<T = unknown>(provider: Provider<T>): provider is ValueProvider<T>;
 export declare function isExistingProvider<T = unknown>(provider: Provider<T>): provider is ExistingProvider<T>;
 export declare function isTokenProvider<T = unknown>(provider: ContainerProvider<T>): provider is TokenProvider<T>;
-export declare function hasInjectedDependencies<T = unknown>(provider: Provider<T>): provider is FactoryProvider<T>;
-export declare function classProvider<T>(useClass: Constructor<T>): ClassProvider<T>;
+export declare function hasInjectedDependencies<T = unknown>(provider: Provider<T>): provider is (FactoryProvider<T> | ClassProvider<T>) & {
+    readonly inject: readonly ProviderToken[];
+};
+export declare function classProvider<T>(useClass: Constructor<T>, inject?: readonly ProviderToken[]): ClassProvider<T>;
 export declare function factoryProvider<T>(useFactory: (...dependencies: unknown[]) => T, inject?: readonly ProviderToken[]): FactoryProvider<T>;
 export declare function valueProvider<T>(useValue: T): ValueProvider<T>;
 export declare function existingProvider<T>(useExisting: ProviderToken<T>): ExistingProvider<T>;
-export declare function provideClass<T>(provide: ProviderToken<T>, useClass: Constructor<T>): ClassRegistration<T>;
+export declare function provideClass<T>(provide: ProviderToken<T>, useClass: Constructor<T>, inject?: readonly ProviderToken[]): ClassRegistration<T>;
 export declare function provideFactory<T>(provide: ProviderToken<T>, useFactory: (...dependencies: unknown[]) => T, inject?: readonly ProviderToken[]): FactoryRegistration<T>;
 export declare function provideValue<T>(provide: ProviderToken<T>, useValue: T): ValueRegistration<T>;
 export declare function provideExisting<T>(provide: ProviderToken<T>, useExisting: ProviderToken<T>): ExistingRegistration<T>;

package/dist/containerProvider/containerProvider.core.js

@@ -18,10 +18,12 @@ export function isTokenProvider(provider) {
     return "provide" in provider && "provider" in provider;
 }
 export function hasInjectedDependencies(provider) {
-    return isFactoryProvider(provider) && Array.isArray(provider.inject);
+    return ((isFactoryProvider(provider) || isClassProvider(provider)) &&
+        Array.isArray(provider.inject) &&
+        provider.inject.length > 0);
 }
-export function classProvider(useClass) {
-    return Object.freeze({ useClass });
+export function classProvider(useClass, inject = []) {
+    return Object.freeze({ useClass, inject: Object.freeze([...inject]) });
 }
 export function factoryProvider(useFactory, inject = []) {
     return Object.freeze({ useFactory, inject: Object.freeze([...inject]) });
@@ -32,8 +34,12 @@ export function valueProvider(useValue) {
 export function existingProvider(useExisting) {
     return Object.freeze({ useExisting });
 }
-export function provideClass(provide, useClass) {
-    return Object.freeze({ provide, useClass });
+export function provideClass(provide, useClass, inject = []) {
+    return Object.freeze({
+        provide,
+        useClass,
+        inject: Object.freeze([...inject]),
+    });
 }
 export function provideFactory(provide, useFactory, inject = []) {
     return Object.freeze({

package/dist/containerRegistration/containerRegistration.core.d.ts

@@ -6,6 +6,15 @@ import { ContainerScope } from "../containerScope/containerScope.type.js";
 import type { ContainerProvider, ProviderToken } from "../containerProvider/containerProvider.core.js";
 import type { InjectionToken, Token } from "../containerToken/containerToken.type.js";
 export type RegistrationToken<T = unknown> = Token<T> | InjectionToken<T>;
+/** The type a registration token resolves to (`unknown` for untyped tokens). */
+export type ResolvedToken<T extends RegistrationToken> = T extends RegistrationToken<infer U> ? U : never;
+/**
+ * Maps a tuple of registration tokens to a tuple of their resolved types, so
+ * `resolveMany([LOGGER, DB])` is typed `[Logger, Db]`.
+ */
+export type ResolvedTokens<Tokens extends readonly RegistrationToken[]> = {
+    -readonly [K in keyof Tokens]: Tokens[K] extends RegistrationToken ? ResolvedToken<Tokens[K]> : never;
+};
 export interface RegistrationMetadata {
     readonly name?: string;
     readonly description?: string;
@@ -18,7 +27,6 @@ export interface ContainerRegistration<T = unknown> {
     readonly provider: ContainerProvider<T>;
     readonly scope: ContainerScope;
     readonly metadata: RegistrationMetadata;
-    readonly initialized: boolean;
     readonly createdAt: Date;
 }
 export interface CreateRegistrationOptions extends RegistrationMetadata {
@@ -29,13 +37,11 @@ export interface MutableRegistrationState<T = unknown> {
     readonly provider: ContainerProvider<T>;
     scope: ContainerScope;
     metadata: RegistrationMetadata;
-    initialized: boolean;
     createdAt: Date;
 }
 export declare function createRegistration<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
 export declare function createMutableRegistrationState<T>(registration: ContainerRegistration<T>): MutableRegistrationState<T>;
 export declare function freezeRegistration<T>(state: MutableRegistrationState<T>): ContainerRegistration<T>;
-export declare function markRegistrationInitialized<T>(registration: ContainerRegistration<T>): ContainerRegistration<T>;
 export declare function getRegistrationToken<T>(registration: ContainerRegistration<T>): Token<T>;
 export declare function getRegistrationProviderToken<T>(registration: ContainerRegistration<T>): ProviderToken<T> | undefined;
 export declare function isSingletonRegistration<T>(registration: ContainerRegistration<T>): boolean;

package/dist/containerRegistration/containerRegistration.core.js

@@ -13,7 +13,6 @@ export function createRegistration(token, provider, options = {}) {
         provider: normalizedProvider,
         scope: resolveContainerScope(options.scope),
         metadata: createRegistrationMetadata(options, normalizedToken),
-        initialized: false,
         createdAt: new Date(),
     };
     return Object.freeze({
@@ -43,7 +42,6 @@ export function createMutableRegistrationState(registration) {
         provider: registration.provider,
         scope: registration.scope,
         metadata: registration.metadata,
-        initialized: registration.initialized,
         createdAt: registration.createdAt,
     };
 }
@@ -58,13 +56,9 @@ export function freezeRegistration(state) {
                 ? Object.freeze({ ...state.metadata.metadata })
                 : undefined,
         }),
-        initialized: state.initialized,
         createdAt: state.createdAt,
     });
 }
-export function markRegistrationInitialized(registration) {
-    return Object.freeze({ ...registration, initialized: true });
-}
 export function getRegistrationToken(registration) {
     return unwrapToken(registration.token);
 }

package/dist/containerRegistry/containerRegistry.core.d.ts

@@ -1,9 +1,12 @@
 /**
  * Container registration registry.
+ *
+ * The registry stores normalized registrations and emits change events
+ * (REGISTER / REPLACE / REMOVE / CLEAR / RESTORE) so collaborators — notably
+ * the resolver's singleton cache — can react to mutations.
  */
 import type { ContainerProvider } from "../containerProvider/containerProvider.core.js";
-import type { ContainerScope } from "../containerScope/containerScope.type.js";
-import type { ContainerRegistration, CreateRegistrationOptions, RegistrationMetadata, RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
+import type { ContainerRegistration, CreateRegistrationOptions, RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
 import type { Token } from "../containerToken/containerToken.type.js";
 import type { ContainerRegistryOptions, RegistryListener } from "./containerRegistry.type.js";
 export declare class ContainerRegistry {
@@ -12,25 +15,36 @@ export declare class ContainerRegistry {
     private readonly allowDuplicates;
     constructor(options?: ContainerRegistryOptions);
     register<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
-    registerRegistration<T>(registration: ContainerRegistration<T>): ContainerRegistration<T>;
     replace<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     get<T>(token: RegistrationToken<T>): ContainerRegistration<T> | undefined;
-    getOrThrow<T>(token: RegistrationToken<T>): ContainerRegistration<T>;
     has<T>(token: RegistrationToken<T>): boolean;
     remove<T>(token: RegistrationToken<T>): boolean;
-    removeOrThrow<T>(token: RegistrationToken<T>): void;
     get size(): number;
     getAll(): readonly ContainerRegistration[];
     getTokens(): readonly Token<unknown>[];
-    getByModule(module: string): readonly ContainerRegistration[];
-    getByScope(scope: ContainerScope): readonly ContainerRegistration[];
-    find(predicate: (r: ContainerRegistration) => boolean): readonly ContainerRegistration[];
-    getMetadata<T>(token: RegistrationToken<T>): RegistrationMetadata | undefined;
     clear(): void;
     subscribe(listener: RegistryListener): () => void;
     clearListeners(): void;
+    /**
+     * Notifies all listeners. Listener errors are collected and rethrown as a
+     * single AggregateError after every listener has been notified — they are
+     * never silently swallowed.
+     */
     private emit;
+    /**
+     * Returns an immutable snapshot of the current registrations.
+     * Pass the result to {@link restore} to roll the registry back.
+     */
     snapshot(): readonly ContainerRegistration[];
+    /**
+     * Wholesale replacement of the registry's contents.
+     *
+     * Every existing registration is discarded and replaced by `regs` (entries
+     * are validated first; duplicate tokens in `regs` throw unless
+     * `allowDuplicates` is enabled, in which case the last entry wins).
+     * Emits a single RESTORE event so caches keyed on the old registrations
+     * can be evicted.
+     */
     restore(regs: readonly ContainerRegistration[]): void;
 }
 //# sourceMappingURL=containerRegistry.core.d.ts.map