@zudojs/container 1.1.0 → 1.1.2

package/README.md

@@ -2,6 +2,12 @@
 
 Token-based dependency injection container for managing application dependencies and service lifetimes.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-container](https://zudojs.oyinlola.site/docs/packages-container) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-container.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -71,7 +77,10 @@ not capture a shorter-lived dependency.
 
 `registerValue()` always registers as `SINGLETON`, overriding any
 `options.scope` you pass — a value provider can only ever return the one
-instance you gave it.
+instance you gave it. The container did not create that value, so it
+never disposes it: a pool or logger shared between containers, or owned
+by the host, stays open when a container is disposed. Register a factory
+instead when the container should own the instance.
 
 A `useExisting` alias never becomes a second owner of its target's instance:
 a `SINGLETON` or `SCOPED` target is disposed exactly once by whoever created
@@ -148,7 +157,12 @@ intentionally swap a registration.
 
 Replacing or removing a registration **evicts and disposes** its cached
 singleton — and evicts any cached `useExisting` alias of it — so the next
-`resolve()` of either token uses the new provider.
+`resolve()` of either token uses the new provider. Eviction cascades: every
+cached singleton that was built on the replaced token (directly or through
+a `TRANSIENT` in between) is evicted and disposed too, so consumers are
+rebuilt against the new instance instead of keeping the old, disposed one.
+Live scopes drop (and dispose) their cached `SCOPED` copies of the replaced
+token and of its consumers.
 
 `DuplicateRegistrationError`, `CircularDependencyError`,
 `RegistrationNotFoundError` and `ProviderResolutionError` are defined in
@@ -208,6 +222,7 @@ await container.dispose();
   have a `dispose()` method or implement `Symbol.dispose` /
   `Symbol.asyncDispose`.
 - `TRANSIENT` instances are never tracked; dispose them yourself.
+- `registerValue()` values are never disposed by the container.
 - With `autoDispose: false`, `dispose()` releases tracked references
   **without disposing them** — disposal becomes your responsibility.
 - Disposal is terminal: the container is marked disposed even if some

package/dist/containerCore/containerCore.core.d.ts

@@ -77,7 +77,10 @@ export declare class Container implements ContainerLike {
     getRegistration<T>(token: RegistrationToken<T>): ContainerRegistration<T> | undefined;
     replace<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     remove<T>(token: RegistrationToken<T>): boolean;
-    /** Removes every registration (evicting and disposing cached singletons). */
+    /**
+     * Removes every registration, evicting and disposing cached instances:
+     * container-owned singletons and every live scope's SCOPED copies alike.
+     */
     clearRegistrations(): void;
     createScope(options?: ContainerScopeOptions): ContainerScopeContext;
     getRegistrations(): readonly ContainerRegistration[];
@@ -91,8 +94,10 @@ export declare class Container implements ContainerLike {
     snapshot(): readonly ContainerRegistration[];
     /**
      * 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.
+     * Entries are validated, cached instances built from the old set are
+     * evicted and disposed — container-owned singletons and every live
+     * scope's SCOPED copies alike — and the operation is refused when
+     * registrations are frozen.
      */
     restoreSnapshot(registrations: readonly ContainerRegistration[]): void;
     isStarted(): boolean;

package/dist/containerCore/containerCore.core.js

@@ -19,7 +19,7 @@ import { ContainerResolver } from "../containerResolution/containerResolution.co
 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 { ContainerError, ContainerLifecycleError, RegistrationNotFoundError, } from "@zudojs/errors";
 import { ContainerScopeContext } from "./containerCore.scope.js";
 export class Container {
     name;
@@ -44,6 +44,11 @@ export class Container {
             void this.#lifecycle.disposeInstance(token).catch(() => {
                 /* see clearSingletons()/dispose() for error-surfacing disposal */
             });
+        }, (token) => {
+            // Live scopes would otherwise keep serving a replaced SCOPED
+            // instance, or one built on a replaced dependency.
+            for (const scope of this.#liveScopes)
+                scope.evictCached(token);
         });
     }
     /**
@@ -142,7 +147,10 @@ export class Container {
         this.ensureMutable();
         return this.#registry.remove(token);
     }
-    /** Removes every registration (evicting and disposing cached singletons). */
+    /**
+     * Removes every registration, evicting and disposing cached instances:
+     * container-owned singletons and every live scope's SCOPED copies alike.
+     */
     clearRegistrations() {
         this.ensureMutable();
         this.#registry.clear();
@@ -150,7 +158,7 @@ export class Container {
     createScope(options = {}) {
         this.ensureActive();
         if (!this.options.allowScopes)
-            throw new Error(`Container scopes are disabled for "${this.name}".`);
+            throw new ContainerError(`Container scopes are disabled for "${this.name}".`);
         const scope = new ContainerScopeContext(this, options);
         this.#liveScopes.add(scope);
         return scope;
@@ -177,8 +185,10 @@ export class Container {
     }
     /**
      * 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.
+     * Entries are validated, cached instances built from the old set are
+     * evicted and disposed — container-owned singletons and every live
+     * scope's SCOPED copies alike — and the operation is refused when
+     * registrations are frozen.
      */
     restoreSnapshot(registrations) {
         this.ensureMutable();
@@ -313,14 +323,14 @@ export class Container {
     }
     ensureNotDisposed() {
         if (this.#disposed)
-            throw new Error(`Container "${this.name}" has already been disposed.`);
+            throw new ContainerLifecycleError("dispose", `Container "${this.name}" has already been disposed.`);
     }
     ensureMutable() {
         this.ensureNotDisposed();
         if (!this.options.freezeRegistrations)
             return;
         if (this.#started)
-            throw new Error(`Registrations for container "${this.name}" are frozen.`);
+            throw new ContainerError(`Registrations for container "${this.name}" are frozen.`);
     }
 }
 export function createContainer(options = {}) {

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

@@ -17,6 +17,7 @@
  * ancestor (scope or container) is disposed.
  */
 import type { RegistrationToken, ResolvedTokens } from "../containerRegistration/containerRegistration.core.js";
+import type { Token } from "../containerToken/containerToken.type.js";
 import type { ContainerScopeOptions, ContainerLike } from "./containerCore.type.js";
 export declare class ContainerScopeContext {
     private disposed;
@@ -89,6 +90,12 @@ export declare class ContainerScopeContext {
      * Returns the container that owns the whole scope tree.
      */
     getContainer(): ContainerLike;
+    /**
+     * @internal Drops a cached SCOPED instance whose registration (or a
+     * dependency of it) was replaced or removed, disposing it best-effort,
+     * in this scope and every child scope.
+     */
+    evictCached(token: Token): void;
     /** @internal Detaches a disposed child scope. */
     releaseChild(scope: ContainerScopeContext): void;
     /**

package/dist/containerCore/containerCore.scope.js

@@ -18,6 +18,7 @@
  */
 import { ContainerLifecycle, ContainerLifecycleOwner, } from "../containerLifecycle/containerLifecycle.core.js";
 import { ContainerScope } from "../containerScope/containerScope.type.js";
+import { ContainerLifecycleError } from "@zudojs/errors";
 export class ContainerScopeContext {
     disposed = false;
     disposing;
@@ -156,6 +157,19 @@ export class ContainerScopeContext {
     getContainer() {
         return this.container;
     }
+    /**
+     * @internal Drops a cached SCOPED instance whose registration (or a
+     * dependency of it) was replaced or removed, disposing it best-effort,
+     * in this scope and every child scope.
+     */
+    evictCached(token) {
+        if (this.disposed)
+            return;
+        this.cache.delete?.(token);
+        void this.lifecycle.disposeInstance(token).catch(() => undefined);
+        for (const child of this.children)
+            child.evictCached(token);
+    }
     /** @internal Detaches a disposed child scope. */
     releaseChild(scope) {
         this.children.delete(scope);
@@ -176,13 +190,13 @@ export class ContainerScopeContext {
      */
     ensureActive() {
         if (this.disposed) {
-            throw new Error(`Container scope "${this.name}" has already been disposed.`);
+            throw new ContainerLifecycleError("dispose", `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.`);
+            throw new ContainerLifecycleError("dispose", `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.`);
+            throw new ContainerLifecycleError("dispose", `Container "${this.container.name}" owning scope "${this.name}" has been disposed.`);
         }
     }
 }

package/dist/containerResolution/containerResolution.core.d.ts

@@ -22,7 +22,10 @@
  * The resolver subscribes to registry change events: REPLACE/REMOVE evict the
  * affected token's cached singleton, CLEAR/RESTORE evict all cached
  * singletons. Each eviction is reported through the `onSingletonEvicted`
- * callback so the owning container can dispose the instance.
+ * callback so the owning container can dispose the instance, and every
+ * invalidated token — for CLEAR/RESTORE that is every cached token, SCOPED
+ * ones included — through `onTokenInvalidated` so live scopes drop and
+ * dispose their own copies.
  */
 import type { RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
 import type { ContainerRegistry } from "../containerRegistry/containerRegistry.core.js";
@@ -32,7 +35,28 @@ export declare class ContainerResolver {
     private readonly registry;
     private readonly singletonCache;
     private readonly onSingletonEvicted;
-    constructor(registry: ContainerRegistry, onSingletonEvicted?: (token: Token<unknown>) => void);
+    private readonly onTokenInvalidated;
+    private readonly dependents;
+    /**
+     * Tokens for which a SCOPED instance has ever been cached in a scope.
+     *
+     * The singleton cache only knows about SINGLETON tokens and the
+     * dependent index only records tokens consumed by another cached
+     * instance, so neither can name a SCOPED token that a scope resolved
+     * directly. A wholesale CLEAR/RESTORE must still tell live scopes to
+     * drop those instances.
+     */
+    private readonly scopedTokens;
+    /**
+     * @param onSingletonEvicted Called for each evicted cached singleton so
+     *   the owner can dispose it.
+     * @param onTokenInvalidated Called for every token invalidated by a
+     *   registry change — for `replace()`/`remove()` the token itself and
+     *   each cached consumer, for `clear()`/`restore()` every token that
+     *   was cached at all — so owners of scope caches can drop and dispose
+     *   their SCOPED copies.
+     */
+    constructor(registry: ContainerRegistry, onSingletonEvicted?: (token: Token<unknown>) => void, onTokenInvalidated?: (token: Token<unknown>) => void);
     resolve<T>(token: RegistrationToken<T>, options?: ResolutionOptions): T;
     resolveDetailed<T>(token: RegistrationToken<T>, options?: ResolutionOptions): ResolutionResult<T>;
     private resolveInternal;

package/dist/containerResolution/containerResolution.core.js

@@ -22,16 +22,20 @@
  * The resolver subscribes to registry change events: REPLACE/REMOVE evict the
  * affected token's cached singleton, CLEAR/RESTORE evict all cached
  * singletons. Each eviction is reported through the `onSingletonEvicted`
- * callback so the owning container can dispose the instance.
+ * callback so the owning container can dispose the instance, and every
+ * invalidated token — for CLEAR/RESTORE that is every cached token, SCOPED
+ * ones included — through `onTokenInvalidated` so live scopes drop and
+ * dispose their own copies.
  */
 import { isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider, normalizeProvider, } from "../containerProvider/containerProvider.core.js";
 import { ContainerScope as Scope } from "../containerScope/containerScope.type.js";
 import { defineRegistration, getRegistrationToken, } from "../containerRegistration/containerRegistration.core.js";
 import { RegistryOperation } from "../containerRegistry/containerRegistry.type.js";
 import { unwrapToken } from "../containerToken/containerToken.type.js";
-import { CircularDependencyError, ProviderResolutionError, RegistrationNotFoundError, } from "@zudojs/errors";
+import { CircularDependencyError, ContainerError, ProviderResolutionError, RegistrationNotFoundError, } from "@zudojs/errors";
 import { AsyncProviderError, CaptiveDependencyError, DependencyResolutionError, MaxResolutionDepthError, ScopedResolutionError, } from "./containerResolution.error.js";
 import { describeToken } from "../containerToken/containerToken.type.js";
+import { DependentIndex } from "./containerResolution.dependents.js";
 /**
  * Scope cache that falls back to its parent scope's cache for lookups while
  * writing only to its own map. Nested scopes therefore see SCOPED instances
@@ -55,6 +59,9 @@ class ChainedResolutionCache {
     set(token, value) {
         this.#own.set(token, value);
     }
+    delete(token) {
+        return this.#own.delete(token);
+    }
     clear() {
         this.#own.clear();
     }
@@ -63,9 +70,31 @@ export class ContainerResolver {
     registry;
     singletonCache = new Map();
     onSingletonEvicted;
-    constructor(registry, onSingletonEvicted) {
+    onTokenInvalidated;
+    dependents = new DependentIndex();
+    /**
+     * Tokens for which a SCOPED instance has ever been cached in a scope.
+     *
+     * The singleton cache only knows about SINGLETON tokens and the
+     * dependent index only records tokens consumed by another cached
+     * instance, so neither can name a SCOPED token that a scope resolved
+     * directly. A wholesale CLEAR/RESTORE must still tell live scopes to
+     * drop those instances.
+     */
+    scopedTokens = new Set();
+    /**
+     * @param onSingletonEvicted Called for each evicted cached singleton so
+     *   the owner can dispose it.
+     * @param onTokenInvalidated Called for every token invalidated by a
+     *   registry change — for `replace()`/`remove()` the token itself and
+     *   each cached consumer, for `clear()`/`restore()` every token that
+     *   was cached at all — so owners of scope caches can drop and dispose
+     *   their SCOPED copies.
+     */
+    constructor(registry, onSingletonEvicted, onTokenInvalidated) {
         this.registry = registry;
         this.onSingletonEvicted = onSingletonEvicted;
+        this.onTokenInvalidated = onTokenInvalidated;
         registry.subscribe((event) => this.handleRegistryChange(event));
     }
     resolve(token, options = {}) {
@@ -108,6 +137,7 @@ export class ContainerResolver {
             }
         }
         const currentPath = [...state.path, token];
+        this.dependents.record(token, state.path, (t) => this.registry.get(t)?.scope);
         if (registration.scope === Scope.SINGLETON) {
             if (this.singletonCache.has(token)) {
                 return {
@@ -150,8 +180,11 @@ export class ContainerResolver {
         }
         if (registration.scope === Scope.SINGLETON)
             this.singletonCache.set(token, value);
-        else if (registration.scope === Scope.SCOPED)
+        else if (registration.scope === Scope.SCOPED) {
             state.scopeCache?.set(token, value);
+            if (state.scopeCache)
+                this.scopedTokens.add(token);
+        }
         const result = {
             value,
             token,
@@ -173,14 +206,17 @@ export class ContainerResolver {
         const provider = normalizeProvider(registration.provider);
         const token = getRegistrationToken(registration);
         try {
+            // A pre-built value belongs to whoever built it (often shared
+            // between containers); the container did not create it, so it
+            // must not dispose it.
             if (isValueProvider(provider))
-                return { value: provider.useValue, owned: true };
+                return { value: provider.useValue, owned: false };
             if (isExistingProvider(provider)) {
                 const target = unwrapToken(provider.useExisting);
                 if (!this.registry.has(target) &&
                     !(state.autoRegisterClasses && typeof target === "function")) {
-                    throw new Error(`useExisting target "${describeToken(target)}" for token ` +
-                        `"${describeToken(token)}" is not registered.`);
+                    throw new ContainerError(`useExisting target "${describeToken(target)}" for token ` +
+                        `"${describeToken(token)}" is not registered.`, { token: describeToken(token) });
                 }
                 const resolved = this.resolveInternal(target, state, singletonAncestor);
                 // Only a TRANSIENT target has no owner of its own; a cached alias
@@ -206,7 +242,9 @@ export class ContainerResolver {
                 const ctor = provider.useClass;
                 return { value: new ctor(...args), owned: true };
             }
-            throw new Error("Unsupported container provider.");
+            throw new ContainerError("Unsupported container provider.", {
+                token: describeToken(token),
+            });
         }
         catch (error) {
             // Resolution errors created deeper in the chain already carry the full
@@ -252,14 +290,33 @@ export class ContainerResolver {
             case RegistryOperation.REPLACE:
             case RegistryOperation.REMOVE: {
                 const token = unwrapToken(event.token);
+                // Consumers first, so each is disposed before what it consumed.
+                for (const dependent of this.dependents.take(token)) {
+                    this.evictSingleton(dependent);
+                    this.onTokenInvalidated?.(dependent);
+                }
                 this.evictSingleton(token);
                 this.evictAliasesOf(token);
+                this.onTokenInvalidated?.(token);
                 break;
             }
             case RegistryOperation.CLEAR:
             case RegistryOperation.RESTORE: {
+                // Every cached token is discarded by a wholesale change, so every
+                // one of them must be reported as invalidated — not just the
+                // singletons. Only REPLACE/REMOVE used to notify, so a live scope
+                // went on serving (and never disposed) the SCOPED instance built
+                // from a registration that clear()/restore() had thrown away.
+                const invalidated = new Set([
+                    ...this.singletonCache.keys(),
+                    ...this.scopedTokens,
+                ]);
                 for (const t of [...this.singletonCache.keys()])
                     this.evictSingleton(t);
+                this.dependents.clear();
+                this.scopedTokens.clear();
+                for (const t of invalidated)
+                    this.onTokenInvalidated?.(t);
                 break;
             }
             default:

package/dist/containerResolution/containerResolution.dependents.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reverse dependency index for cached container instances.
+ *
+ * `replace()`/`remove()` used to evict only the changed token, so a
+ * singleton that had already captured it kept serving the old — by then
+ * disposed — instance. Recording which cached instance consumed which
+ * token lets eviction cascade to every consumer.
+ */
+import { ContainerScope as Scope } from "../containerScope/containerScope.type.js";
+import type { Token } from "../containerToken/containerToken.type.js";
+/** Looks up the lifetime of a registered token. */
+export type LifetimeLookup = (token: Token<unknown>) => Scope | undefined;
+/**
+ * Maps a token to the cached (SINGLETON or SCOPED) instances whose
+ * construction resolved it.
+ */
+export declare class DependentIndex {
+    #private;
+    /**
+     * Records that the nearest cached ancestor on `path` depends on
+     * `token`. Transient ancestors are skipped: they are rebuilt on every
+     * resolution, so the cached instance above them is the real consumer.
+     */
+    record(token: Token<unknown>, path: readonly Token<unknown>[], lifetimeOf: LifetimeLookup): void;
+    /**
+     * Returns every token that transitively depends on `token`, nearest
+     * consumers last, and forgets them.
+     */
+    take(token: Token<unknown>): readonly Token<unknown>[];
+    /** Forgets every recorded dependency. */
+    clear(): void;
+}
+//# sourceMappingURL=containerResolution.dependents.d.ts.map

package/dist/containerResolution/containerResolution.dependents.js

@@ -0,0 +1,66 @@
+/**
+ * Reverse dependency index for cached container instances.
+ *
+ * `replace()`/`remove()` used to evict only the changed token, so a
+ * singleton that had already captured it kept serving the old — by then
+ * disposed — instance. Recording which cached instance consumed which
+ * token lets eviction cascade to every consumer.
+ */
+import { ContainerScope as Scope } from "../containerScope/containerScope.type.js";
+/**
+ * Maps a token to the cached (SINGLETON or SCOPED) instances whose
+ * construction resolved it.
+ */
+export class DependentIndex {
+    #dependents = new Map();
+    /**
+     * Records that the nearest cached ancestor on `path` depends on
+     * `token`. Transient ancestors are skipped: they are rebuilt on every
+     * resolution, so the cached instance above them is the real consumer.
+     */
+    record(token, path, lifetimeOf) {
+        for (let i = path.length - 1; i >= 0; i--) {
+            const owner = path[i];
+            const lifetime = lifetimeOf(owner);
+            if (lifetime === Scope.SINGLETON || lifetime === Scope.SCOPED) {
+                if (owner === token)
+                    return;
+                let set = this.#dependents.get(token);
+                if (set === undefined) {
+                    set = new Set();
+                    this.#dependents.set(token, set);
+                }
+                set.add(owner);
+                return;
+            }
+        }
+    }
+    /**
+     * Returns every token that transitively depends on `token`, nearest
+     * consumers last, and forgets them.
+     */
+    take(token) {
+        const ordered = [];
+        const visited = new Set([token]);
+        const visit = (current) => {
+            const direct = this.#dependents.get(current);
+            this.#dependents.delete(current);
+            if (direct === undefined)
+                return;
+            for (const dependent of direct) {
+                if (visited.has(dependent))
+                    continue;
+                visited.add(dependent);
+                visit(dependent);
+                ordered.push(dependent);
+            }
+        };
+        visit(token);
+        return ordered;
+    }
+    /** Forgets every recorded dependency. */
+    clear() {
+        this.#dependents.clear();
+    }
+}
+//# sourceMappingURL=containerResolution.dependents.js.map

package/dist/containerResolution/containerResolution.type.d.ts

@@ -15,6 +15,8 @@ export interface ResolutionCache {
     has(token: Token<unknown>): boolean;
     get(token: Token<unknown>): unknown;
     set(token: Token<unknown>, value: unknown): void;
+    /** Drops one entry from this cache (not its parents). Optional. */
+    delete?(token: Token<unknown>): boolean;
     clear(): void;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/container",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Token-based dependency injection container for managing application dependencies and service lifetimes.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",