@zudojs/container 0.0.1 → 1.0.0

package/dist/containerRegistry/containerRegistry.core.js

@@ -1,11 +1,16 @@
 /**
  * Container registration registry.
+ *
+ * The registry stores normalized registrations and emits change events
+ * (REGISTER / REPLACE / REMOVE / CLEAR / RESTORE) so collaborators — notably
+ * the resolver's singleton cache — can react to mutations.
  */
-import { defineRegistration, getRegistrationToken, } from "../containerRegistration/containerRegistration.core.js";
-import { unwrapToken } from "../containerToken/containerToken.type.js";
+import { assertValidProvider, assertValidRegistrationToken, defineRegistration, getRegistrationToken, } from "../containerRegistration/containerRegistration.core.js";
+import { describeToken, unwrapToken, } from "../containerToken/containerToken.type.js";
 import { RegistryOperation } from "./containerRegistry.type.js";
 import { DuplicateRegistrationError, RegistrationNotFoundError, } from "@zudojs/errors";
-import { describeRegistryToken } from "./containerRegistry.error.js";
+/** Token used for registry-wide events (CLEAR / RESTORE). */
+const REGISTRY_EVENT_TOKEN = Symbol.for("zudojs:container:registry");
 export class ContainerRegistry {
     registrations = new Map();
     listeners = new Set();
@@ -16,7 +21,7 @@ export class ContainerRegistry {
     register(token, provider, options = {}) {
         const t = unwrapToken(token);
         if (this.registrations.has(t) && !this.allowDuplicates)
-            throw new DuplicateRegistrationError(describeRegistryToken(t));
+            throw new DuplicateRegistrationError(describeToken(t));
         const prev = this.registrations.get(t);
         const reg = defineRegistration(t, provider, options);
         this.registrations.set(t, reg);
@@ -29,25 +34,10 @@ export class ContainerRegistry {
         });
         return reg;
     }
-    registerRegistration(registration) {
-        const t = getRegistrationToken(registration);
-        if (this.registrations.has(t) && !this.allowDuplicates)
-            throw new DuplicateRegistrationError(describeRegistryToken(t));
-        const prev = this.registrations.get(t);
-        this.registrations.set(t, registration);
-        this.emit({
-            operation: prev ? RegistryOperation.REPLACE : RegistryOperation.REGISTER,
-            token: t,
-            registration,
-            previous: prev,
-            timestamp: new Date(),
-        });
-        return registration;
-    }
     replace(token, provider, options = {}) {
         const t = unwrapToken(token);
         if (!this.registrations.has(t))
-            throw new RegistrationNotFoundError(describeRegistryToken(t));
+            throw new RegistrationNotFoundError(describeToken(t));
         const prev = this.registrations.get(t);
         const reg = defineRegistration(t, provider, options);
         this.registrations.set(t, reg);
@@ -63,12 +53,6 @@ export class ContainerRegistry {
     get(token) {
         return this.registrations.get(unwrapToken(token));
     }
-    getOrThrow(token) {
-        const r = this.get(token);
-        if (!r)
-            throw new RegistrationNotFoundError(describeRegistryToken(unwrapToken(token)));
-        return r;
-    }
     has(token) {
         return this.registrations.has(unwrapToken(token));
     }
@@ -87,10 +71,6 @@ export class ContainerRegistry {
             });
         return removed;
     }
-    removeOrThrow(token) {
-        if (!this.remove(unwrapToken(token)))
-            throw new RegistrationNotFoundError(describeRegistryToken(unwrapToken(token)));
-    }
     get size() {
         return this.registrations.size;
     }
@@ -100,25 +80,13 @@ export class ContainerRegistry {
     getTokens() {
         return [...this.registrations.keys()];
     }
-    getByModule(module) {
-        return [...this.registrations.values()].filter((r) => r.metadata.module === module);
-    }
-    getByScope(scope) {
-        return [...this.registrations.values()].filter((r) => r.scope === scope);
-    }
-    find(predicate) {
-        return [...this.registrations.values()].filter(predicate);
-    }
-    getMetadata(token) {
-        return this.get(token)?.metadata;
-    }
     clear() {
         if (this.registrations.size === 0)
             return;
         this.registrations.clear();
         this.emit({
             operation: RegistryOperation.CLEAR,
-            token: Symbol.for("zudojs:container:registry"),
+            token: REGISTRY_EVENT_TOKEN,
             timestamp: new Date(),
         });
     }
@@ -131,23 +99,58 @@ export class ContainerRegistry {
     clearListeners() {
         this.listeners.clear();
     }
+    /**
+     * Notifies all listeners. Listener errors are collected and rethrown as a
+     * single AggregateError after every listener has been notified — they are
+     * never silently swallowed.
+     */
     emit(event) {
+        const errors = [];
         for (const l of this.listeners) {
             try {
                 l(event);
             }
-            catch {
-                /* noop */
+            catch (error) {
+                errors.push(error);
             }
         }
+        if (errors.length > 0)
+            throw new AggregateError(errors, `${errors.length} container registry listener(s) failed while handling "${event.operation}".`);
     }
+    /**
+     * Returns an immutable snapshot of the current registrations.
+     * Pass the result to {@link restore} to roll the registry back.
+     */
     snapshot() {
         return this.getAll();
     }
+    /**
+     * Wholesale replacement of the registry's contents.
+     *
+     * Every existing registration is discarded and replaced by `regs` (entries
+     * are validated first; duplicate tokens in `regs` throw unless
+     * `allowDuplicates` is enabled, in which case the last entry wins).
+     * Emits a single RESTORE event so caches keyed on the old registrations
+     * can be evicted.
+     */
     restore(regs) {
+        const next = new Map();
+        for (const r of regs) {
+            assertValidRegistrationToken(r.token);
+            assertValidProvider(r.provider);
+            const t = getRegistrationToken(r);
+            if (next.has(t) && !this.allowDuplicates)
+                throw new DuplicateRegistrationError(describeToken(t));
+            next.set(t, r);
+        }
         this.registrations.clear();
-        for (const r of regs)
-            this.registrations.set(getRegistrationToken(r), r);
+        for (const [t, r] of next)
+            this.registrations.set(t, r);
+        this.emit({
+            operation: RegistryOperation.RESTORE,
+            token: REGISTRY_EVENT_TOKEN,
+            timestamp: new Date(),
+        });
     }
 }
 //# sourceMappingURL=containerRegistry.core.js.map

package/dist/containerRegistry/containerRegistry.type.d.ts

@@ -14,7 +14,9 @@ export declare enum RegistryOperation {
     REGISTER = "register",
     REPLACE = "replace",
     REMOVE = "remove",
-    CLEAR = "clear"
+    CLEAR = "clear",
+    /** Wholesale replacement of all registrations via `restore()`. */
+    RESTORE = "restore"
 }
 /**
  * Event emitted when the registry changes.

package/dist/containerRegistry/containerRegistry.type.js

@@ -10,5 +10,7 @@ export var RegistryOperation;
     RegistryOperation["REPLACE"] = "replace";
     RegistryOperation["REMOVE"] = "remove";
     RegistryOperation["CLEAR"] = "clear";
+    /** Wholesale replacement of all registrations via `restore()`. */
+    RegistryOperation["RESTORE"] = "restore";
 })(RegistryOperation || (RegistryOperation = {}));
 //# sourceMappingURL=containerRegistry.type.js.map

package/dist/containerRegistry/index.d.ts

@@ -4,6 +4,5 @@
  * Service registry storage and lookup.
  */
 export * from "./containerRegistry.type.js";
-export { describeRegistryToken } from "./containerRegistry.error.js";
 export * from "./containerRegistry.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/containerRegistry/index.js

@@ -4,6 +4,5 @@
  * Service registry storage and lookup.
  */
 export * from "./containerRegistry.type.js";
-export { describeRegistryToken } from "./containerRegistry.error.js";
 export * from "./containerRegistry.core.js";
 //# sourceMappingURL=index.js.map

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

@@ -1,26 +1,58 @@
 /**
  * Dependency resolver for Zudojs.
+ *
+ * Lifetime semantics:
+ * - SINGLETON instances are always looked up in and stored to the resolver's
+ *   root singleton cache, no matter where the resolution happens (root or
+ *   scope). A scope can therefore never re-create or shadow a singleton.
+ * - SCOPED instances live in the scope cache supplied via
+ *   `ResolutionOptions.cache`. Resolving a SCOPED registration without a
+ *   scope cache throws a ScopedResolutionError; a SCOPED dependency of a
+ *   SINGLETON throws a CaptiveDependencyError.
+ * - TRANSIENT instances are never cached.
+ *
+ * Every freshly created instance (any lifetime, never a cache hit) is
+ * reported through `ResolutionOptions.onInstanceCreated` in creation order,
+ * so owners can track transitively created dependencies for disposal — not
+ * just the top-level result of a `resolve()` call.
+ *
+ * Factories registered as SINGLETON or SCOPED must be synchronous: a Promise
+ * result throws an AsyncProviderError instead of being cached as the instance.
+ *
+ * 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.
  */
 import type { RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
 import type { ContainerRegistry } from "../containerRegistry/containerRegistry.core.js";
+import type { Token } from "../containerToken/containerToken.type.js";
 import type { ResolutionCache, ResolutionOptions, ResolutionResult } from "./containerResolution.type.js";
 export declare class ContainerResolver {
     private readonly registry;
     private readonly singletonCache;
-    constructor(registry: ContainerRegistry);
+    private readonly onSingletonEvicted;
+    constructor(registry: ContainerRegistry, onSingletonEvicted?: (token: Token<unknown>) => void);
     resolve<T>(token: RegistrationToken<T>, options?: ResolutionOptions): T;
     resolveDetailed<T>(token: RegistrationToken<T>, options?: ResolutionOptions): ResolutionResult<T>;
     private resolveInternal;
     private createInstance;
-    private createFromFactory;
-    private createFromClass;
-    createScope(): ResolutionCache;
-    clearSingletons(): void;
-    hasSingleton<T>(token: RegistrationToken<T>): boolean;
-    getSingleton<T>(token: RegistrationToken<T>): T | undefined;
-    removeSingleton<T>(token: RegistrationToken<T>): boolean;
-    clearScope(cache: ResolutionCache): void;
+    /**
+     * Creates an empty scope cache for SCOPED instances. When `parent` is
+     * given, lookups fall back to it (nested scope semantics) while writes stay
+     * local to the new cache.
+     */
+    createScope(parent?: ResolutionCache): ResolutionCache;
+    /** Tokens currently held in the singleton cache. */
+    getCachedSingletonTokens(): readonly Token<unknown>[];
+    /**
+     * Clears the singleton cache WITHOUT invoking eviction callbacks.
+     * Callers are responsible for disposing the previously cached instances.
+     */
+    clearSingletonCache(): void;
     resolveMany<T>(tokens: readonly RegistrationToken<T>[], options?: ResolutionOptions): T[];
-    canResolve<T>(token: RegistrationToken<T>): boolean;
+    canResolve<T>(token: RegistrationToken<T>, autoRegisterClasses?: boolean): boolean;
+    private handleRegistryChange;
+    private evictSingleton;
 }
 //# sourceMappingURL=containerResolution.core.d.ts.map

package/dist/containerResolution/containerResolution.core.js

@@ -1,51 +1,117 @@
 /**
  * Dependency resolver for Zudojs.
+ *
+ * Lifetime semantics:
+ * - SINGLETON instances are always looked up in and stored to the resolver's
+ *   root singleton cache, no matter where the resolution happens (root or
+ *   scope). A scope can therefore never re-create or shadow a singleton.
+ * - SCOPED instances live in the scope cache supplied via
+ *   `ResolutionOptions.cache`. Resolving a SCOPED registration without a
+ *   scope cache throws a ScopedResolutionError; a SCOPED dependency of a
+ *   SINGLETON throws a CaptiveDependencyError.
+ * - TRANSIENT instances are never cached.
+ *
+ * Every freshly created instance (any lifetime, never a cache hit) is
+ * reported through `ResolutionOptions.onInstanceCreated` in creation order,
+ * so owners can track transitively created dependencies for disposal — not
+ * just the top-level result of a `resolve()` call.
+ *
+ * Factories registered as SINGLETON or SCOPED must be synchronous: a Promise
+ * result throws an AsyncProviderError instead of being cached as the instance.
+ *
+ * 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.
  */
 import { isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider, normalizeProvider, } from "../containerProvider/containerProvider.core.js";
 import { ContainerScope as Scope } from "../containerScope/containerScope.type.js";
-import { getRegistrationToken } from "../containerRegistration/containerRegistration.core.js";
-import { RegistrationNotFoundError } from "@zudojs/errors";
-import { describeRegistryToken } from "../containerRegistry/containerRegistry.error.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, } from "@zudojs/errors";
+import { CircularDependencyError, ProviderResolutionError, RegistrationNotFoundError, } from "@zudojs/errors";
+import { AsyncProviderError, CaptiveDependencyError, DependencyResolutionError, MaxResolutionDepthError, ScopedResolutionError, } from "./containerResolution.error.js";
 import { describeToken } from "../containerToken/containerToken.type.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
+ * already created by their ancestors, while instances they create themselves
+ * stay private to (and are disposed with) the nested scope.
+ */
+class ChainedResolutionCache {
+    #own = new Map();
+    #parent;
+    constructor(parent) {
+        this.#parent = parent;
+    }
+    has(token) {
+        return this.#own.has(token) || (this.#parent?.has(token) ?? false);
+    }
+    get(token) {
+        if (this.#own.has(token))
+            return this.#own.get(token);
+        return this.#parent?.get(token);
+    }
+    set(token, value) {
+        this.#own.set(token, value);
+    }
+    clear() {
+        this.#own.clear();
+    }
+}
 export class ContainerResolver {
     registry;
-    singletonCache;
-    constructor(registry) {
+    singletonCache = new Map();
+    onSingletonEvicted;
+    constructor(registry, onSingletonEvicted) {
         this.registry = registry;
-        this.singletonCache = new Map();
+        this.onSingletonEvicted = onSingletonEvicted;
+        registry.subscribe((event) => this.handleRegistryChange(event));
     }
     resolve(token, options = {}) {
         return this.resolveDetailed(token, options).value;
     }
     resolveDetailed(token, options = {}) {
         const normalized = unwrapToken(token);
-        const cache = options.cache ?? this.singletonCache;
-        const path = options.path ?? [];
-        return this.resolveInternal(normalized, cache, path, options);
-    }
-    resolveInternal(token, cache, path, options) {
-        if (path.includes(token))
-            throw new CircularDependencyError([...path, token].map((t) => describeToken(t)));
-        const registration = this.registry.get(token);
+        const path = [...(options.path ?? [])];
+        const state = {
+            scopeCache: options.cache,
+            autoRegisterClasses: options.autoRegisterClasses ?? true,
+            allowRegistration: options.allowRegistration ?? true,
+            detectCircularDependencies: options.detectCircularDependencies ?? true,
+            maxResolutionDepth: options.maxResolutionDepth ?? 100,
+            onInstanceCreated: options.onInstanceCreated,
+            path,
+            pathSet: new Set(path),
+        };
+        return this.resolveInternal(normalized, state, undefined);
+    }
+    resolveInternal(token, state, singletonAncestor) {
+        const depth = state.path.length + 1;
+        if (depth > state.maxResolutionDepth)
+            throw new MaxResolutionDepthError(describeToken(token), depth, state.maxResolutionDepth, [...state.path, token].map((t) => describeToken(t)));
+        if (state.detectCircularDependencies && state.pathSet.has(token))
+            throw new CircularDependencyError([...state.path, token].map((t) => describeToken(t)));
+        let registration = this.registry.get(token);
         if (!registration) {
-            if (options.autoRegisterClasses !== false &&
-                typeof token === "function") {
-                this.registry.register(token, { useClass: token }, { scope: Scope.TRANSIENT });
-                return this.resolveInternal(token, cache, path, {
-                    ...options,
-                    autoRegisterClasses: false,
-                });
+            if (state.autoRegisterClasses && typeof token === "function") {
+                if (state.allowRegistration) {
+                    registration = this.registry.register(token, { useClass: token }, { scope: Scope.TRANSIENT });
+                }
+                else {
+                    // Registrations are frozen: instantiate ephemerally, do not register.
+                    registration = defineRegistration(token, { useClass: token }, { scope: Scope.TRANSIENT });
+                }
+            }
+            else {
+                throw new RegistrationNotFoundError(describeToken(token));
             }
-            throw new RegistrationNotFoundError(describeRegistryToken(token));
         }
-        const currentPath = [...path, token];
-        if (registration.scope !== Scope.TRANSIENT) {
-            const cached = cache.get(token);
-            if (cached !== undefined) {
+        const currentPath = [...state.path, token];
+        if (registration.scope === Scope.SINGLETON) {
+            if (this.singletonCache.has(token)) {
                 return {
-                    value: cached,
+                    value: this.singletonCache.get(token),
                     token,
                     registration,
                     scope: registration.scope,
@@ -54,12 +120,38 @@ export class ContainerResolver {
                 };
             }
         }
-        const value = this.createInstance(registration, cache, currentPath, options);
+        else if (registration.scope === Scope.SCOPED) {
+            if (singletonAncestor !== undefined)
+                throw new CaptiveDependencyError(describeToken(singletonAncestor), describeToken(token), currentPath.map((t) => describeToken(t)));
+            if (!state.scopeCache)
+                throw new ScopedResolutionError(describeToken(token), currentPath.map((t) => describeToken(t)));
+            if (state.scopeCache.has(token)) {
+                return {
+                    value: state.scopeCache.get(token),
+                    token,
+                    registration,
+                    scope: registration.scope,
+                    fromCache: true,
+                    path: currentPath,
+                };
+            }
+        }
+        const nextAncestor = registration.scope === Scope.SINGLETON ? token : singletonAncestor;
+        state.path.push(token);
+        state.pathSet.add(token);
+        let value;
+        try {
+            value = this.createInstance(registration, state, nextAncestor);
+        }
+        finally {
+            state.path.pop();
+            state.pathSet.delete(token);
+        }
         if (registration.scope === Scope.SINGLETON)
             this.singletonCache.set(token, value);
         else if (registration.scope === Scope.SCOPED)
-            cache.set(token, value);
-        return {
+            state.scopeCache?.set(token, value);
+        const result = {
             value,
             token,
             registration,
@@ -67,59 +159,110 @@ export class ContainerResolver {
             fromCache: false,
             path: currentPath,
         };
+        state.onInstanceCreated?.(result);
+        return result;
     }
-    createInstance(registration, cache, path, options) {
+    createInstance(registration, state, singletonAncestor) {
         const provider = normalizeProvider(registration.provider);
+        const token = getRegistrationToken(registration);
         try {
             if (isValueProvider(provider))
                 return provider.useValue;
-            if (isExistingProvider(provider))
-                return this.resolve(provider.useExisting, { ...options, cache, path });
-            if (isFactoryProvider(provider))
-                return this.createFromFactory(provider, cache, path, options);
-            if (isClassProvider(provider))
-                return this.createFromClass(provider.useClass);
+            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.`);
+                }
+                return this.resolveInternal(target, state, singletonAncestor)
+                    .value;
+            }
+            if (isFactoryProvider(provider)) {
+                const deps = provider.inject ?? [];
+                const args = deps.map((d) => this.resolveInternal(unwrapToken(d), state, singletonAncestor)
+                    .value);
+                const produced = provider.useFactory(...args);
+                if (registration.scope !== Scope.TRANSIENT && isPromiseLike(produced))
+                    throw new AsyncProviderError(describeToken(token), registration.scope);
+                return produced;
+            }
+            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);
+            }
             throw new Error("Unsupported container provider.");
         }
         catch (error) {
+            // Resolution errors created deeper in the chain already carry the full
+            // chain in their message/details — propagate them unchanged.
             if (error instanceof CircularDependencyError ||
-                error instanceof ProviderResolutionError)
+                error instanceof ProviderResolutionError ||
+                error instanceof ScopedResolutionError ||
+                error instanceof CaptiveDependencyError ||
+                error instanceof MaxResolutionDepthError ||
+                error instanceof AsyncProviderError)
                 throw error;
-            const message = error instanceof Error ? error.message : undefined;
-            throw new ProviderResolutionError(describeRegistryToken(getRegistrationToken(registration)), message, error);
+            throw new DependencyResolutionError(describeToken(token), error, state.path.map((t) => describeToken(t)));
         }
     }
-    createFromFactory(provider, cache, path, options) {
-        const deps = provider.inject ?? [];
-        return provider.useFactory(...deps.map((d) => this.resolve(d, { ...options, cache, path })));
+    /**
+     * Creates an empty scope cache for SCOPED instances. When `parent` is
+     * given, lookups fall back to it (nested scope semantics) while writes stay
+     * local to the new cache.
+     */
+    createScope(parent) {
+        return new ChainedResolutionCache(parent);
     }
-    createFromClass(constructor) {
-        return new constructor();
+    /** Tokens currently held in the singleton cache. */
+    getCachedSingletonTokens() {
+        return [...this.singletonCache.keys()];
     }
-    createScope() {
-        return new Map();
-    }
-    clearSingletons() {
+    /**
+     * Clears the singleton cache WITHOUT invoking eviction callbacks.
+     * Callers are responsible for disposing the previously cached instances.
+     */
+    clearSingletonCache() {
         this.singletonCache.clear();
     }
-    hasSingleton(token) {
-        return this.singletonCache.has(unwrapToken(token));
-    }
-    getSingleton(token) {
-        return this.singletonCache.get(unwrapToken(token));
-    }
-    removeSingleton(token) {
-        return this.singletonCache.delete(unwrapToken(token));
-    }
-    clearScope(cache) {
-        cache.clear();
-    }
     resolveMany(tokens, options = {}) {
         return tokens.map((t) => this.resolve(t, options));
     }
-    canResolve(token) {
+    canResolve(token, autoRegisterClasses = true) {
         const t = unwrapToken(token);
-        return this.registry.has(t) || typeof t === "function";
+        return (this.registry.has(t) || (autoRegisterClasses && typeof t === "function"));
     }
+    handleRegistryChange(event) {
+        switch (event.operation) {
+            case RegistryOperation.REPLACE:
+            case RegistryOperation.REMOVE: {
+                this.evictSingleton(unwrapToken(event.token));
+                break;
+            }
+            case RegistryOperation.CLEAR:
+            case RegistryOperation.RESTORE: {
+                for (const t of [...this.singletonCache.keys()])
+                    this.evictSingleton(t);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    evictSingleton(token) {
+        if (!this.singletonCache.has(token))
+            return;
+        this.singletonCache.delete(token);
+        this.onSingletonEvicted?.(token);
+    }
+}
+function isPromiseLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "then" in value &&
+        typeof value.then === "function");
 }
 //# sourceMappingURL=containerResolution.core.js.map