@zudojs/container 0.1.0 → 1.1.0

package/dist/containerProvider/containerProvider.core.js

@@ -18,10 +18,12 @@ export function isTokenProvider(provider) {
     return "provide" in provider && "provider" in provider;
 }
 export function hasInjectedDependencies(provider) {
-    return isFactoryProvider(provider) && Array.isArray(provider.inject);
+    return ((isFactoryProvider(provider) || isClassProvider(provider)) &&
+        Array.isArray(provider.inject) &&
+        provider.inject.length > 0);
 }
-export function classProvider(useClass) {
-    return Object.freeze({ useClass });
+export function classProvider(useClass, inject = []) {
+    return Object.freeze({ useClass, inject: Object.freeze([...inject]) });
 }
 export function factoryProvider(useFactory, inject = []) {
     return Object.freeze({ useFactory, inject: Object.freeze([...inject]) });
@@ -32,8 +34,12 @@ export function valueProvider(useValue) {
 export function existingProvider(useExisting) {
     return Object.freeze({ useExisting });
 }
-export function provideClass(provide, useClass) {
-    return Object.freeze({ provide, useClass });
+export function provideClass(provide, useClass, inject = []) {
+    return Object.freeze({
+        provide,
+        useClass,
+        inject: Object.freeze([...inject]),
+    });
 }
 export function provideFactory(provide, useFactory, inject = []) {
     return Object.freeze({

package/dist/containerRegistration/containerRegistration.core.d.ts

@@ -6,6 +6,15 @@ import { ContainerScope } from "../containerScope/containerScope.type.js";
 import type { ContainerProvider, ProviderToken } from "../containerProvider/containerProvider.core.js";
 import type { InjectionToken, Token } from "../containerToken/containerToken.type.js";
 export type RegistrationToken<T = unknown> = Token<T> | InjectionToken<T>;
+/** The type a registration token resolves to (`unknown` for untyped tokens). */
+export type ResolvedToken<T extends RegistrationToken> = T extends RegistrationToken<infer U> ? U : never;
+/**
+ * Maps a tuple of registration tokens to a tuple of their resolved types, so
+ * `resolveMany([LOGGER, DB])` is typed `[Logger, Db]`.
+ */
+export type ResolvedTokens<Tokens extends readonly RegistrationToken[]> = {
+    -readonly [K in keyof Tokens]: Tokens[K] extends RegistrationToken ? ResolvedToken<Tokens[K]> : never;
+};
 export interface RegistrationMetadata {
     readonly name?: string;
     readonly description?: string;
@@ -18,7 +27,6 @@ export interface ContainerRegistration<T = unknown> {
     readonly provider: ContainerProvider<T>;
     readonly scope: ContainerScope;
     readonly metadata: RegistrationMetadata;
-    readonly initialized: boolean;
     readonly createdAt: Date;
 }
 export interface CreateRegistrationOptions extends RegistrationMetadata {
@@ -29,13 +37,11 @@ export interface MutableRegistrationState<T = unknown> {
     readonly provider: ContainerProvider<T>;
     scope: ContainerScope;
     metadata: RegistrationMetadata;
-    initialized: boolean;
     createdAt: Date;
 }
 export declare function createRegistration<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
 export declare function createMutableRegistrationState<T>(registration: ContainerRegistration<T>): MutableRegistrationState<T>;
 export declare function freezeRegistration<T>(state: MutableRegistrationState<T>): ContainerRegistration<T>;
-export declare function markRegistrationInitialized<T>(registration: ContainerRegistration<T>): ContainerRegistration<T>;
 export declare function getRegistrationToken<T>(registration: ContainerRegistration<T>): Token<T>;
 export declare function getRegistrationProviderToken<T>(registration: ContainerRegistration<T>): ProviderToken<T> | undefined;
 export declare function isSingletonRegistration<T>(registration: ContainerRegistration<T>): boolean;

package/dist/containerRegistration/containerRegistration.core.js

@@ -13,7 +13,6 @@ export function createRegistration(token, provider, options = {}) {
         provider: normalizedProvider,
         scope: resolveContainerScope(options.scope),
         metadata: createRegistrationMetadata(options, normalizedToken),
-        initialized: false,
         createdAt: new Date(),
     };
     return Object.freeze({
@@ -43,7 +42,6 @@ export function createMutableRegistrationState(registration) {
         provider: registration.provider,
         scope: registration.scope,
         metadata: registration.metadata,
-        initialized: registration.initialized,
         createdAt: registration.createdAt,
     };
 }
@@ -58,13 +56,9 @@ export function freezeRegistration(state) {
                 ? Object.freeze({ ...state.metadata.metadata })
                 : undefined,
         }),
-        initialized: state.initialized,
         createdAt: state.createdAt,
     });
 }
-export function markRegistrationInitialized(registration) {
-    return Object.freeze({ ...registration, initialized: true });
-}
 export function getRegistrationToken(registration) {
     return unwrapToken(registration.token);
 }

package/dist/containerRegistry/containerRegistry.core.d.ts

@@ -1,9 +1,12 @@
 /**
  * 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 type { ContainerProvider } from "../containerProvider/containerProvider.core.js";
-import type { ContainerScope } from "../containerScope/containerScope.type.js";
-import type { ContainerRegistration, CreateRegistrationOptions, RegistrationMetadata, RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
+import type { ContainerRegistration, CreateRegistrationOptions, RegistrationToken } from "../containerRegistration/containerRegistration.core.js";
 import type { Token } from "../containerToken/containerToken.type.js";
 import type { ContainerRegistryOptions, RegistryListener } from "./containerRegistry.type.js";
 export declare class ContainerRegistry {
@@ -12,25 +15,36 @@ export declare class ContainerRegistry {
     private readonly allowDuplicates;
     constructor(options?: ContainerRegistryOptions);
     register<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
-    registerRegistration<T>(registration: ContainerRegistration<T>): ContainerRegistration<T>;
     replace<T>(token: RegistrationToken<T>, provider: ContainerProvider<T>, options?: CreateRegistrationOptions): ContainerRegistration<T>;
     get<T>(token: RegistrationToken<T>): ContainerRegistration<T> | undefined;
-    getOrThrow<T>(token: RegistrationToken<T>): ContainerRegistration<T>;
     has<T>(token: RegistrationToken<T>): boolean;
     remove<T>(token: RegistrationToken<T>): boolean;
-    removeOrThrow<T>(token: RegistrationToken<T>): void;
     get size(): number;
     getAll(): readonly ContainerRegistration[];
     getTokens(): readonly Token<unknown>[];
-    getByModule(module: string): readonly ContainerRegistration[];
-    getByScope(scope: ContainerScope): readonly ContainerRegistration[];
-    find(predicate: (r: ContainerRegistration) => boolean): readonly ContainerRegistration[];
-    getMetadata<T>(token: RegistrationToken<T>): RegistrationMetadata | undefined;
     clear(): void;
     subscribe(listener: RegistryListener): () => void;
     clearListeners(): void;
+    /**
+     * Notifies all listeners. Listener errors are collected and rethrown as a
+     * single AggregateError after every listener has been notified — they are
+     * never silently swallowed.
+     */
     private emit;
+    /**
+     * Returns an immutable snapshot of the current registrations.
+     * Pass the result to {@link restore} to roll the registry back.
+     */
     snapshot(): readonly ContainerRegistration[];
+    /**
+     * 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: readonly ContainerRegistration[]): void;
 }
 //# sourceMappingURL=containerRegistry.core.d.ts.map

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,67 @@
 /**
  * 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;
+    /**
+     * 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