@zudojs/container 0.0.1 → 1.0.0

package/dist/containerCore/containerCore.core.js

@@ -1,5 +1,16 @@
 /**
  * Core dependency injection container for Zudojs.
+ *
+ * Lifetime and disposal model:
+ * - SINGLETON instances are cached in the container's root singleton cache
+ *   and tracked by the container lifecycle — including singletons created
+ *   transitively as dependencies of another resolution; they are disposed
+ *   when the container is disposed (or when their registration is
+ *   replaced/removed).
+ * - SCOPED instances only exist inside a scope created with `createScope()`;
+ *   resolving a SCOPED token at the root throws.
+ * - TRANSIENT instances are never cached and never tracked — callers own
+ *   their disposal.
  */
 import { existingProvider, factoryProvider, valueProvider, classProvider, } from "../containerProvider/containerProvider.core.js";
 import { ContainerScope as Scope } from "../containerScope/containerScope.type.js";
@@ -7,36 +18,63 @@ import { ContainerRegistry } from "../containerRegistry/containerRegistry.core.j
 import { ContainerResolver } from "../containerResolution/containerResolution.core.js";
 import { ContainerLifecycle, ContainerLifecycleOwner, } from "../containerLifecycle/containerLifecycle.core.js";
 import { resolveContainerOptions } from "../containerOptions/containerOptions.type.js";
+import { unwrapToken } from "../containerToken/containerToken.type.js";
+import { RegistrationNotFoundError } from "@zudojs/errors";
 import { ContainerScopeContext } from "./containerCore.scope.js";
 export class Container {
     name;
     options;
-    registry;
-    resolver;
-    lifecycle;
-    started = false;
-    disposed = false;
+    #registry;
+    #resolver;
+    #lifecycle;
+    #liveScopes = new Set();
+    #started = false;
+    #disposed = false;
     constructor(options = {}) {
         this.options = resolveContainerOptions(options);
         this.name = this.options.name;
-        this.registry = new ContainerRegistry(this.options.registry);
-        this.resolver = new ContainerResolver(this.registry);
-        this.lifecycle = new ContainerLifecycle(this.options.lifecycle);
+        this.#registry = new ContainerRegistry(this.options.registry);
+        this.#lifecycle = new ContainerLifecycle(this.options.lifecycle);
+        this.#resolver = new ContainerResolver(this.#registry, (token) => {
+            // A cached singleton was evicted because its registration changed;
+            // dispose the tracked instance. Eviction disposal is best-effort:
+            // failures cannot propagate through the synchronous registry mutation
+            // that triggered them.
+            void this.#lifecycle.disposeInstance(token).catch(() => {
+                /* see clearSingletons()/dispose() for error-surfacing disposal */
+            });
+        });
     }
+    /**
+     * Marks the container as started.
+     *
+     * Calling `start()` explicitly is optional: `resolve()` (and
+     * `createScope()`) auto-start the container on first use. Note that with
+     * `freezeRegistrations: true`, starting — including the implicit start
+     * performed by the first `resolve()` — freezes the registration set.
+     */
     start() {
         this.ensureNotDisposed();
-        if (this.started)
+        if (this.#started)
             return this;
-        this.started = true;
+        this.#started = true;
         return this;
     }
     register(token, provider, options = {}) {
         this.ensureMutable();
-        return this.registry.register(token, provider, options);
+        return this.#registry.register(token, provider, options);
     }
     registerClass(token, ctor, options = {}) {
-        return this.register(token, classProvider(ctor), options);
+        const { inject, ...rest } = options;
+        return this.register(token, classProvider(ctor, inject ?? []), rest);
     }
+    /**
+     * Registers a pre-built value.
+     *
+     * Note: the scope is forcibly set to SINGLETON (overriding any
+     * `options.scope`) — a value provider always returns the same instance, so
+     * any other lifetime would be misleading.
+     */
     registerValue(token, value, options = {}) {
         return this.register(token, valueProvider(value), {
             ...options,
@@ -49,73 +87,168 @@ export class Container {
     registerExisting(token, existing, options = {}) {
         return this.register(token, existingProvider(existing), options);
     }
+    /**
+     * Resolves a dependency at the container root.
+     *
+     * Auto-starts the container on first use. SCOPED registrations cannot be
+     * resolved here — create a scope with {@link createScope} instead.
+     */
     resolve(token) {
         this.ensureActive();
-        const result = this.resolver.resolveDetailed(token, this.resolutionOptions);
-        this.lifecycle.track(result.token, result.value, ContainerLifecycleOwner.CONTAINER);
-        return result.value;
+        return this.#resolver.resolveDetailed(token, this.buildResolutionOptions())
+            .value;
     }
+    /**
+     * Resolves several tokens at once. The result is a tuple typed per token,
+     * so heterogeneous token lists keep their individual types.
+     */
     resolveMany(tokens) {
         return tokens.map((t) => this.resolve(t));
     }
+    /**
+     * Like {@link resolve} but returns `undefined` when the token has no
+     * registration (and cannot be auto-registered). Other resolution failures
+     * — broken factories, missing dependencies, captive dependencies — still
+     * throw.
+     */
     resolveOptional(token) {
-        if (!this.canResolve(token))
-            return undefined;
-        return this.resolve(token);
+        try {
+            return this.resolve(token);
+        }
+        catch (error) {
+            if (error instanceof RegistrationNotFoundError)
+                return undefined;
+            throw error;
+        }
     }
     canResolve(token) {
         this.ensureNotDisposed();
-        return this.resolver.canResolve(token);
+        return this.#resolver.canResolve(token, this.resolutionOptions.autoRegisterClasses);
     }
     has(token) {
         this.ensureNotDisposed();
-        return this.registry.has(token);
+        return this.#registry.has(token);
     }
     getRegistration(token) {
         this.ensureNotDisposed();
-        return this.registry.get(token);
+        return this.#registry.get(token);
+    }
+    replace(token, provider, options = {}) {
+        this.ensureMutable();
+        return this.#registry.replace(token, provider, options);
     }
     remove(token) {
         this.ensureMutable();
-        return this.registry.remove(token);
+        return this.#registry.remove(token);
+    }
+    /** Removes every registration (evicting and disposing cached singletons). */
+    clearRegistrations() {
+        this.ensureMutable();
+        this.#registry.clear();
     }
     createScope(options = {}) {
         this.ensureActive();
         if (!this.options.allowScopes)
-            throw new Error("Container scopes are disabled.");
-        return new ContainerScopeContext(this, options);
+            throw new Error(`Container scopes are disabled for "${this.name}".`);
+        const scope = new ContainerScopeContext(this, options);
+        this.#liveScopes.add(scope);
+        return scope;
     }
     getRegistrations() {
         this.ensureNotDisposed();
-        return this.registry.getAll();
+        return this.#registry.getAll();
+    }
+    getTokens() {
+        this.ensureNotDisposed();
+        return this.#registry.getTokens();
     }
     get registrationCount() {
-        return this.registry.size;
+        return this.#registry.size;
+    }
+    /**
+     * Returns an immutable snapshot of the current registrations, suitable for
+     * later {@link restoreSnapshot}. Cached instances are NOT part of the
+     * snapshot — only the registrations.
+     */
+    snapshot() {
+        this.ensureNotDisposed();
+        return this.#registry.snapshot();
+    }
+    /**
+     * Wholesale-replaces the registration set with a previous snapshot.
+     * Entries are validated, cached singletons for the old set are evicted and
+     * disposed, and the operation is refused when registrations are frozen.
+     */
+    restoreSnapshot(registrations) {
+        this.ensureMutable();
+        this.#registry.restore(registrations);
     }
     isStarted() {
-        return this.started;
+        return this.#started;
     }
     isDisposed() {
-        return this.disposed;
+        return this.#disposed;
     }
-    clearSingletons() {
-        this.ensureActive();
-        this.resolver.clearSingletons();
+    /**
+     * Evicts all cached singleton instances and disposes the tracked ones.
+     * Fails with an AggregateError listing every disposal failure.
+     */
+    async clearSingletons() {
+        this.ensureNotDisposed();
+        const tokens = this.#resolver.getCachedSingletonTokens();
+        this.#resolver.clearSingletonCache();
+        const failures = [];
+        for (const token of tokens) {
+            try {
+                await this.#lifecycle.disposeInstance(token);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length > 0)
+            throw new AggregateError(failures, `Failed to dispose ${failures.length} singleton instance(s) of container "${this.name}".`);
     }
+    /**
+     * Disposes the container: all live scopes first, then (with
+     * `autoDispose: true`, the default) every tracked singleton in reverse
+     * creation order.
+     *
+     * With `autoDispose: false` tracked instances are NOT disposed — their
+     * references are simply released and disposal becomes the caller's
+     * responsibility.
+     *
+     * Disposal is terminal: the container is marked disposed even when some
+     * instances fail to dispose; every failure is reported in the thrown
+     * AggregateError. Idempotent.
+     */
     async dispose() {
-        if (this.disposed)
+        if (this.#disposed)
             return;
-        try {
-            if (this.options.autoDispose)
-                await this.lifecycle.disposeContainer();
-            else
-                this.lifecycle.reset();
+        const failures = [];
+        for (const scope of [...this.#liveScopes]) {
+            try {
+                await scope.dispose();
+            }
+            catch (error) {
+                failures.push(error);
+            }
         }
-        finally {
-            this.resolver.clearSingletons();
-            this.disposed = true;
-            this.started = false;
+        this.#liveScopes.clear();
+        if (this.options.autoDispose) {
+            try {
+                await this.#lifecycle.dispose();
+            }
+            catch (error) {
+                failures.push(error);
+            }
         }
+        this.#lifecycle.shutdown();
+        this.#resolver.clearSingletonCache();
+        this.#disposed = true;
+        this.#started = false;
+        if (failures.length > 0)
+            throw new AggregateError(failures, `Container "${this.name}" was disposed, but ${failures.length} cleanup step(s) failed.`);
     }
     get resolutionOptions() {
         return {
@@ -124,20 +257,54 @@ export class Container {
             maxResolutionDepth: this.options.resolution.maxResolutionDepth ?? 100,
         };
     }
+    /** @internal Creates a fresh scoped-instance cache for a scope. */
+    createScopeCache(parent) {
+        return this.#resolver.createScope(parent);
+    }
+    /** @internal Resolves on behalf of a scope, tracking singleton results. */
+    resolveInScope(token, cache, onInstanceCreated) {
+        this.ensureActive();
+        return this.#resolver.resolveDetailed(token, this.buildResolutionOptions(cache, onInstanceCreated));
+    }
+    /** @internal Unregisters a top-level scope from the live-scope set. */
+    releaseScope(scope) {
+        this.#liveScopes.delete(scope);
+    }
+    buildResolutionOptions(cache, onInstanceCreated) {
+        return {
+            ...this.resolutionOptions,
+            allowRegistration: !this.options.freezeRegistrations,
+            cache,
+            onInstanceCreated: (result) => {
+                this.trackCreated(result);
+                onInstanceCreated?.(result);
+            },
+        };
+    }
+    /**
+     * Tracks every freshly created SINGLETON instance — top-level results and
+     * transitively created dependencies alike — in the container lifecycle.
+     * SCOPED instances are owned by scopes and TRANSIENT ones by callers.
+     */
+    trackCreated(result) {
+        if (result.scope !== Scope.SINGLETON)
+            return;
+        this.#lifecycle.track(unwrapToken(result.token), result.value, ContainerLifecycleOwner.CONTAINER);
+    }
     ensureActive() {
         this.ensureNotDisposed();
-        if (!this.started)
+        if (!this.#started)
             this.start();
     }
     ensureNotDisposed() {
-        if (this.disposed)
+        if (this.#disposed)
             throw new Error(`Container "${this.name}" has already been disposed.`);
     }
     ensureMutable() {
         this.ensureNotDisposed();
         if (!this.options.freezeRegistrations)
             return;
-        if (this.started)
+        if (this.#started)
             throw new Error(`Registrations for container "${this.name}" are frozen.`);
     }
 }

package/dist/containerCore/containerCore.scope.d.ts

@@ -1,31 +1,53 @@
 /**
- * ContainerScopeContext — child dependency scope with
- * its own scoped-instance cache.
- */
-import type { RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
-import type { ContainerScopeOptions, ContainerLike } from "./containerCore.type.js";
-/**
- * Represents a child dependency scope.
+ * ContainerScopeContext — a dependency scope with its own scoped-instance
+ * cache and its own lifecycle for SCOPED instances.
  *
- * A scope has its own scoped-instance cache while sharing
- * registrations and singleton instances with its parent.
+ * Ownership model:
+ * - SCOPED instances created through this scope — including those created
+ *   transitively as dependencies — are owned by the scope and disposed when
+ *   the scope is disposed.
+ * - SINGLETON instances resolved through a scope stay owned by the parent
+ *   container — a scope's disposal never touches them.
+ * - TRANSIENT instances are not tracked anywhere; callers own their disposal.
+ *
+ * Nesting: `scope.createScope()` creates a true child scope. A child sees
+ * SCOPED instances already created by its ancestors (lookups chain upward),
+ * while instances it creates itself are private to the child. Disposing a
+ * scope disposes its children first, and a child refuses to resolve once any
+ * ancestor (scope or container) is disposed.
  */
+import type { RegistrationToken, ResolvedTokens } from "../containerRegistration/containerRegistration.core.js";
+import type { ContainerScopeOptions, ContainerLike } from "./containerCore.type.js";
 export declare class ContainerScopeContext {
-    private readonly parent;
     private disposed;
     private readonly cache;
     private readonly lifecycle;
+    private readonly container;
+    private readonly parentScope;
+    private readonly children;
     readonly name: string;
     readonly metadata: Readonly<Record<string, unknown>>;
-    constructor(parent: ContainerLike, options?: ContainerScopeOptions);
+    /**
+     * @param container The container that owns the scope tree.
+     * @param options Scope name / metadata.
+     * @param parentScope When given, the new scope is a nested child of it.
+     *   Application code should use `container.createScope()` /
+     *   `scope.createScope()` rather than constructing scopes directly.
+     */
+    constructor(container: ContainerLike, options?: ContainerScopeOptions, parentScope?: ContainerScopeContext);
     /**
      * Resolves a dependency within this scope.
+     *
+     * SCOPED instances are cached per scope (visible to child scopes) and
+     * tracked for disposal with the scope that created them. SINGLETON
+     * instances come from (and are tracked by) the container. TRANSIENT
+     * instances are created fresh and never tracked.
      */
     resolve<T>(token: RegistrationToken<T>): T;
     /**
-     * Resolves multiple dependencies within this scope.
+     * Resolves multiple dependencies within this scope, typed per token.
      */
-    resolveMany<T>(tokens: readonly RegistrationToken<T>[]): T[];
+    resolveMany<const Tokens extends readonly RegistrationToken[]>(tokens: Tokens): ResolvedTokens<Tokens>;
     /**
      * Checks whether a dependency can be resolved.
      */
@@ -35,11 +57,20 @@ export declare class ContainerScopeContext {
      */
     has<T>(token: RegistrationToken<T>): boolean;
     /**
-     * Creates another nested scope.
+     * Creates a nested child scope.
+     *
+     * The child inherits this scope's cached SCOPED instances for lookups,
+     * caches the SCOPED instances it creates itself, and is disposed
+     * automatically when this scope is disposed.
      */
     createScope(options?: ContainerScopeOptions): ContainerScopeContext;
     /**
-     * Disposes all instances belonging to this scope.
+     * Disposes child scopes (most recent first), then all SCOPED instances
+     * belonging to this scope in reverse creation order, and detaches the scope
+     * from its parent. Container-owned singletons are not touched. Idempotent.
+     *
+     * Every failure is collected; the scope is marked disposed regardless and
+     * an AggregateError listing the failures is thrown afterwards.
      */
     dispose(): Promise<void>;
     /**
@@ -47,11 +78,25 @@ export declare class ContainerScopeContext {
      */
     isDisposed(): boolean;
     /**
-     * Returns the parent container.
+     * Returns the direct parent: the container for a top-level scope, or the
+     * parent scope for a nested one.
+     */
+    getParent(): ContainerLike | ContainerScopeContext;
+    /**
+     * Returns the container that owns the whole scope tree.
+     */
+    getContainer(): ContainerLike;
+    /** @internal Detaches a disposed child scope. */
+    releaseChild(scope: ContainerScopeContext): void;
+    /**
+     * Tracks SCOPED instances created during a resolution through this scope
+     * (top-level result or transitively created dependency). Instances served
+     * from an ancestor's cache are cache hits and never reach here.
      */
-    getParent(): ContainerLike;
+    private trackCreated;
     /**
-     * Throws when the scope is no longer active.
+     * Throws when the scope — or any ancestor scope, or the container that
+     * owns it — is no longer active.
      */
     private ensureActive;
 }

package/dist/containerCore/containerCore.scope.js

@@ -1,42 +1,62 @@
 /**
- * ContainerScopeContext — child dependency scope with
- * its own scoped-instance cache.
- */
-import { ContainerLifecycle, ContainerLifecycleOwner, } from "../containerLifecycle/containerLifecycle.core.js";
-/**
- * Represents a child dependency scope.
+ * ContainerScopeContext — a dependency scope with its own scoped-instance
+ * cache and its own lifecycle for SCOPED instances.
  *
- * A scope has its own scoped-instance cache while sharing
- * registrations and singleton instances with its parent.
+ * Ownership model:
+ * - SCOPED instances created through this scope — including those created
+ *   transitively as dependencies — are owned by the scope and disposed when
+ *   the scope is disposed.
+ * - SINGLETON instances resolved through a scope stay owned by the parent
+ *   container — a scope's disposal never touches them.
+ * - TRANSIENT instances are not tracked anywhere; callers own their disposal.
+ *
+ * Nesting: `scope.createScope()` creates a true child scope. A child sees
+ * SCOPED instances already created by its ancestors (lookups chain upward),
+ * while instances it creates itself are private to the child. Disposing a
+ * scope disposes its children first, and a child refuses to resolve once any
+ * ancestor (scope or container) is disposed.
  */
+import { ContainerLifecycle, ContainerLifecycleOwner, } from "../containerLifecycle/containerLifecycle.core.js";
+import { ContainerScope } from "../containerScope/containerScope.type.js";
 export class ContainerScopeContext {
-    parent;
     disposed = false;
     cache;
     lifecycle;
+    container;
+    parentScope;
+    children = new Set();
     name;
     metadata;
-    constructor(parent, options = {}) {
-        this.parent = parent;
-        this.name = options.name ?? `${parent.name}:scope`;
+    /**
+     * @param container The container that owns the scope tree.
+     * @param options Scope name / metadata.
+     * @param parentScope When given, the new scope is a nested child of it.
+     *   Application code should use `container.createScope()` /
+     *   `scope.createScope()` rather than constructing scopes directly.
+     */
+    constructor(container, options = {}, parentScope) {
+        this.container = container;
+        this.parentScope = parentScope;
+        this.name = options.name ?? `${(parentScope ?? container).name}:scope`;
         this.metadata = Object.freeze({ ...(options.metadata ?? {}) });
-        this.cache = parent.resolver.createScope();
+        this.cache = container.createScopeCache(parentScope?.cache);
         this.lifecycle = new ContainerLifecycle();
     }
     /**
      * Resolves a dependency within this scope.
+     *
+     * SCOPED instances are cached per scope (visible to child scopes) and
+     * tracked for disposal with the scope that created them. SINGLETON
+     * instances come from (and are tracked by) the container. TRANSIENT
+     * instances are created fresh and never tracked.
      */
     resolve(token) {
         this.ensureActive();
-        const result = this.parent.resolver.resolveDetailed(token, {
-            ...this.parent.resolutionOptions,
-            cache: this.cache,
-        });
-        this.lifecycle.track(result.token, result.value, ContainerLifecycleOwner.SCOPE);
+        const result = this.container.resolveInScope(token, this.cache, (created) => this.trackCreated(created));
         return result.value;
     }
     /**
-     * Resolves multiple dependencies within this scope.
+     * Resolves multiple dependencies within this scope, typed per token.
      */
     resolveMany(tokens) {
         return tokens.map((token) => this.resolve(token));
@@ -46,35 +66,66 @@ export class ContainerScopeContext {
      */
     canResolve(token) {
         this.ensureActive();
-        return this.parent.resolver.canResolve(token);
+        return this.container.canResolve(token);
     }
     /**
      * Checks whether a registration exists.
      */
     has(token) {
         this.ensureActive();
-        return this.parent.has(token);
+        return this.container.has(token);
     }
     /**
-     * Creates another nested scope.
+     * Creates a nested child scope.
+     *
+     * The child inherits this scope's cached SCOPED instances for lookups,
+     * caches the SCOPED instances it creates itself, and is disposed
+     * automatically when this scope is disposed.
      */
     createScope(options = {}) {
         this.ensureActive();
-        return this.parent.createScope(options);
+        const child = new ContainerScopeContext(this.container, options, this);
+        this.children.add(child);
+        return child;
     }
     /**
-     * Disposes all instances belonging to this scope.
+     * Disposes child scopes (most recent first), then all SCOPED instances
+     * belonging to this scope in reverse creation order, and detaches the scope
+     * from its parent. Container-owned singletons are not touched. Idempotent.
+     *
+     * Every failure is collected; the scope is marked disposed regardless and
+     * an AggregateError listing the failures is thrown afterwards.
      */
     async dispose() {
         if (this.disposed)
             return;
+        this.disposed = true;
+        const failures = [];
+        for (const child of [...this.children].reverse()) {
+            try {
+                await child.dispose();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        this.children.clear();
         try {
-            await this.lifecycle.disposeScope();
+            await this.lifecycle.dispose();
+        }
+        catch (error) {
+            failures.push(error);
         }
         finally {
+            this.lifecycle.shutdown();
             this.cache.clear();
-            this.disposed = true;
+            if (this.parentScope)
+                this.parentScope.releaseChild(this);
+            else
+                this.container.releaseScope(this);
         }
+        if (failures.length > 0)
+            throw new AggregateError(failures, `Container scope "${this.name}" was disposed, but ${failures.length} cleanup step(s) failed.`);
     }
     /**
      * Returns whether the scope has been disposed.
@@ -83,18 +134,46 @@ export class ContainerScopeContext {
         return this.disposed;
     }
     /**
-     * Returns the parent container.
+     * Returns the direct parent: the container for a top-level scope, or the
+     * parent scope for a nested one.
      */
     getParent() {
-        return this.parent;
+        return this.parentScope ?? this.container;
     }
     /**
-     * Throws when the scope is no longer active.
+     * Returns the container that owns the whole scope tree.
+     */
+    getContainer() {
+        return this.container;
+    }
+    /** @internal Detaches a disposed child scope. */
+    releaseChild(scope) {
+        this.children.delete(scope);
+    }
+    /**
+     * Tracks SCOPED instances created during a resolution through this scope
+     * (top-level result or transitively created dependency). Instances served
+     * from an ancestor's cache are cache hits and never reach here.
+     */
+    trackCreated(result) {
+        if (result.scope !== ContainerScope.SCOPED)
+            return;
+        this.lifecycle.track(result.token, result.value, ContainerLifecycleOwner.SCOPE);
+    }
+    /**
+     * Throws when the scope — or any ancestor scope, or the container that
+     * owns it — is no longer active.
      */
     ensureActive() {
         if (this.disposed) {
             throw new Error(`Container scope "${this.name}" has already been disposed.`);
         }
+        if (this.parentScope?.isDisposed()) {
+            throw new Error(`Parent scope "${this.parentScope.name}" of scope "${this.name}" has been disposed.`);
+        }
+        if (this.container.isDisposed()) {
+            throw new Error(`Container "${this.container.name}" owning scope "${this.name}" has been disposed.`);
+        }
     }
 }
 //# sourceMappingURL=containerCore.scope.js.map