@zudojs/container 1.1.0 → 1.1.1

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.js

@@ -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);
         });
     }
     /**

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

@@ -156,6 +156,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);

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

@@ -32,7 +32,16 @@ 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;
+    /**
+     * @param onSingletonEvicted Called for each evicted cached singleton so
+     *   the owner can dispose it.
+     * @param onTokenInvalidated Called for every token invalidated by a
+     *   `replace()`/`remove()` (the token itself and each cached consumer),
+     *   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

@@ -32,6 +32,7 @@ import { unwrapToken } from "../containerToken/containerToken.type.js";
 import { CircularDependencyError, 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 +56,9 @@ class ChainedResolutionCache {
     set(token, value) {
         this.#own.set(token, value);
     }
+    delete(token) {
+        return this.#own.delete(token);
+    }
     clear() {
         this.#own.clear();
     }
@@ -63,9 +67,19 @@ export class ContainerResolver {
     registry;
     singletonCache = new Map();
     onSingletonEvicted;
-    constructor(registry, onSingletonEvicted) {
+    onTokenInvalidated;
+    dependents = new DependentIndex();
+    /**
+     * @param onSingletonEvicted Called for each evicted cached singleton so
+     *   the owner can dispose it.
+     * @param onTokenInvalidated Called for every token invalidated by a
+     *   `replace()`/`remove()` (the token itself and each cached consumer),
+     *   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 +122,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 {
@@ -173,8 +188,11 @@ 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) &&
@@ -252,14 +270,21 @@ 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: {
                 for (const t of [...this.singletonCache.keys()])
                     this.evictSingleton(t);
+                this.dependents.clear();
                 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.1",
   "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.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",