@zudojs/container 1.0.0 → 1.1.0

package/README.md

@@ -73,6 +73,12 @@ not capture a shorter-lived dependency.
 `options.scope` you pass — a value provider can only ever return the one
 instance you gave it.
 
+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
 resolution — not just the value returned by the `resolve()` call.
@@ -141,7 +147,13 @@ 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.
+
+`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
 
@@ -201,6 +213,10 @@ await container.dispose();
 - 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;
@@ -221,10 +222,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 +262,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

@@ -20,6 +20,7 @@ import type { RegistrationToken, ResolvedTokens } from "../containerRegistration
 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 +71,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.
      */

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 {

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

@@ -54,5 +54,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

@@ -140,8 +140,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,7 +160,13 @@ 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) {
@@ -167,7 +174,7 @@ export class ContainerResolver {
         const token = getRegistrationToken(registration);
         try {
             if (isValueProvider(provider))
-                return provider.useValue;
+                return { value: provider.useValue, owned: true };
             if (isExistingProvider(provider)) {
                 const target = unwrapToken(provider.useExisting);
                 if (!this.registry.has(target) &&
@@ -175,8 +182,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 +197,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,7 +251,9 @@ export class ContainerResolver {
         switch (event.operation) {
             case RegistryOperation.REPLACE:
             case RegistryOperation.REMOVE: {
-                this.evictSingleton(unwrapToken(event.token));
+                const token = unwrapToken(event.token);
+                this.evictSingleton(token);
+                this.evictAliasesOf(token);
                 break;
             }
             case RegistryOperation.CLEAR:
@@ -258,6 +272,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/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.0",
   "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.0.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "publishConfig": {
     "access": "public"
   },