@zudojs/container 1.1.1 → 1.2.0

package/README.md

@@ -47,6 +47,21 @@ container.registerFactory(API, (db) => new Api(db), [DB]); // deps via inject li
 container.registerExisting("db-alias", DB); // alias to another token
 ```
 
+A factory's parameters are typed from its `inject` list, in order: with
+`DB = createToken<Db>("Db")`, `(db) => new Api(db)` receives `db: Db`, and a
+factory whose parameters do not match the tokens is a compile error. Class
+tokens type the same way; plain string and symbol tokens give `unknown`.
+`factoryProvider(factory, inject)` and `provideFactory(token, factory,
+inject)` infer the same way.
+
+```typescript
+container.registerFactory(
+  REPORT,
+  (db, clock) => new Report(db, clock), // db: Db, clock: Clock
+  [DB, Clock],
+);
+```
+
 ## Tokens
 
 Tokens can be strings, symbols, classes, or `InjectionToken`s from
@@ -58,6 +73,9 @@ Tokens can be strings, symbols, classes, or `InjectionToken`s from
 - `createGlobalToken(key)` uses `Symbol.for(key)`: any other call with the
   same key anywhere in the process yields the **same** token. That is by
   design for cross-package sharing; namespace your keys (e.g. `"myapp:db"`).
+- Error messages and default registration names show a symbol token by its
+  description: `createToken<Db>("Database")` appears as `Database`, not
+  `Symbol(Database)` (`describeToken(token)` returns the same string).
 
 ## Lifetimes (`scope` option)
 
@@ -185,7 +203,13 @@ const container = createContainer({
   registers it on the fly as `TRANSIENT`. When registrations are frozen the
   class is instantiated _ephemerally_ without being registered. Set to
   `false` to require explicit registration (`canResolve`/`resolveOptional`
-  respect this).
+  respect this). Only a class whose constructor declares no required
+  parameters (`Class.length === 0`) is auto-registered: auto-registration
+  has no inject list, so `resolve(NeedsDep)` for
+  `constructor(dep: Dep)` throws `RegistrationNotFoundError` naming the
+  class and telling you to register it with an `inject` list, instead of
+  building it with `dep = undefined`. Parameters with defaults do not
+  count.
 - `detectCircularDependencies` — circular chains throw
   `CircularDependencyError` with the full chain. When disabled,
   `maxResolutionDepth` still stops runaway recursion.

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

@@ -12,7 +12,7 @@
  * - TRANSIENT instances are never cached and never tracked — callers own
  *   their disposal.
  */
-import type { ContainerProvider, ProviderToken } from "../containerProvider/containerProvider.core.js";
+import type { ContainerProvider, InjectedFactory, ProviderToken } from "../containerProvider/containerProvider.core.js";
 import type { ContainerRegistration, CreateRegistrationOptions, RegistrationToken, ResolvedTokens } from "../containerRegistration/containerRegistration.core.js";
 import type { ResolutionCache, ResolutionResult } from "../containerResolution/containerResolution.type.js";
 import type { ContainerOptions, ResolvedContainerOptions } from "../containerOptions/containerOptions.type.js";
@@ -51,7 +51,14 @@ export declare class Container implements ContainerLike {
      * any other lifetime would be misleading.
      */
     registerValue<T>(token: RegistrationToken<T>, value: T, options?: CreateRegistrationOptions): ContainerRegistration<T>;
-    registerFactory<T>(token: RegistrationToken<T>, factory: (...deps: unknown[]) => T, inject?: readonly ProviderToken[], options?: CreateRegistrationOptions): ContainerRegistration<T>;
+    /**
+     * Registers a factory. Its parameters are typed from the `inject` tokens,
+     * in order: `registerFactory(API, (db) => new Api(db), [DB])` types `db`
+     * as `Db` when `DB` is a `createToken<Db>()` or class token, and rejects a
+     * factory whose parameters do not match. String/symbol tokens give
+     * `unknown`.
+     */
+    registerFactory<T, const Deps extends readonly ProviderToken[] = readonly []>(token: RegistrationToken<T>, factory: InjectedFactory<T, Deps>, inject?: Deps, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     registerExisting<T>(token: RegistrationToken<T>, existing: ProviderToken<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     /**
      * Resolves a dependency at the container root.
@@ -77,7 +84,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 +101,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;
@@ -87,6 +87,13 @@ export class Container {
             scope: Scope.SINGLETON,
         });
     }
+    /**
+     * Registers a factory. Its parameters are typed from the `inject` tokens,
+     * in order: `registerFactory(API, (db) => new Api(db), [DB])` types `db`
+     * as `Db` when `DB` is a `createToken<Db>()` or class token, and rejects a
+     * factory whose parameters do not match. String/symbol tokens give
+     * `unknown`.
+     */
     registerFactory(token, factory, inject = [], options = {}) {
         return this.register(token, factoryProvider(factory, inject), options);
     }
@@ -147,7 +154,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();
@@ -155,7 +165,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;
@@ -182,8 +192,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();
@@ -318,14 +330,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.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;
@@ -189,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/containerProvider/containerProvider.core.d.ts

@@ -4,6 +4,17 @@
  */
 import type { Constructor, InjectionToken, Token } from "../containerToken/containerToken.type.js";
 export type ProviderToken<T = unknown> = Token<T> | InjectionToken<T>;
+/**
+ * The parameter list a factory receives for an `inject` list: each token is
+ * mapped to the type it resolves to, so `[DB, Clock]` gives `[Db, Clock]`.
+ * Untyped string/symbol tokens map to `unknown`, and a non-tuple
+ * `readonly ProviderToken[]` gives `unknown[]`, as before.
+ */
+export type InjectedDependencies<Deps extends readonly ProviderToken[]> = {
+    -readonly [K in keyof Deps]: Deps[K] extends ProviderToken<infer U> ? U : never;
+};
+/** A factory whose parameters are typed from its `inject` list. */
+export type InjectedFactory<T, Deps extends readonly ProviderToken[]> = (...dependencies: InjectedDependencies<Deps>) => T;
 export interface ClassProvider<T> {
     readonly useClass: Constructor<T>;
     /**
@@ -55,11 +66,19 @@ export declare function hasInjectedDependencies<T = unknown>(provider: Provider<
     readonly inject: readonly ProviderToken[];
 };
 export declare function classProvider<T>(useClass: Constructor<T>, inject?: readonly ProviderToken[]): ClassProvider<T>;
-export declare function factoryProvider<T>(useFactory: (...dependencies: unknown[]) => T, inject?: readonly ProviderToken[]): FactoryProvider<T>;
+/**
+ * Builds a factory provider. The factory's parameters are inferred from the
+ * `inject` tokens, in order.
+ */
+export declare function factoryProvider<T, const Deps extends readonly ProviderToken[] = readonly []>(useFactory: InjectedFactory<T, Deps>, inject?: Deps): FactoryProvider<T>;
 export declare function valueProvider<T>(useValue: T): ValueProvider<T>;
 export declare function existingProvider<T>(useExisting: ProviderToken<T>): ExistingProvider<T>;
 export declare function provideClass<T>(provide: ProviderToken<T>, useClass: Constructor<T>, inject?: readonly ProviderToken[]): ClassRegistration<T>;
-export declare function provideFactory<T>(provide: ProviderToken<T>, useFactory: (...dependencies: unknown[]) => T, inject?: readonly ProviderToken[]): FactoryRegistration<T>;
+/**
+ * Builds a factory registration. The factory's parameters are inferred from
+ * the `inject` tokens, in order.
+ */
+export declare function provideFactory<T, const Deps extends readonly ProviderToken[] = readonly []>(provide: ProviderToken<T>, useFactory: InjectedFactory<T, Deps>, inject?: Deps): FactoryRegistration<T>;
 export declare function provideValue<T>(provide: ProviderToken<T>, useValue: T): ValueRegistration<T>;
 export declare function provideExisting<T>(provide: ProviderToken<T>, useExisting: ProviderToken<T>): ExistingRegistration<T>;
 export declare function getProviderToken<T>(provider: ContainerProvider<T>): ProviderToken<T> | undefined;

package/dist/containerProvider/containerProvider.core.js

@@ -25,8 +25,15 @@ export function hasInjectedDependencies(provider) {
 export function classProvider(useClass, inject = []) {
     return Object.freeze({ useClass, inject: Object.freeze([...inject]) });
 }
+/**
+ * Builds a factory provider. The factory's parameters are inferred from the
+ * `inject` tokens, in order.
+ */
 export function factoryProvider(useFactory, inject = []) {
-    return Object.freeze({ useFactory, inject: Object.freeze([...inject]) });
+    return Object.freeze({
+        useFactory: useFactory,
+        inject: Object.freeze([...inject]),
+    });
 }
 export function valueProvider(useValue) {
     return Object.freeze({ useValue });
@@ -41,10 +48,14 @@ export function provideClass(provide, useClass, inject = []) {
         inject: Object.freeze([...inject]),
     });
 }
+/**
+ * Builds a factory registration. The factory's parameters are inferred from
+ * the `inject` tokens, in order.
+ */
 export function provideFactory(provide, useFactory, inject = []) {
     return Object.freeze({
         provide,
-        useFactory,
+        useFactory: useFactory,
         inject: Object.freeze([...inject]),
     });
 }

package/dist/containerResolution/containerResolution.autoRegister.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @zudojs/container/containerResolution/containerResolution.autoRegister
+ *
+ * Guards for `autoRegisterClasses`: resolving an unregistered class builds
+ * it with no arguments, which is only correct for a constructor that
+ * declares none.
+ */
+/**
+ * Whether an unregistered token may be auto-registered: a class whose
+ * constructor declares no required parameters (`Class.length === 0`).
+ *
+ * Parameters with a default value do not count, so
+ * `constructor(value = 7)` still qualifies.
+ */
+export declare function isAutoRegistrable(token: unknown): boolean;
+/**
+ * Throws when a class cannot be auto-registered because its constructor
+ * declares parameters. Auto-registration has no inject list, so building
+ * it would pass `undefined` for every dependency.
+ *
+ * @throws {RegistrationNotFoundError} naming the class and how to
+ *   register it.
+ */
+export declare function assertAutoRegistrable(token: {
+    readonly length: number;
+}): void;
+//# sourceMappingURL=containerResolution.autoRegister.d.ts.map

package/dist/containerResolution/containerResolution.autoRegister.js

@@ -0,0 +1,40 @@
+/**
+ * @zudojs/container/containerResolution/containerResolution.autoRegister
+ *
+ * Guards for `autoRegisterClasses`: resolving an unregistered class builds
+ * it with no arguments, which is only correct for a constructor that
+ * declares none.
+ */
+import { RegistrationNotFoundError } from "@zudojs/errors";
+import { describeToken } from "../containerToken/containerToken.type.js";
+/**
+ * Whether an unregistered token may be auto-registered: a class whose
+ * constructor declares no required parameters (`Class.length === 0`).
+ *
+ * Parameters with a default value do not count, so
+ * `constructor(value = 7)` still qualifies.
+ */
+export function isAutoRegistrable(token) {
+    return typeof token === "function" && token.length === 0;
+}
+/**
+ * Throws when a class cannot be auto-registered because its constructor
+ * declares parameters. Auto-registration has no inject list, so building
+ * it would pass `undefined` for every dependency.
+ *
+ * @throws {RegistrationNotFoundError} naming the class and how to
+ *   register it.
+ */
+export function assertAutoRegistrable(token) {
+    if (isAutoRegistrable(token))
+        return;
+    const name = describeToken(token);
+    const count = token.length;
+    throw new RegistrationNotFoundError(name, `Cannot auto-register class "${name}": its constructor declares ` +
+        `${count} parameter${count === 1 ? "" : "s"} and no inject list is ` +
+        `registered, so it would be built with undefined dependencies. ` +
+        `Register it with container.registerClass(${name}, ${name}, ` +
+        `{ inject: [/* one token per parameter */] }) or ` +
+        `container.registerFactory(${name}, (...deps) => new ${name}(...deps), [/* tokens */]).`);
+}
+//# sourceMappingURL=containerResolution.autoRegister.js.map

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";
@@ -34,12 +37,24 @@ export declare class ContainerResolver {
     private readonly onSingletonEvicted;
     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
-     *   `replace()`/`remove()` (the token itself and each cached consumer),
-     *   so owners of scope caches can drop and dispose their SCOPED copies.
+     *   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;

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 { assertAutoRegistrable, isAutoRegistrable, } from "./containerResolution.autoRegister.js";
 import { DependentIndex } from "./containerResolution.dependents.js";
 /**
  * Scope cache that falls back to its parent scope's cache for lookups while
@@ -69,12 +73,24 @@ export class ContainerResolver {
     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
-     *   `replace()`/`remove()` (the token itself and each cached consumer),
-     *   so owners of scope caches can drop and dispose their SCOPED copies.
+     *   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;
@@ -109,6 +125,7 @@ export class ContainerResolver {
         let registration = this.registry.get(token);
         if (!registration) {
             if (state.autoRegisterClasses && typeof token === "function") {
+                assertAutoRegistrable(token);
                 if (state.allowRegistration) {
                     registration = this.registry.register(token, { useClass: token }, { scope: Scope.TRANSIENT });
                 }
@@ -165,8 +182,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,
@@ -196,9 +216,9 @@ export class ContainerResolver {
             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.`);
+                    !(state.autoRegisterClasses && isAutoRegistrable(target))) {
+                    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
@@ -224,7 +244,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
@@ -263,7 +285,7 @@ export class ContainerResolver {
     }
     canResolve(token, autoRegisterClasses = true) {
         const t = unwrapToken(token);
-        return (this.registry.has(t) || (autoRegisterClasses && typeof t === "function"));
+        return (this.registry.has(t) || (autoRegisterClasses && isAutoRegistrable(t)));
     }
     handleRegistryChange(event) {
         switch (event.operation) {
@@ -282,9 +304,21 @@ export class ContainerResolver {
             }
             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/containerToken/containerToken.type.d.ts

@@ -44,5 +44,13 @@ export declare function isInjectionToken<T = unknown>(value: unknown): value is
 export declare function isConstructorToken<T = unknown>(token: Token<T>): token is Constructor<T>;
 export declare function isSymbolToken<T = unknown>(token: Token<T>): token is symbol;
 export declare function isStringToken<T = unknown>(token: Token<T>): token is string;
+/**
+ * Returns a human-readable name for a token, used in error messages and as
+ * the default registration name.
+ *
+ * A symbol token (including every `createToken`/`createGlobalToken` token)
+ * is shown by its description, so errors read `MissingService` rather than
+ * `Symbol(MissingService)`. A symbol without a description is `Symbol()`.
+ */
 export declare function describeToken<T>(token: Token<T> | InjectionToken<T>): string;
 //# sourceMappingURL=containerToken.type.d.ts.map

package/dist/containerToken/containerToken.type.js

@@ -48,14 +48,20 @@ export function isSymbolToken(token) {
 export function isStringToken(token) {
     return typeof token === "string";
 }
+/**
+ * Returns a human-readable name for a token, used in error messages and as
+ * the default registration name.
+ *
+ * A symbol token (including every `createToken`/`createGlobalToken` token)
+ * is shown by its description, so errors read `MissingService` rather than
+ * `Symbol(MissingService)`. A symbol without a description is `Symbol()`.
+ */
 export function describeToken(token) {
     const resolved = unwrapToken(token);
     if (typeof resolved === "string")
         return resolved;
     if (typeof resolved === "symbol")
-        return resolved.description
-            ? `Symbol(${resolved.description})`
-            : "Symbol()";
+        return resolved.description ? resolved.description : "Symbol()";
     if (typeof resolved === "function")
         return resolved.name || "AnonymousConstructor";
     return "UnknownToken";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/container",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Token-based dependency injection container for managing application dependencies and service lifetimes.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,11 +18,11 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/errors": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -41,7 +41,7 @@
     "dependency-injection",
     "container"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-container",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },