@zudojs/container 1.0.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,16 @@ 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
+it, and a `SCOPED` alias of a `SINGLETON` leaves the singleton alive when the
+scope is disposed. Only a `TRANSIENT` target captured by a cached alias is
+tracked (and disposed) through the alias.
 
 Tracking covers **every** `SINGLETON`/`SCOPED` instance the container
 creates — including ones created transitively as dependencies of another
@@ -141,7 +156,18 @@ which case the later registration wins. Use `container.replace()` to
 intentionally swap a registration.
 
 Replacing or removing a registration **evicts and disposes** its cached
-singleton, so the next `resolve()` uses the new provider.
+singleton — and evicts any cached `useExisting` alias of it — so the next
+`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
+`@zudojs/errors` and re-exported from this package, so `instanceof` checks
+need only one import.
 
 ## Resolution options
 
@@ -196,11 +222,16 @@ 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
   instances fail to dispose, and every failure is reported in the thrown
   `AggregateError`. `dispose()` is idempotent; any use after disposal throws.
+  The container counts as disposed from the moment `dispose()` is called —
+  a `resolve()` racing the disposal throws rather than creating an instance
+  nobody will clean up — and concurrent `dispose()` calls all settle when
+  the one disposal finishes.
 - `clearSingletons()` evicts and disposes cached singletons without
   disposing the container.
 

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

@@ -114,8 +114,15 @@ export declare class Container implements ContainerLike {
      * Disposal is terminal: the container is marked disposed even when some
      * instances fail to dispose; every failure is reported in the thrown
      * AggregateError. Idempotent.
+     *
+     * The container is marked disposed *before* any cleanup runs, so a
+     * `resolve()` racing the disposal throws instead of creating a singleton
+     * that would be tracked after the disposal snapshot and then silently
+     * dropped. Concurrent `dispose()` calls share the in-flight disposal and
+     * settle only when it has finished.
      */
     dispose(): Promise<void>;
+    private runDispose;
     get resolutionOptions(): {
         autoRegisterClasses: boolean;
         detectCircularDependencies: boolean;

package/dist/containerCore/containerCore.core.js

@@ -30,6 +30,7 @@ export class Container {
     #liveScopes = new Set();
     #started = false;
     #disposed = false;
+    #disposing;
     constructor(options = {}) {
         this.options = resolveContainerOptions(options);
         this.name = this.options.name;
@@ -43,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);
         });
     }
     /**
@@ -221,10 +227,26 @@ export class Container {
      * Disposal is terminal: the container is marked disposed even when some
      * instances fail to dispose; every failure is reported in the thrown
      * AggregateError. Idempotent.
+     *
+     * The container is marked disposed *before* any cleanup runs, so a
+     * `resolve()` racing the disposal throws instead of creating a singleton
+     * that would be tracked after the disposal snapshot and then silently
+     * dropped. Concurrent `dispose()` calls share the in-flight disposal and
+     * settle only when it has finished.
      */
-    async dispose() {
+    dispose() {
+        if (this.#disposing)
+            return this.#disposing;
         if (this.#disposed)
-            return;
+            return Promise.resolve();
+        this.#disposed = true;
+        this.#started = false;
+        this.#disposing = this.runDispose().finally(() => {
+            this.#disposing = undefined;
+        });
+        return this.#disposing;
+    }
+    async runDispose() {
         const failures = [];
         for (const scope of [...this.#liveScopes]) {
             try {
@@ -245,8 +267,6 @@ export class Container {
         }
         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.`);
     }

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

@@ -17,9 +17,11 @@
  * 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;
+    private disposing;
     private readonly cache;
     private readonly lifecycle;
     private readonly container;
@@ -70,9 +72,11 @@ export declare class ContainerScopeContext {
      * 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.
+     * an AggregateError listing the failures is thrown afterwards. Concurrent
+     * callers share the in-flight disposal rather than returning early.
      */
     dispose(): Promise<void>;
+    private runDispose;
     /**
      * Returns whether the scope has been disposed.
      */
@@ -86,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

@@ -20,6 +20,7 @@ import { ContainerLifecycle, ContainerLifecycleOwner, } from "../containerLifecy
 import { ContainerScope } from "../containerScope/containerScope.type.js";
 export class ContainerScopeContext {
     disposed = false;
+    disposing;
     cache;
     lifecycle;
     container;
@@ -94,12 +95,21 @@ export class ContainerScopeContext {
      * 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.
+     * an AggregateError listing the failures is thrown afterwards. Concurrent
+     * callers share the in-flight disposal rather than returning early.
      */
-    async dispose() {
+    dispose() {
+        if (this.disposing)
+            return this.disposing;
         if (this.disposed)
-            return;
+            return Promise.resolve();
         this.disposed = true;
+        this.disposing = this.runDispose().finally(() => {
+            this.disposing = undefined;
+        });
+        return this.disposing;
+    }
+    async runDispose() {
         const failures = [];
         for (const child of [...this.children].reverse()) {
             try {
@@ -146,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/containerLifecycle/containerLifecycle.core.js

@@ -120,6 +120,10 @@ export class ContainerLifecycle {
     async dispose(owner) {
         if (this.disposed)
             return;
+        // Mark before the first await: an instance tracked while disposal is in
+        // flight would be dropped by `shutdown()` without ever being disposed.
+        if (owner === undefined)
+            this.disposed = true;
         const tracked = [...this.instances.values()].reverse();
         const selected = owner
             ? tracked.filter((entry) => entry.owner === owner)
@@ -141,8 +145,6 @@ export class ContainerLifecycle {
                     break;
             }
         }
-        if (owner === undefined)
-            this.disposed = true;
         if (errors.length > 0)
             throw new ContainerDisposalError(errors, failedTokens);
     }

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;
@@ -54,5 +63,14 @@ export declare class ContainerResolver {
     canResolve<T>(token: RegistrationToken<T>, autoRegisterClasses?: boolean): boolean;
     private handleRegistryChange;
     private evictSingleton;
+    /**
+     * Evicts every cached singleton whose `useExisting` chain ends at `target`.
+     *
+     * A cached alias holds the target's instance under its own token, so
+     * evicting the target alone left the alias serving the old — by now
+     * disposed — instance after `replace()`/`remove()`.
+     */
+    private evictAliasesOf;
+    private aliasChainReaches;
 }
 //# sourceMappingURL=containerResolution.core.d.ts.map

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 {
@@ -140,8 +155,9 @@ export class ContainerResolver {
         state.path.push(token);
         state.pathSet.add(token);
         let value;
+        let owned;
         try {
-            value = this.createInstance(registration, state, nextAncestor);
+            ({ value, owned } = this.createInstance(registration, state, nextAncestor));
         }
         finally {
             state.path.pop();
@@ -159,15 +175,24 @@ export class ContainerResolver {
             fromCache: false,
             path: currentPath,
         };
-        state.onInstanceCreated?.(result);
+        // A `useExisting` alias of a cached (SINGLETON/SCOPED) target does not
+        // own the instance it hands out — the target's own creation already
+        // reported it. Reporting it again registered a second owner for the same
+        // object: the container disposed it twice, and a SCOPED alias let a
+        // scope dispose a container-owned singleton.
+        if (owned)
+            state.onInstanceCreated?.(result);
         return result;
     }
     createInstance(registration, state, singletonAncestor) {
         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 provider.useValue;
+                return { value: provider.useValue, owned: false };
             if (isExistingProvider(provider)) {
                 const target = unwrapToken(provider.useExisting);
                 if (!this.registry.has(target) &&
@@ -175,8 +200,13 @@ export class ContainerResolver {
                     throw new Error(`useExisting target "${describeToken(target)}" for token ` +
                         `"${describeToken(token)}" is not registered.`);
                 }
-                return this.resolveInternal(target, state, singletonAncestor)
-                    .value;
+                const resolved = this.resolveInternal(target, state, singletonAncestor);
+                // Only a TRANSIENT target has no owner of its own; a cached alias
+                // of it is the one place the instance can be tracked.
+                return {
+                    value: resolved.value,
+                    owned: resolved.scope === Scope.TRANSIENT,
+                };
             }
             if (isFactoryProvider(provider)) {
                 const deps = provider.inject ?? [];
@@ -185,14 +215,14 @@ export class ContainerResolver {
                 const produced = provider.useFactory(...args);
                 if (registration.scope !== Scope.TRANSIENT && isPromiseLike(produced))
                     throw new AsyncProviderError(describeToken(token), registration.scope);
-                return produced;
+                return { value: produced, owned: true };
             }
             if (isClassProvider(provider)) {
                 const deps = provider.inject ?? [];
                 const args = deps.map((d) => this.resolveInternal(unwrapToken(d), state, singletonAncestor)
                     .value);
                 const ctor = provider.useClass;
-                return new ctor(...args);
+                return { value: new ctor(...args), owned: true };
             }
             throw new Error("Unsupported container provider.");
         }
@@ -239,13 +269,22 @@ export class ContainerResolver {
         switch (event.operation) {
             case RegistryOperation.REPLACE:
             case RegistryOperation.REMOVE: {
-                this.evictSingleton(unwrapToken(event.token));
+                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:
@@ -258,6 +297,40 @@ export class ContainerResolver {
         this.singletonCache.delete(token);
         this.onSingletonEvicted?.(token);
     }
+    /**
+     * Evicts every cached singleton whose `useExisting` chain ends at `target`.
+     *
+     * A cached alias holds the target's instance under its own token, so
+     * evicting the target alone left the alias serving the old — by now
+     * disposed — instance after `replace()`/`remove()`.
+     */
+    evictAliasesOf(target) {
+        for (const cached of [...this.singletonCache.keys()]) {
+            if (cached === target)
+                continue;
+            if (this.aliasChainReaches(cached, target))
+                this.evictSingleton(cached);
+        }
+    }
+    aliasChainReaches(token, target) {
+        const visited = new Set();
+        let current = token;
+        for (;;) {
+            const registration = this.registry.get(current);
+            if (!registration)
+                return false;
+            const provider = normalizeProvider(registration.provider);
+            if (!isExistingProvider(provider))
+                return false;
+            const next = unwrapToken(provider.useExisting);
+            if (next === target)
+                return true;
+            if (visited.has(next))
+                return false;
+            visited.add(next);
+            current = next;
+        }
+    }
 }
 function isPromiseLike(value) {
     return (typeof value === "object" &&

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/dist/index.d.ts

@@ -12,4 +12,5 @@ export * from "./containerRegistry/index.js";
 export * from "./containerResolution/index.js";
 export * from "./containerScope/index.js";
 export * from "./containerToken/index.js";
+export { CircularDependencyError, DuplicateRegistrationError, RegistrationNotFoundError, ProviderResolutionError, } from "@zudojs/errors";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -12,4 +12,7 @@ export * from "./containerRegistry/index.js";
 export * from "./containerResolution/index.js";
 export * from "./containerScope/index.js";
 export * from "./containerToken/index.js";
+// Error classes the container throws but that live in @zudojs/errors,
+// re-exported so `instanceof` checks need only this package.
+export { CircularDependencyError, DuplicateRegistrationError, RegistrationNotFoundError, ProviderResolutionError, } from "@zudojs/errors";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/container",
-  "version": "1.0.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,13 +18,17 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "publishConfig": {
     "access": "public"
   },