@lppedd/di-wise-neo 0.6.0 → 0.7.0

package/dist/es/index.mjs

@@ -127,23 +127,23 @@ function ensureInjectionContext(fn) {
     return context;
 }
 
-function inject(token) {
+function inject(token, name) {
     const context = ensureInjectionContext(inject);
-    return context.container.resolve(token);
+    return context.container.resolve(token, name);
 }
-function injectBy(thisArg, token) {
+function injectBy(thisArg, token, name) {
     const context = ensureInjectionContext(injectBy);
     const resolution = context.resolution;
     const currentFrame = resolution.stack.peek();
     if (!currentFrame) {
-        return inject(token);
+        return inject(token, name);
     }
     const currentRef = {
         current: thisArg
     };
     const cleanup = resolution.dependents.set(currentFrame.provider, currentRef);
     try {
-        return inject(token);
+        return inject(token, name);
     } finally{
         cleanup();
     }
@@ -154,41 +154,59 @@ function injectAll(token) {
     return context.container.resolveAll(token);
 }
 
-/**
- * Registers a mapping between a generated (e.g., decorated or proxied) constructor
- * and its original, underlying constructor.
- *
- * 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.
- * 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.
- */ function setClassIdentityMapping(transformedClass, originalClass) {
-    classIdentityMap.set(transformedClass, originalClass);
+// @internal
+class Metadata {
+    constructor(Class){
+        this.dependencies = {
+            constructor: [],
+            methods: new Map()
+        };
+        this.tokensRef = {
+            getRefTokens: ()=>new Set()
+        };
+        this.provider = {
+            useClass: Class
+        };
+    }
+    get name() {
+        return this.provider.name;
+    }
+    set name(name) {
+        this.provider.name = name;
+    }
+    getConstructorDependency(index) {
+        const i = this.dependencies.constructor.findIndex((d)=>d.index === index);
+        if (i > -1) {
+            return this.dependencies.constructor[i];
+        }
+        const dependency = {
+            index: index
+        };
+        this.dependencies.constructor.push(dependency);
+        return dependency;
+    }
+    getMethodDependency(method, index) {
+        let methodDeps = this.dependencies.methods.get(method);
+        if (!methodDeps) {
+            this.dependencies.methods.set(method, methodDeps = []);
+        }
+        const i = methodDeps.findIndex((d)=>d.index === index);
+        if (i > -1) {
+            return methodDeps[i];
+        }
+        const dependency = {
+            index: index
+        };
+        methodDeps.push(dependency);
+        return dependency;
+    }
 }
 // @internal
 function getMetadata(Class) {
     const originalClass = classIdentityMap.get(Class) ?? Class;
     let metadata = metadataMap.get(originalClass);
     if (!metadata) {
-        metadataMap.set(originalClass, metadata = {
-            tokensRef: {
-                getRefTokens: ()=>new Set()
-            },
-            provider: {
-                useClass: originalClass
-            },
-            dependencies: {
-                constructor: [],
-                methods: new Map()
-            }
-        });
+        metadataMap.set(originalClass, metadata = new Metadata(originalClass));
     }
     if (metadata.provider.useClass !== Class) {
         // This is part of the class identity mapping API (see setClassIdentityMapping).
@@ -202,32 +220,48 @@ function getMetadata(Class) {
         // We must update useClass to be the extender class B so that instances created by the
         // DI container match the consumer's registered class. Without this update, the DI
         // system would instantiate the original class A, causing behavior inconsistencies.
-        //
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
         metadata.provider.useClass = Class;
     }
     return metadata;
 }
+/**
+ * Registers a mapping between a generated (e.g., decorated or proxied) constructor
+ * and its original, underlying constructor.
+ *
+ * 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.
+ * 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.
+ */ function setClassIdentityMapping(transformedClass, originalClass) {
+    classIdentityMap.set(transformedClass, originalClass);
+}
 const classIdentityMap = new WeakMap();
 const metadataMap = new WeakMap();
 
-function optional(token) {
+function optional(token, name) {
     const context = ensureInjectionContext(optional);
-    return context.container.resolve(token, true);
+    return context.container.resolve(token, true, name);
 }
-function optionalBy(thisArg, token) {
+function optionalBy(thisArg, token, name) {
     const context = ensureInjectionContext(optionalBy);
     const resolution = context.resolution;
     const currentFrame = resolution.stack.peek();
     if (!currentFrame) {
-        return optional(token);
+        return optional(token, name);
     }
     const currentRef = {
         current: thisArg
     };
     const cleanup = resolution.dependents.set(currentFrame.provider, currentRef);
     try {
-        return optional(token);
+        return optional(token, name);
     } finally{
         cleanup();
     }
@@ -286,28 +320,29 @@ const Scope = {
 }
 // @internal
 function isConstructor(token) {
-    return typeof token == "function";
+    return typeof token === "function";
 }
 
 // @internal
 function getTypeName(value) {
-    if (typeof value == "string") {
-        return `"${value}"`;
-    }
-    if (typeof value == "function") {
-        return value.name && `typeof ${value.name}` || "Function";
-    }
-    if (typeof value == "object") {
-        if (value === null) {
-            return "null";
-        }
-        const proto = Object.getPrototypeOf(value);
-        if (proto && proto !== Object.prototype) {
-            const constructor = proto.constructor;
-            if (typeof constructor == "function" && constructor.name) {
-                return constructor.name;
+    switch(typeof value){
+        case "string":
+            return `"${value}"`;
+        case "function":
+            return value.name && `typeof ${value.name}` || "Function";
+        case "object":
+            {
+                if (value === null) {
+                    return "null";
+                }
+                const proto = Object.getPrototypeOf(value);
+                if (proto && proto !== Object.prototype) {
+                    const constructor = proto.constructor;
+                    if (typeof constructor === "function" && constructor.name) {
+                        return constructor.name;
+                    }
+                }
             }
-        }
     }
     return typeof value;
 }
@@ -318,28 +353,46 @@ class TokenRegistry {
         this.myMap = new Map();
         this.myParent = parent;
     }
-    get(token) {
+    get(token, name) {
         // To clarify, at(-1) means we take the last added registration for this token
-        return this.getAll(token)?.at(-1);
+        return this.getAll(token, name).at(-1);
     }
-    getAll(token) {
-        const internal = internals.get(token);
+    getAll(token, name) {
+        // Internal registrations cannot have a name
+        const internal = name !== undefined ? undefined : internals.get(token);
         return internal && [
             internal
-        ] || this.getAllFromParent(token);
+        ] || this.getAllFromParent(token, name);
     }
     set(token, registration) {
         assert(!internals.has(token), `cannot register reserved token ${token.name}`);
         let registrations = this.myMap.get(token);
         if (!registrations) {
             this.myMap.set(token, registrations = []);
+        } else if (registration.name !== undefined) {
+            const existing = registrations.filter((r)=>r.name === registration.name);
+            assert(existing.length === 0, `a ${token.name} token named '${registration.name}' is already registered`);
         }
         registrations.push(registration);
     }
-    delete(token) {
+    delete(token, name) {
         const registrations = this.myMap.get(token);
-        this.myMap.delete(token);
-        return registrations;
+        if (registrations) {
+            if (name !== undefined) {
+                const removedRegistrations = [];
+                const newRegistrations = [];
+                for (const registration of registrations){
+                    const array = registration.name === name ? removedRegistrations : newRegistrations;
+                    array.push(registration);
+                }
+                if (removedRegistrations.length > 0) {
+                    this.myMap.set(token, newRegistrations);
+                    return removedRegistrations;
+                }
+            }
+            this.myMap.delete(token);
+        }
+        return registrations ?? [];
     }
     deleteAll() {
         const tokens = Array.from(this.myMap.keys());
@@ -367,9 +420,14 @@ class TokenRegistry {
         }
         return Array.from(values);
     }
-    getAllFromParent(token) {
-        const registrations = this.myMap.get(token);
-        return registrations || this.myParent?.getAllFromParent(token);
+    getAllFromParent(token, name) {
+        const thisRegistrations = this.myMap.get(token);
+        let registrations = thisRegistrations || this.myParent?.getAllFromParent(token, name);
+        if (registrations && name !== undefined) {
+            registrations = registrations.filter((r)=>r.name === name);
+            assert(registrations.length < 2, `internal error: more than one registration named '${name}'`);
+        }
+        return registrations ?? [];
     }
 }
 // @internal
@@ -467,9 +525,6 @@ function isDisposable(value) {
     getAllCached(token) {
         this.checkDisposed();
         const registrations = this.myTokenRegistry.getAll(token);
-        if (!registrations) {
-            return [];
-        }
         const values = new Set();
         for (const registration of registrations){
             const value = registration.value;
@@ -491,46 +546,17 @@ function isDisposable(value) {
         }
         return Array.from(values);
     }
-    isRegistered(token) {
+    isRegistered(token, name) {
         this.checkDisposed();
-        return this.myTokenRegistry.get(token) !== undefined;
-    }
-    registerClass(token, Class, options) {
-        // This mess will go away once/if we remove the register method
-        // in favor of the multiple specialized ones
-        if (Class) {
-            const ctor = Class ?? token;
-            this.register(token, {
-                useClass: ctor
-            }, options);
-        } else {
-            this.register(token);
-        }
-    }
-    registerFactory(token, factory, options) {
-        this.register(token, {
-            useFactory: factory
-        }, options);
-    }
-    registerValue(token, value) {
-        this.register(token, {
-            useValue: value
-        });
-    }
-    registerAlias(targetToken, aliasTokens) {
-        // De-duplicate tokens
-        for (const alias of new Set(aliasTokens)){
-            this.register(alias, {
-                useExisting: targetToken
-            });
-        }
+        return this.myTokenRegistry.get(token, name) !== undefined;
     }
     register(...args) {
         this.checkDisposed();
-        if (args.length == 1) {
+        if (args.length === 1) {
             const Class = args[0];
             const metadata = getMetadata(Class);
             const registration = {
+                name: metadata.name,
                 // The provider is of type ClassProvider, initialized by getMetadata
                 provider: metadata.provider,
                 options: {
@@ -558,10 +584,11 @@ function isDisposable(value) {
             if (isClassProvider(provider)) {
                 const metadata = getMetadata(provider.useClass);
                 const registration = {
+                    // An explicit provider name overrides what is specified via @Named
+                    name: metadata.name ?? provider.name,
                     provider: metadata.provider,
                     options: {
-                        // The explicit registration options override what is specified
-                        // via class decorators (e.g., @Scoped)
+                        // Explicit registration options override what is specified via class decorators (e.g., @Scoped)
                         scope: metadata.scope?.value ?? this.myOptions.defaultScope,
                         ...options
                     },
@@ -573,10 +600,12 @@ function isDisposable(value) {
                     this.resolveProviderValue(registration, registration.provider);
                 }
             } else {
-                if (isExistingProvider(provider)) {
+                const existingProvider = isExistingProvider(provider);
+                if (existingProvider) {
                     assert(token !== provider.useExisting, `the useExisting token ${token.name} cannot be the same as the token being registered`);
                 }
                 this.myTokenRegistry.set(token, {
+                    name: existingProvider ? undefined : provider.name,
                     provider: provider,
                     options: options
                 });
@@ -584,12 +613,9 @@ function isDisposable(value) {
         }
         return this;
     }
-    unregister(token) {
+    unregister(token, name) {
         this.checkDisposed();
-        const registrations = this.myTokenRegistry.delete(token);
-        if (!registrations) {
-            return [];
-        }
+        const registrations = this.myTokenRegistry.delete(token, name);
         const values = new Set();
         for (const registration of registrations){
             const value = registration.value;
@@ -599,22 +625,31 @@ function isDisposable(value) {
         }
         return Array.from(values);
     }
-    resolve(token, optional) {
+    resolve(token, optionalOrName, name) {
         this.checkDisposed();
-        const registration = this.myTokenRegistry.get(token);
+        let localOptional;
+        let localName;
+        if (typeof optionalOrName === "string") {
+            localName = optionalOrName;
+        } else {
+            localOptional = optionalOrName;
+            localName = name;
+        }
+        const registration = this.myTokenRegistry.get(token, localName);
         if (registration) {
-            return this.resolveRegistration(token, registration);
+            return this.resolveRegistration(token, registration, localName);
         }
         if (isConstructor(token)) {
-            return this.instantiateClass(token, optional);
+            return this.instantiateClass(token, localOptional);
         }
-        return optional ? undefined : throwUnregisteredError(token);
+        return optionalOrName ? undefined : throwUnregisteredError(token);
     }
     resolveAll(token, optional) {
         this.checkDisposed();
         const registrations = this.myTokenRegistry.getAll(token);
-        if (registrations) {
-            return registrations.map((registration)=>this.resolveRegistration(token, registration)).filter((value)=>value != null);
+        if (registrations.length > 0) {
+            return registrations //
+            .map((registration)=>this.resolveRegistration(token, registration)).filter((value)=>value != null);
         }
         if (isConstructor(token)) {
             const instance = this.instantiateClass(token, optional);
@@ -650,12 +685,12 @@ function isDisposable(value) {
         // Allow values to be GCed
         disposedRefs.clear();
     }
-    resolveRegistration(token, registration) {
+    resolveRegistration(token, registration, name) {
         let currRegistration = registration;
         let currProvider = currRegistration.provider;
         while(isExistingProvider(currProvider)){
             const targetToken = currProvider.useExisting;
-            currRegistration = this.myTokenRegistry.get(targetToken);
+            currRegistration = this.myTokenRegistry.get(targetToken, name);
             if (!currRegistration) {
                 throwExistingUnregisteredError(token, targetToken);
             }
@@ -786,7 +821,7 @@ function isDisposable(value) {
         }
     }
     resolveScope(scope = this.myOptions.defaultScope, context = useInjectionContext()) {
-        if (scope == Scope.Inherited) {
+        if (scope === Scope.Inherited) {
             const dependentFrame = context?.resolution.stack.peek();
             return dependentFrame?.scope || Scope.Transient;
         }
@@ -796,7 +831,7 @@ function isDisposable(value) {
         const dependencies = registration.dependencies;
         if (dependencies) {
             assert(isClassProvider(registration.provider), `internal error: not a ClassProvider`);
-            const ctorDeps = dependencies.constructor;
+            const ctorDeps = dependencies.constructor.filter((d)=>d.appliedBy);
             if (ctorDeps.length > 0) {
                 // Let's check if all necessary constructor parameters are decorated.
                 // If not, we cannot safely create an instance.
@@ -807,13 +842,13 @@ function isDisposable(value) {
                 });
                 return ctorDeps.sort((a, b)=>a.index - b.index).map((dep)=>{
                     const token = dep.tokenRef.getRefToken();
-                    switch(dep.decorator){
+                    switch(dep.appliedBy){
                         case "Inject":
-                            return this.resolve(token);
+                            return this.resolve(token, dep.name);
                         case "InjectAll":
                             return this.resolveAll(token);
                         case "Optional":
-                            return this.resolve(token, true);
+                            return this.resolve(token, true, dep.name);
                         case "OptionalAll":
                             return this.resolveAll(token, true);
                     }
@@ -828,7 +863,9 @@ function isDisposable(value) {
             assert(isClassProvider(registration.provider), `internal error: not a ClassProvider`);
             const ctor = registration.provider.useClass;
             // Perform method injection
-            for (const [key, methodDeps] of dependencies.methods){
+            for (const entry of dependencies.methods){
+                const key = entry[0];
+                const methodDeps = entry[1].filter((d)=>d.appliedBy);
                 // Let's check if all necessary method parameters are decorated.
                 // If not, we cannot safely invoke the method.
                 // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
@@ -839,13 +876,13 @@ function isDisposable(value) {
                 });
                 const args = methodDeps.sort((a, b)=>a.index - b.index).map((dep)=>{
                     const token = dep.tokenRef.getRefToken();
-                    switch(dep.decorator){
+                    switch(dep.appliedBy){
                         case "Inject":
-                            return injectBy(instance, token);
+                            return injectBy(instance, token, dep.name);
                         case "InjectAll":
                             return injectAll(token);
                         case "Optional":
-                            return optionalBy(instance, token);
+                            return optionalBy(instance, token, dep.name);
                         case "OptionalAll":
                             return optionalAll(token);
                     }
@@ -905,7 +942,7 @@ function isDisposable(value) {
  *
  * // Wizard is registered with Container scope, and an instance
  * // is immediately created and cached by the container
- * const wizard = container.register(Wizard);
+ * container.register(Wizard);
  * ```
  *
  * @__NO_SIDE_EFFECTS__
@@ -954,41 +991,31 @@ function isTokenRef(value) {
     return value && typeof value === "object" && typeof value.getRefToken === "function";
 }
 
-function processDecoratedParameter(decorator, token, target, propertyKey, parameterIndex) {
-    // Error out immediately if the decorator has been applied
-    // to a static property or a static method
+// @internal
+function updateParameterMetadata(decorator, target, propertyKey, parameterIndex, updateFn) {
+    // Error out immediately if the decorator has been applied to a static method
     if (propertyKey !== undefined && typeof target === "function") {
-        assert(false, `@${decorator} cannot be used on static member ${target.name}.${String(propertyKey)}`);
+        assert(false, `@${decorator} cannot be used on static method ${target.name}.${String(propertyKey)}`);
     }
-    const tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
     if (propertyKey === undefined) {
         // Constructor
         const metadata = getMetadata(target);
-        metadata.dependencies.constructor.push({
-            decorator: decorator,
-            tokenRef: tokenRef,
-            index: parameterIndex
-        });
+        const dependency = metadata.getConstructorDependency(parameterIndex);
+        updateFn(dependency);
     } else {
-        // Normal instance method
+        // Instance method
         const metadata = getMetadata(target.constructor);
-        const methods = metadata.dependencies.methods;
-        let dep = methods.get(propertyKey);
-        if (dep === undefined) {
-            dep = [];
-            methods.set(propertyKey, dep);
-        }
-        dep.push({
-            decorator: decorator,
-            tokenRef: tokenRef,
-            index: parameterIndex
-        });
+        const dependency = metadata.getMethodDependency(propertyKey, parameterIndex);
+        updateFn(dependency);
     }
 }
 
 function Inject(token) {
     return function(target, propertyKey, parameterIndex) {
-        processDecoratedParameter("Inject", token, target, propertyKey, parameterIndex);
+        updateParameterMetadata("Inject", target, propertyKey, parameterIndex, (dependency)=>{
+            dependency.appliedBy = "Inject";
+            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+        });
     };
 }
 
@@ -1014,19 +1041,66 @@ function Inject(token) {
 
 function InjectAll(token) {
     return function(target, propertyKey, parameterIndex) {
-        processDecoratedParameter("InjectAll", token, target, propertyKey, parameterIndex);
+        updateParameterMetadata("InjectAll", target, propertyKey, parameterIndex, (dependency)=>{
+            dependency.appliedBy = "InjectAll";
+            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+        });
+    };
+}
+
+/**
+ * Qualifies a class or an injected parameter with a unique name.
+ *
+ * This allows the container to distinguish between multiple implementations
+ * of the same interface or type during registration and injection.
+ *
+ * @example
+ * ```ts
+ * @Named("dumbledore")
+ * class Dumbledore implements Wizard {}
+ *
+ * // Register Dumbledore with Type<Wizard>
+ * container.register(IWizard, { useClass: Dumbledore });
+ * const dumbledore = container.resolve(IWizard, "dumbledore");
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function Named(name) {
+    if (!name.trim()) {
+        assert(false, "the @Named qualifier cannot be empty or blank");
+    }
+    return function(target, propertyKey, parameterIndex) {
+        if (parameterIndex === undefined) {
+            // The decorator has been applied to the class
+            const ctor = target;
+            const metadata = getMetadata(ctor);
+            assert(!metadata.name, `a @Named('${metadata.name}') qualifier has already been applied to ${ctor.name}`);
+            metadata.name = name;
+        } else {
+            // The decorator has been applied to a method parameter
+            updateParameterMetadata("Named", target, propertyKey, parameterIndex, (dependency)=>{
+                assert(!dependency.name, `a @Named('${dependency.name}') qualifier has already been applied to the parameter`);
+                dependency.name = name;
+            });
+        }
     };
 }
 
 function Optional(token) {
     return function(target, propertyKey, parameterIndex) {
-        processDecoratedParameter("Optional", token, target, propertyKey, parameterIndex);
+        updateParameterMetadata("Optional", target, propertyKey, parameterIndex, (dependency)=>{
+            dependency.appliedBy = "Optional";
+            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+        });
     };
 }
 
 function OptionalAll(token) {
     return function(target, propertyKey, parameterIndex) {
-        processDecoratedParameter("OptionalAll", token, target, propertyKey, parameterIndex);
+        updateParameterMetadata("OptionalAll", target, propertyKey, parameterIndex, (dependency)=>{
+            dependency.appliedBy = "OptionalAll";
+            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+        });
     };
 }
 
@@ -1158,5 +1232,5 @@ function OptionalAll(token) {
     return container;
 }
 
-export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy, setClassIdentityMapping };
+export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy, setClassIdentityMapping };
 //# sourceMappingURL=index.mjs.map