@lppedd/di-wise-neo 0.17.0 → 0.18.1

package/dist/es/index.d.mts

@@ -1,3 +1,6 @@
+type ClassDecorator<Class extends object> = (target: Constructor<Class>) => Constructor<Class> | void;
+type ParameterDecorator = (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
+
 declare const Scope: {
     /**
      * Creates a new value every time the token is resolved.
@@ -126,11 +129,8 @@ declare function createType<T>(typeName: string, provider: Provider<T>, options?
 interface ClassRef<Instance extends object> {
     readonly getRefClass: () => Constructor<Instance>;
 }
-interface TokensRef<Value> {
-    readonly getRefTokens: () => Set<Token<Value>>;
-}
 interface TokenRef<Value> {
-    readonly getRefToken: () => Token<Value>;
+    readonly getRefTokens: () => Set<Token<Value>>;
 }
 /**
  * Allows referencing a class declared later in the file by wrapping it
@@ -140,15 +140,12 @@ interface TokenRef<Value> {
  */
 declare function classRef<Instance extends object>(Class: () => Constructor<Instance>): ClassRef<Instance>;
 /**
- * Allows referencing tokens declared later in the file by wrapping them
- * in a lazily evaluated function.
- */
-declare function tokenRef<Value>(token: () => Tokens<Value>): TokensRef<Value>;
-/**
- * Allows referencing a token declared later in the file by wrapping it
- * in a lazily evaluated function.
+ * Allows referencing one or multiple tokens declared later in the file by wrapping them
+ * into a lazily evaluated function.
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-declare function tokenRef<Value>(token: () => Token<Value>): TokenRef<Value>;
+declare function tokenRef<Value>(token: () => Token<Value> | Tokens<Value>): TokenRef<Value>;
 
 /**
  * Provides a class instance for a token via a class constructor.
@@ -290,6 +287,13 @@ interface ContainerOptions {
      * @defaultValue false
      */
     readonly autoRegister: boolean;
+    /**
+     * Whether to also dispose values provided via {@link ValueProvider}, which are not
+     * created or managed by the container, when the container itself is disposed.
+     *
+     * @defaultValue false
+     */
+    readonly disposeUnmanaged: boolean;
 }
 /**
  * Child container creation options.
@@ -308,19 +312,20 @@ interface ChildContainerOptions extends ContainerOptions {
 interface ContainerHook {
     /**
      * Called when the container provides a value for a {@link Token}.
-     * - For **Container** scoped tokens, it is called only once when the token is first resolved and cached.
-     * - For **Resolution** scoped tokens, it is called once per token resolution graph.
-     * - For **Transient** scoped tokens, it is called each time the token is resolved,
+     * - For **Container**-scoped tokens, it is called only once when the token is first resolved and cached.
+     * - For **Resolution**-scoped tokens, it is called once per token resolution graph.
+     * - For **Transient**-scoped tokens, it is called each time the token is resolved,
      *   which might mean multiple times per resolution graph.
      *
-     * @param value The provided value.
-     * @param scope The {@link Scope} of the provided value.
+     * @param value - The provided value.
+     * @param scope - The {@link Scope} of the provided value.
      */
     readonly onProvide?: (value: unknown, scope: Scope) => void;
     /**
      * Called after the container has been disposed.
      *
-     * @param values The values that were cached by the container.
+     * @param values - All distinct values that were cached by the disposed container.
+     *   Currently, only **Container**-scoped token values are cached.
      */
     readonly onDispose?: (values: unknown[]) => void;
 }
@@ -347,10 +352,10 @@ interface Container {
      */
     createChild(options?: Partial<ChildContainerOptions>): Container;
     /**
-     * Clears and returns all distinct cached values from this container's internal registry.
+     * Clears and returns all distinct values that were cached by this container.
      * Values from {@link ValueProvider} registrations are not included, as they are never cached.
      *
-     * Note that only this container is affected. Parent containers, if any, remain unchanged.
+     * Note that only this container is affected. Parent or child containers, if any, remain unchanged.
      */
     clearCache(): unknown[];
     /**
@@ -380,10 +385,11 @@ interface Container {
     /**
      * Removes all registrations from this container's internal registry.
      *
-     * Returns an array of distinct cached values that were stored within the removed registrations.
-     * Values from {@link ValueProvider} registrations are not included, as they are not cached.
+     * Returns an array of the distinct values that were cached by this container for the
+     * removed registrations. Values from {@link ValueProvider} registrations are not included,
+     * as they are not cached.
      *
-     * Note that only this container is affected. Parent containers, if any, remain unchanged.
+     * Note that only this container is affected. Parent or child containers, if any, remain unchanged.
      */
     resetRegistry(): unknown[];
     /**
@@ -432,10 +438,11 @@ interface Container {
     /**
      * Removes all registrations for the given token from the container's internal registry.
      *
-     * Returns an array of distinct cached values that were stored within the removed registrations.
-     * Values from {@link ValueProvider} registrations are not included, as they are not cached.
+     * Returns an array of the distinct values that were cached by this container for the
+     * removed registrations. Values from {@link ValueProvider} registrations are not included,
+     * as they are not cached.
      *
-     * Note that only this container is affected. Parent containers, if any, remain unchanged.
+     * Note that only this container is affected. Parent or child containers, if any, remain unchanged.
      */
     unregister<Value>(token: Token<Value>, name?: string): Value[];
     /**
@@ -650,7 +657,7 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function AutoRegister(): ClassDecorator;
+declare function AutoRegister<This extends object>(): ClassDecorator<This>;
 
 /**
  * Class decorator that sets the class scope to **Container** and enables
@@ -671,7 +678,7 @@ declare function AutoRegister(): ClassDecorator;
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function EagerInstantiate(): ClassDecorator;
+declare function EagerInstantiate<This extends object>(): ClassDecorator<This>;
 
 /**
  * Parameter decorator that injects the instance associated with the given class.
@@ -725,7 +732,14 @@ declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  * class Wand {}
  * ```
  */
-declare function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
+declare function Injectable<Value, This extends Value & object>(token: Token<Value>): ClassDecorator<This>;
+declare function Injectable<VA, VB, This extends VA & VB & object>(tokenA: Token<VA>, //
+tokenB: Token<VB>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, This extends VA & VB & VC & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, VD, This extends VA & VB & VC & VD & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>, tokenD: Token<VD>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, VD, VE, This extends VA & VB & VC & VD & VE & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>, tokenD: Token<VD>, tokenE: Token<VE>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, VD, VE, VF, This extends VA & VB & VC & VD & VE & VF & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>, tokenD: Token<VD>, tokenE: Token<VE>, tokenF: Token<VF>): ClassDecorator<This>;
+declare function Injectable<This extends object>(...tokens: Tokens<unknown>): ClassDecorator<This>;
 /**
  * Class decorator that registers additional aliasing tokens for the decorated type
  * when the type is first registered in the container.
@@ -743,7 +757,7 @@ declare function Injectable<This extends object, Value extends This>(...tokens:
  * class Weapon {}
  * ```
  */
-declare function Injectable<This extends object, Value extends This>(tokens: TokenRef<Value> | TokensRef<Value>): ClassDecorator;
+declare function Injectable<Value, This extends Value & object>(tokens: TokenRef<Value>): ClassDecorator<This>;
 
 /**
  * Parameter decorator that injects all instances provided by the registrations
@@ -803,7 +817,7 @@ declare function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Named(name: string): ClassDecorator & ParameterDecorator;
+declare function Named<This extends object>(name: string): ClassDecorator<This> & ParameterDecorator;
 
 /**
  * Parameter decorator that injects the instance associated with the given class,
@@ -901,7 +915,7 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Scoped(scope: Scope): ClassDecorator;
+declare function Scoped<This extends object>(scope: Scope): ClassDecorator<This>;
 
 /**
  * Injects the instance associated with the given class.
@@ -992,7 +1006,7 @@ declare function injectBy<Value>(thisArg: any, token: Token<Value>, name?: strin
  * Asserts that the current stack frame is within an injection context,
  * meaning it has access to injection functions (`inject`, `optional`, etc.).
  *
- * @param fn The function performing the assertion, or a string name used in the error message.
+ * @param fn - The function performing the assertion, or a string name used in the error message.
  * @throws {Error} If the current stack frame is not within an injection context.
  */
 declare function assertInjectionContext(fn: Function | string): void;
@@ -1103,14 +1117,14 @@ declare const Injector: Type<Injector>;
  * This allows libraries or consumers that manipulate constructors, such as through
  * class decorators, to inform the DI system about the real "identity" of a class.
  *
- * @param transformedClass - The constructor function returned by a class decorator or factory.
- * @param originalClass - The original constructor function.
- *
- * @remarks
- * This API affects the core class identity resolution mechanism of the DI system.
+ * **IMPORTANT**:
+ * this API affects the core class identity resolution mechanism of the DI system.
  * Incorrect usage may cause metadata to be misassociated, leading to subtle errors.
  * Use only when manipulating constructors (e.g., via decorators or proxies),
  * and ensure the mapping is correct.
+ *
+ * @param transformedClass - The constructor function returned by a class decorator or factory.
+ * @param originalClass - The original constructor function.
  */
 declare function setClassIdentityMapping<T extends object>(transformedClass: Constructor<T>, originalClass: Constructor<T>): void;
 
@@ -1172,4 +1186,4 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
 declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
 
 export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, assertInjectionContext, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
-export type { ChildContainerOptions, ClassProvider, ClassRef, Constructor, Container, ContainerHook, ContainerOptions, ExistingProvider, FactoryProvider, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };
+export type { ChildContainerOptions, ClassProvider, ClassRef, Constructor, Container, ContainerHook, ContainerOptions, ExistingProvider, FactoryProvider, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, Type, ValueProvider };

package/dist/es/index.mjs

@@ -31,8 +31,9 @@ function throwResolutionError(tokenInfo, aliases, cause) {
 // @internal
 function throwParameterResolutionError(ctor, methodKey, dependency, cause) {
     const location = getLocation(ctor, methodKey);
+    const [token] = dependency.tokenRef.getRefTokens();
     const tokenName = getFullTokenName([
-        dependency.tokenRef?.getRefToken(),
+        token,
         dependency.name
     ]);
     const msg = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
@@ -165,7 +166,7 @@ function ensureInjectionContext(name) {
  * Asserts that the current stack frame is within an injection context,
  * meaning it has access to injection functions (`inject`, `optional`, etc.).
  *
- * @param fn The function performing the assertion, or a string name used in the error message.
+ * @param fn - The function performing the assertion, or a string name used in the error message.
  * @throws {Error} If the current stack frame is not within an injection context.
  */ function assertInjectionContext(fn) {
     const name = typeof fn === "function" ? `${fn.name || "<unnamed>"}()` : fn;
@@ -224,8 +225,12 @@ function injectBy(thisArg, token, name) {
         getRefClass: ()=>Class()
     };
 }
-// @__NO_SIDE_EFFECTS__
-function tokenRef(token) {
+/**
+ * Allows referencing one or multiple tokens declared later in the file by wrapping them
+ * into a lazily evaluated function.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function tokenRef(token) {
     return {
         getRefTokens: ()=>{
             // Normalize the single token here so that we don't have to do it at every getRefTokens call site
@@ -234,11 +239,6 @@ function tokenRef(token) {
                 tokenOrTokens
             ];
             return new Set(tokensArray);
-        },
-        getRefToken: ()=>{
-            const tokenOrTokens = token();
-            check(!Array.isArray(tokenOrTokens), "internal error: ref tokens should be a single token");
-            return tokenOrTokens;
         }
     };
 }
@@ -247,12 +247,8 @@ function isClassRef(value) {
     return value != null && typeof value === "object" && typeof value.getRefClass === "function";
 }
 // @internal
-function isTokensRef(value) {
-    return value != null && typeof value === "object" && typeof value.getRefTokens === "function";
-}
-// @internal
 function isTokenRef(value) {
-    return value != null && typeof value === "object" && typeof value.getRefToken === "function";
+    return value != null && typeof value === "object" && typeof value.getRefTokens === "function";
 }
 
 // @internal
@@ -262,7 +258,7 @@ class Metadata {
             ctor: [],
             methods: new Map()
         };
-        this.tokensRef = {
+        this.tokenRef = {
             getRefTokens: ()=>new Set()
         };
         this.provider = {
@@ -333,14 +329,14 @@ function getMetadata(classOrRef) {
  * This allows libraries or consumers that manipulate constructors, such as through
  * class decorators, to inform the DI system about the real "identity" of a class.
  *
- * @param transformedClass - The constructor function returned by a class decorator or factory.
- * @param originalClass - The original constructor function.
- *
- * @remarks
- * This API affects the core class identity resolution mechanism of the DI system.
+ * **IMPORTANT**:
+ * this API affects the core class identity resolution mechanism of the DI system.
  * Incorrect usage may cause metadata to be misassociated, leading to subtle errors.
  * Use only when manipulating constructors (e.g., via decorators or proxies),
  * and ensure the mapping is correct.
+ *
+ * @param transformedClass - The constructor function returned by a class decorator or factory.
+ * @param originalClass - The original constructor function.
  */ function setClassIdentityMapping(transformedClass, originalClass) {
     classIdentityMap.set(transformedClass, originalClass);
 }
@@ -554,16 +550,12 @@ class TokenRegistry {
     clearCache() {
         const values = new Set();
         for (const registrations of this.myRegistrations.values()){
-            for(let i = 0; i < registrations.length; i++){
-                const registration = registrations[i];
-                const value = registration.value;
-                if (value) {
-                    values.add(value.current);
+            for (const registration of registrations){
+                const valueRef = registration.valueRef;
+                if (valueRef) {
+                    values.add(valueRef.current);
                 }
-                registrations[i] = {
-                    ...registration,
-                    value: undefined
-                };
+                registration.valueRef = undefined;
             }
         }
         return Array.from(values);
@@ -614,9 +606,11 @@ function isDisposable(value) {
         this.myParent = parent;
         this.myOptions = {
             defaultScope: options?.defaultScope ?? "Transient",
-            autoRegister: options?.autoRegister ?? false
+            autoRegister: options?.autoRegister ?? false,
+            disposeUnmanaged: options?.disposeUnmanaged ?? false
         };
-        this.myHookRegistry = new HookRegistry(parent?.myHookRegistry);
+        const copyHooks = options?.copyHooks ?? true;
+        this.myHookRegistry = new HookRegistry(copyHooks ? parent?.myHookRegistry : undefined);
         this.myTokenRegistry = new TokenRegistry(parent?.myTokenRegistry);
     }
     get registry() {
@@ -637,7 +631,9 @@ function isDisposable(value) {
         this.checkDisposed();
         const container = new ContainerImpl(this, {
             defaultScope: options?.defaultScope ?? this.myOptions.defaultScope,
-            autoRegister: options?.autoRegister ?? this.myOptions.autoRegister
+            autoRegister: options?.autoRegister ?? this.myOptions.autoRegister,
+            disposeUnmanaged: options?.disposeUnmanaged ?? this.myOptions.disposeUnmanaged,
+            copyHooks: options?.copyHooks
         });
         this.myChildren.add(container);
         return container;
@@ -649,16 +645,15 @@ function isDisposable(value) {
     getCached(token) {
         this.checkDisposed();
         const registration = this.myTokenRegistry.get(token);
-        return registration?.value?.current;
+        return registration?.valueRef?.current;
     }
     getAllCached(token) {
         this.checkDisposed();
         const registrations = this.myTokenRegistry.getAll(token);
         const values = new Set();
-        for (const registration of registrations){
-            const value = registration.value;
-            if (value) {
-                values.add(value.current);
+        for (const { valueRef } of registrations){
+            if (valueRef) {
+                values.add(valueRef.current);
             }
         }
         return Array.from(values);
@@ -667,10 +662,9 @@ function isDisposable(value) {
         this.checkDisposed();
         const [, registrations] = this.myTokenRegistry.deleteAll();
         const values = new Set();
-        for (const registration of registrations){
-            const value = registration.value;
-            if (value) {
-                values.add(value.current);
+        for (const { valueRef } of registrations){
+            if (valueRef) {
+                values.add(valueRef.current);
             }
         }
         return Array.from(values);
@@ -697,10 +691,9 @@ function isDisposable(value) {
         this.checkDisposed();
         const registrations = this.myTokenRegistry.delete(token, name);
         const values = new Set();
-        for (const registration of registrations){
-            const value = registration.value;
-            if (value) {
-                values.add(value.current);
+        for (const { valueRef } of registrations){
+            if (valueRef) {
+                values.add(valueRef.current);
             }
         }
         return Array.from(values);
@@ -739,18 +732,23 @@ function isDisposable(value) {
         this.myChildren.clear();
         this.myParent?.myChildren?.delete(this);
         const [, registrations] = this.myTokenRegistry.deleteAll();
-        const values = new Set();
-        for (const registration of registrations){
-            // Only container-scoped registrations use 'registration.value'
-            if (registration.value) {
-                const value = registration.value.current;
-                // Dispose all cached values that implement the Disposable interface
-                if (!values.has(value) && values.add(value) && isDisposable(value)) {
-                    value.dispose();
-                }
+        const disposeUnmanaged = this.myOptions.disposeUnmanaged;
+        const cacheValues = new Set();
+        const allValues = new Set();
+        for (const { provider, valueRef } of registrations){
+            if (valueRef) {
+                cacheValues.add(valueRef.current);
+                allValues.add(valueRef.current);
+            } else if (disposeUnmanaged && isValueProvider(provider)) {
+                allValues.add(provider.useValue);
+            }
+        }
+        for (const value of allValues){
+            if (isDisposable(value)) {
+                value.dispose();
             }
         }
-        this.notifyDisposeHooks(Array.from(values));
+        this.notifyDisposeHooks(Array.from(cacheValues));
         this.myHookRegistry.clear();
     }
     registerClass(Class) {
@@ -769,7 +767,7 @@ function isDisposable(value) {
         this.myTokenRegistry.put(Class, registration);
         // Register the additional tokens specified via class decorators.
         // These tokens will point to the original Class token and will have the same scope.
-        for (const token of metadata.tokensRef.getRefTokens()){
+        for (const token of metadata.tokenRef.getRefTokens()){
             this.myTokenRegistry.put(token, {
                 name: name,
                 provider: {
@@ -960,13 +958,13 @@ function isDisposable(value) {
             switch(scope){
                 case "Container":
                     {
-                        const valueRef = registration.value;
+                        const valueRef = registration.valueRef;
                         if (valueRef) {
                             return valueRef.current;
                         }
                         const args = this.resolveCtorDependencies(registration);
                         const value = this.injectMethodDependencies(registration, factory(args));
-                        registration.value = {
+                        registration.valueRef = {
                             current: value
                         };
                         this.notifyProvideHooks(value, scope);
@@ -1055,7 +1053,7 @@ function isDisposable(value) {
     }
     // Call context: decorator-based injection
     resolveDependency(dependency, instance) {
-        const token = dependency.tokenRef?.getRefToken();
+        const [token] = dependency.tokenRef.getRefTokens();
         check(token, `token passed to @${dependency.appliedBy} was undefined (possible circular imports)`);
         const name = dependency.name;
         switch(dependency.appliedBy){
@@ -1131,12 +1129,11 @@ function isDisposable(value) {
  * @__NO_SIDE_EFFECTS__
  */ function EagerInstantiate() {
     return function(Class) {
-        const ctor = Class;
-        const metadata = getMetadata(ctor);
+        const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === "Container", ()=>{
             const { value, appliedBy } = currentScope;
-            const className = getTokenName(ctor);
+            const className = getTokenName(Class);
             return `class ${className}: scope ${value} was already set by @${appliedBy},\n  ` + `but @EagerInstantiate is trying to set a conflicting scope Container.\n  ` + `Only one decorator should set the class scope, or all must agree on the same value.`;
         });
         metadata.eagerInstantiate = true;
@@ -1163,12 +1160,12 @@ function Injectable(...args) {
     return function(Class) {
         const metadata = getMetadata(Class);
         const arg0 = args[0];
-        const tokensRef = isTokensRef(arg0) ? arg0 : tokenRef(()=>args);
-        const existingTokensRef = metadata.tokensRef;
-        metadata.tokensRef = {
+        const ref = isTokenRef(arg0) ? arg0 : tokenRef(()=>args);
+        const existingTokensRef = metadata.tokenRef;
+        metadata.tokenRef = {
             getRefTokens: ()=>{
                 const existingTokens = existingTokensRef.getRefTokens();
-                for (const token of tokensRef.getRefTokens()){
+                for (const token of ref.getRefTokens()){
                     existingTokens.add(token);
                 }
                 return existingTokens;
@@ -1211,9 +1208,9 @@ function InjectAll(token) {
     return function(target, propertyKey, parameterIndex) {
         if (parameterIndex === undefined) {
             // The decorator has been applied to the class
-            const ctor = target;
-            const metadata = getMetadata(ctor);
-            const className = getTokenName(ctor);
+            const Class = target;
+            const metadata = getMetadata(Class);
+            const className = getTokenName(Class);
             check(metadata.name === undefined, `multiple @Named decorators on class ${className}, but only one is allowed`);
             metadata.name = name;
         } else {
@@ -1276,13 +1273,12 @@ function OptionalAll(token) {
  * @__NO_SIDE_EFFECTS__
  */ function Scoped(scope) {
     return function(Class) {
-        const ctor = Class;
-        const metadata = getMetadata(ctor);
+        const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === scope, ()=>{
             const { value, appliedBy } = currentScope;
             const by = appliedBy === "Scoped" ? `another @${appliedBy} decorator` : `@${appliedBy}`;
-            const className = getTokenName(ctor);
+            const className = getTokenName(Class);
             return `class ${className}: scope ${value} was already set by ${by},\n  ` + `but @Scoped is trying to set a conflicting scope ${scope}.\n  ` + `Only one decorator should set the class scope, or all must agree on the same value.`;
         });
         metadata.scope = {