@lppedd/di-wise-neo 0.9.1 → 0.9.3

package/dist/es/index.mjs

@@ -1,30 +1,3 @@
-/**
- * Type API.
- */ /**
- * Creates a type token.
- *
- * @example
- * ```ts
- * const ISpell = createType<Spell>("Spell");
- * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function createType(typeName) {
-    const type = {
-        name: `Type<${typeName}>`,
-        inter: createType,
-        union: createType,
-        toString () {
-            return type.name;
-        }
-    };
-    return type;
-}
-// @internal
-function isConstructor(token) {
-    return typeof token === "function";
-}
-
 // @internal
 function check(condition, message) {
     if (!condition) {
@@ -37,18 +10,35 @@ function expectNever(value) {
 }
 // @internal
 function throwUnregisteredError(token, name) {
-    const type = isConstructor(token) ? "class" : "token";
     const spec = name !== undefined ? `[name=${name}]` : "";
-    throw new Error(tag(`unregistered ${type} ${token.name}${spec}`));
+    throw new Error(tag(`unregistered token ${getTokenName(token)}${spec}`));
 }
 // @internal
-function throwExistingUnregisteredError(sourceToken, targetTokenOrError) {
-    let message = tag(`token resolution error encountered while resolving ${sourceToken.name}`);
-    message += isError(targetTokenOrError) ? `\n  [cause] ${untag(targetTokenOrError.message)}` : `\n  [cause] the aliased token ${targetTokenOrError.name} is not registered`;
-    throw new Error(message);
+function throwExistingUnregisteredError(token, cause) {
+    const message = tag(`failed to resolve token ${getTokenName(token)}`);
+    throw isError(cause) ? new Error(`${message}\n  [cause] ${untag(cause.message)}`, {
+        cause
+    }) : new Error(`${message}\n  [cause] the aliased token ${getTokenName(cause)} is not registered`);
+}
+// @internal
+function throwParameterResolutionError(ctor, methodKey, dependency, cause) {
+    const location = getLocation(ctor, methodKey);
+    const token = dependency.tokenRef.getRefToken();
+    const message = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${token.name})`);
+    throw new Error(`${message}\n  [cause] ${untag(cause.message)}`, {
+        cause
+    });
+}
+// @internal
+function getLocation(ctor, methodKey) {
+    const ctorName = ctor.name || "<unnamed>";
+    return methodKey ? `${ctorName}.${String(methodKey)}` : ctorName;
+}
+// @internal
+function getTokenName(token) {
+    return token.name || "<unnamed>";
 }
 function isError(value) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     return value && value.stack && value.message && typeof value.message === "string";
 }
 function tag(message) {
@@ -80,7 +70,7 @@ class KeyedStack {
         };
     }
     constructor(){
-        this.myEntries = new Array();
+        this.myEntries = [];
         this.myKeys = new WeakSet();
     }
 }
@@ -113,6 +103,7 @@ class WeakRefMap {
 // @internal
 function createResolution() {
     return {
+        tokenStack: [],
         stack: new KeyedStack(),
         values: new WeakRefMap(),
         dependents: new WeakRefMap()
@@ -173,7 +164,7 @@ function injectAll(token) {
 class Metadata {
     constructor(Class){
         this.dependencies = {
-            constructor: [],
+            ctor: [],
             methods: new Map()
         };
         this.tokensRef = {
@@ -189,15 +180,15 @@ class Metadata {
     set name(name) {
         this.provider.name = name;
     }
-    getConstructorDependency(index) {
-        const i = this.dependencies.constructor.findIndex((d)=>d.index === index);
+    getCtorDependency(index) {
+        const i = this.dependencies.ctor.findIndex((d)=>d.index === index);
         if (i > -1) {
-            return this.dependencies.constructor[i];
+            return this.dependencies.ctor[i];
         }
         const dependency = {
             index: index
         };
-        this.dependencies.constructor.push(dependency);
+        this.dependencies.ctor.push(dependency);
         return dependency;
     }
     getMethodDependency(method, index) {
@@ -311,6 +302,33 @@ const Scope = {
     Container: "Container"
 };
 
+/**
+ * Type API.
+ */ /**
+ * Creates a type token.
+ *
+ * @example
+ * ```ts
+ * const ISpell = createType<Spell>("Spell");
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function createType(typeName) {
+    const type = {
+        name: `Type<${typeName}>`,
+        inter: createType,
+        union: createType,
+        toString () {
+            return type.name;
+        }
+    };
+    return type;
+}
+// @internal
+function isConstructor(token) {
+    return typeof token === "function";
+}
+
 // @internal
 function getTypeName(value) {
     switch(typeof value){
@@ -325,9 +343,9 @@ function getTypeName(value) {
                 }
                 const proto = Object.getPrototypeOf(value);
                 if (proto && proto !== Object.prototype) {
-                    const constructor = proto.constructor;
-                    if (typeof constructor === "function" && constructor.name) {
-                        return constructor.name;
+                    const ctor = proto.constructor;
+                    if (typeof ctor === "function" && ctor.name) {
+                        return ctor.name;
                     }
                 }
             }
@@ -443,7 +461,6 @@ const builders = new WeakSet();
 // @internal
 // @internal
 function isDisposable(value) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     return value && typeof value === "object" && typeof value.dispose === "function";
 }
 
@@ -548,13 +565,13 @@ function isDisposable(value) {
             }
             // Eager-instantiate only if the class is container-scoped
             if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
-                this.resolveProviderValue(registration, registration.provider);
+                this.resolveProviderValue(Class, registration);
             }
         } else {
             const [token, provider, options] = args;
             const existingProvider = isExistingProvider(provider);
             const name = existingProvider ? undefined : provider.name;
-            check(name === undefined || name.trim(), "the provider name qualifier cannot be empty or blank");
+            check(name === undefined || name.trim(), `the name qualifier for token ${getTokenName(token)} must not be empty`);
             if (isClassProvider(provider)) {
                 const metadata = getMetadata(provider.useClass);
                 const registration = {
@@ -571,7 +588,7 @@ function isDisposable(value) {
                 this.myTokenRegistry.set(token, registration);
                 // Eager-instantiate only if the provided class is container-scoped
                 if (metadata.eagerInstantiate && registration.options?.scope === Scope.Container) {
-                    this.resolveProviderValue(registration, registration.provider);
+                    this.resolveProviderValue(token, registration);
                 }
             } else {
                 if (existingProvider) {
@@ -661,17 +678,15 @@ function isDisposable(value) {
     }
     resolveRegistration(token, registration, name) {
         let currRegistration = registration;
-        let currProvider = currRegistration.provider;
-        while(isExistingProvider(currProvider)){
-            const targetToken = currProvider.useExisting;
+        while(isExistingProvider(currRegistration.provider)){
+            const targetToken = currRegistration.provider.useExisting;
             currRegistration = this.myTokenRegistry.get(targetToken, name);
             if (!currRegistration) {
                 throwExistingUnregisteredError(token, targetToken);
             }
-            currProvider = currRegistration.provider;
         }
         try {
-            return this.resolveProviderValue(currRegistration, currProvider);
+            return this.resolveProviderValue(token, currRegistration);
         } catch (e) {
             // If we were trying to resolve a token registered via ExistingProvider,
             // we must add the cause of the error to the message
@@ -698,16 +713,15 @@ function isDisposable(value) {
         }
         return undefined;
     }
-    resolveProviderValue(registration, provider) {
-        check(registration.provider === provider, "internal error: mismatching provider");
+    resolveProviderValue(token, registration) {
+        const provider = registration.provider;
         if (isClassProvider(provider)) {
             const Class = provider.useClass;
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-            return this.resolveScopedValue(registration, (args)=>new Class(...args));
+            return this.resolveScopedValue(token, registration, (args)=>new Class(...args));
         }
         if (isFactoryProvider(provider)) {
             const factory = provider.useFactory;
-            return this.resolveScopedValue(registration, factory);
+            return this.resolveScopedValue(token, registration, factory);
         }
         if (isValueProvider(provider)) {
             return provider.useValue;
@@ -715,7 +729,7 @@ function isDisposable(value) {
         check(!isExistingProvider(provider), "internal error: unexpected ExistingProvider");
         expectNever(provider);
     }
-    resolveScopedValue(registration, factory) {
+    resolveScopedValue(token, registration, factory) {
         let context = useInjectionContext();
         if (!context || context.container !== this) {
             context = {
@@ -728,12 +742,16 @@ function isDisposable(value) {
         const options = registration.options;
         if (resolution.stack.has(provider)) {
             const dependentRef = resolution.dependents.get(provider);
-            check(dependentRef, "circular dependency detected");
+            check(dependentRef, ()=>{
+                const path = resolution.tokenStack.map((t)=>t.name).join(" → ");
+                return `circular dependency detected while resolving ${path} → ${token.name}`;
+            });
             return dependentRef.current;
         }
         const scope = this.resolveScope(options?.scope, context);
         const cleanups = [
             provideInjectionContext(context),
+            resolution.tokenStack.push(token) && (()=>resolution.tokenStack.pop()),
             !isBuilder(provider) && resolution.stack.push(provider, {
                 provider,
                 scope
@@ -747,8 +765,8 @@ function isDisposable(value) {
                         if (valueRef) {
                             return valueRef.current;
                         }
-                        const args = this.resolveConstructorDependencies(registration);
-                        const value = this.injectDependencies(registration, factory(args));
+                        const args = this.resolveCtorDependencies(registration);
+                        const value = this.injectMethodDependencies(registration, factory(args));
                         registration.value = {
                             current: value
                         };
@@ -760,8 +778,8 @@ function isDisposable(value) {
                         if (valueRef) {
                             return valueRef.current;
                         }
-                        const args = this.resolveConstructorDependencies(registration);
-                        const value = this.injectDependencies(registration, factory(args));
+                        const args = this.resolveCtorDependencies(registration);
+                        const value = this.injectMethodDependencies(registration, factory(args));
                         resolution.values.set(provider, {
                             current: value
                         });
@@ -769,8 +787,8 @@ function isDisposable(value) {
                     }
                 case Scope.Transient:
                     {
-                        const args = this.resolveConstructorDependencies(registration);
-                        return this.injectDependencies(registration, factory(args));
+                        const args = this.resolveCtorDependencies(registration);
+                        return this.injectMethodDependencies(registration, factory(args));
                     }
             }
         } finally{
@@ -784,72 +802,74 @@ function isDisposable(value) {
         }
         return scope;
     }
-    resolveConstructorDependencies(registration) {
+    resolveCtorDependencies(registration) {
         const dependencies = registration.dependencies;
         if (dependencies) {
             check(isClassProvider(registration.provider), `internal error: not a ClassProvider`);
-            const ctorDeps = dependencies.constructor.filter((d)=>d.appliedBy);
+            const ctorDeps = dependencies.ctor.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.
                 const ctor = registration.provider.useClass;
                 check(ctor.length === ctorDeps.length, ()=>{
-                    const msg = `expected ${ctor.length} decorated constructor parameters in ${ctor.name}`;
+                    const location = getLocation(ctor);
+                    const msg = `${location} expected ${ctor.length} decorated constructor parameters`;
                     return msg + `, but found ${ctorDeps.length}`;
                 });
-                return ctorDeps.sort((a, b)=>a.index - b.index).map((dep)=>{
-                    const token = dep.tokenRef.getRefToken();
-                    switch(dep.appliedBy){
-                        case "Inject":
-                            return this.resolve(token, dep.name);
-                        case "InjectAll":
-                            return this.resolveAll(token);
-                        case "Optional":
-                            return this.resolve(token, true, dep.name);
-                        case "OptionalAll":
-                            return this.resolveAll(token, true);
-                    }
-                });
+                return this.resolveArgs(ctorDeps, ctor);
             }
         }
         return [];
     }
-    injectDependencies(registration, instance) {
+    injectMethodDependencies(registration, instance) {
         const dependencies = registration.dependencies;
         if (dependencies) {
             check(isClassProvider(registration.provider), `internal error: not a ClassProvider`);
             const ctor = registration.provider.useClass;
             // Perform method injection
             for (const entry of dependencies.methods){
-                const key = entry[0];
+                const methodKey = 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
-                const method = instance[key];
+                const method = instance[methodKey];
                 check(methodDeps.length === method.length, ()=>{
-                    const msg = `expected ${method.length} decorated method parameters`;
-                    return msg + ` in ${ctor.name}.${String(key)}, but found ${methodDeps.length}`;
-                });
-                const args = methodDeps.sort((a, b)=>a.index - b.index).map((dep)=>{
-                    const token = dep.tokenRef.getRefToken();
-                    switch(dep.appliedBy){
-                        case "Inject":
-                            return injectBy(instance, token, dep.name);
-                        case "InjectAll":
-                            return injectAll(token);
-                        case "Optional":
-                            return optionalBy(instance, token, dep.name);
-                        case "OptionalAll":
-                            return optionalAll(token);
-                    }
+                    const location = getLocation(ctor, methodKey);
+                    const msg = `${location} expected ${method.length} decorated method parameters`;
+                    return msg + `, but found ${methodDeps.length}`;
                 });
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+                const args = this.resolveArgs(methodDeps, ctor, instance, methodKey);
                 method.bind(instance)(...args);
             }
         }
         return instance;
     }
+    resolveArgs(deps, ctor, instance, methodKey) {
+        const sortedDeps = deps.sort((a, b)=>a.index - b.index);
+        const args = [];
+        for (const dep of sortedDeps){
+            try {
+                args.push(this.resolveDependency(dep, instance));
+            } catch (e) {
+                throwParameterResolutionError(ctor, methodKey, dep, e);
+            }
+        }
+        return args;
+    }
+    resolveDependency(dependency, instance) {
+        const token = dependency.tokenRef.getRefToken();
+        const name = dependency.name;
+        switch(dependency.appliedBy){
+            case "Inject":
+                return instance ? injectBy(instance, token, name) : this.resolve(token, name);
+            case "InjectAll":
+                return instance ? injectAll(token) : this.resolveAll(token);
+            case "Optional":
+                return instance ? optionalBy(instance, token, name) : this.resolve(token, true, name);
+            case "OptionalAll":
+                return instance ? optionalAll(token) : this.resolveAll(token, true);
+        }
+    }
     checkDisposed() {
         check(!this.myDisposed, "the container is disposed");
     }
@@ -905,11 +925,13 @@ function isDisposable(value) {
  * @__NO_SIDE_EFFECTS__
  */ function EagerInstantiate() {
     return function(Class) {
-        const metadata = getMetadata(Class);
+        const ctor = Class;
+        const metadata = getMetadata(ctor);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === Scope.Container, ()=>{
             const { value, appliedBy } = currentScope;
-            return `class ${Class.name}: 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.`;
+            const className = getTokenName(ctor);
+            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;
         metadata.scope = {
@@ -939,30 +961,28 @@ function forwardRef(token) {
 }
 // @internal
 function isTokensRef(value) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     return value && typeof value === "object" && typeof value.getRefTokens === "function";
 }
 // @internal
 function isTokenRef(value) {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     return value && typeof value === "object" && typeof value.getRefToken === "function";
 }
 
 // @internal
-function updateParameterMetadata(decorator, target, propertyKey, parameterIndex, updateFn) {
+function updateParameterMetadata(decorator, target, methodKey, parameterIndex, updateFn) {
     // Error out immediately if the decorator has been applied to a static method
-    if (propertyKey !== undefined && typeof target === "function") {
-        check(false, `@${decorator} cannot be used on static method ${target.name}.${String(propertyKey)}`);
+    if (methodKey !== undefined && typeof target === "function") {
+        check(false, `@${decorator} cannot be used on static method ${target.name}.${String(methodKey)}`);
     }
-    if (propertyKey === undefined) {
+    if (methodKey === undefined) {
         // Constructor
         const metadata = getMetadata(target);
-        const dependency = metadata.getConstructorDependency(parameterIndex);
+        const dependency = metadata.getCtorDependency(parameterIndex);
         updateFn(dependency);
     } else {
         // Instance method
         const metadata = getMetadata(target.constructor);
-        const dependency = metadata.getMethodDependency(propertyKey, parameterIndex);
+        const dependency = metadata.getMethodDependency(methodKey, parameterIndex);
         updateFn(dependency);
     }
 }
@@ -971,30 +991,30 @@ function updateParameterMetadata(decorator, target, propertyKey, parameterIndex,
 // understand which one "wins", unless the user is aware of the decorator evaluation order.
 //
 // @internal
-function checkSingleDecorator(dependency, target, propertyKey, parameterIndex) {
+function checkSingleDecorator(dependency, target, methodKey, parameterIndex) {
     check(dependency.appliedBy === undefined, ()=>{
-        const location = getLocation(target, propertyKey, parameterIndex);
-        return `multiple injection decorators on ${location}, but only one is allowed`;
+        const param = describeParam(target, methodKey, parameterIndex);
+        return `multiple injection decorators on ${param}, but only one is allowed`;
     });
 }
 // Checks that the `@Named` decorator is not used in combination with
 // `@InjectAll` or `@OptionalAll`, which ignore the name qualification.
 //
 // @internal
-function checkNamedDecorator(dependency, target, propertyKey, parameterIndex) {
+function checkNamedDecorator(dependency, target, methodKey, parameterIndex) {
     const { appliedBy, name } = dependency;
     check(name === undefined || appliedBy !== "InjectAll" && appliedBy !== "OptionalAll", ()=>{
-        const location = getLocation(target, propertyKey, parameterIndex);
-        return `@Named has no effect on ${location} when used with @${appliedBy}`;
+        const param = describeParam(target, methodKey, parameterIndex);
+        return `@Named has no effect on ${param} when used with @${appliedBy}`;
     });
 }
 // Returns a human-readable description of the parameter location.
 // For example: "Wizard constructor parameter 2" or "Wizard.set parameter 0"
 //
 // @internal
-function getLocation(target, propertyKey, parameterIndex) {
-    const location = propertyKey === undefined ? `${target.name} constructor` : `${target.constructor.name}.${String(propertyKey)}`;
-    return `${location} parameter ${parameterIndex}`;
+function describeParam(target, methodKey, parameterIndex) {
+    const location = methodKey === undefined ? target.name : `${target.constructor.name}.${String(methodKey)}`;
+    return `${location}(parameter #${parameterIndex})`;
 }
 
 function Inject(token) {
@@ -1056,20 +1076,21 @@ function InjectAll(token) {
  *
  * @__NO_SIDE_EFFECTS__
  */ function Named(name) {
-    check(name.trim(), "the @Named qualifier cannot be empty or blank");
+    check(name.trim(), "the @Named qualifier must not be empty");
     return function(target, propertyKey, parameterIndex) {
         if (parameterIndex === undefined) {
             // The decorator has been applied to the class
             const ctor = target;
             const metadata = getMetadata(ctor);
-            check(metadata.name === undefined, `multiple @Named decorators on class ${ctor.name}, but only one is allowed`);
+            const className = getTokenName(ctor);
+            check(metadata.name === undefined, `multiple @Named decorators on class ${className}, but only one is allowed`);
             metadata.name = name;
         } else {
             // The decorator has been applied to a method parameter
             updateParameterMetadata("Named", target, propertyKey, parameterIndex, (dependency)=>{
                 check(dependency.name === undefined, ()=>{
-                    const location = getLocation(target, propertyKey, parameterIndex);
-                    return `multiple @Named decorators on ${location}, but only one is allowed`;
+                    const param = describeParam(target, propertyKey, parameterIndex);
+                    return `multiple @Named decorators on ${param}, but only one is allowed`;
                 });
                 dependency.name = name;
                 checkNamedDecorator(dependency, target, propertyKey, parameterIndex);
@@ -1122,12 +1143,14 @@ function OptionalAll(token) {
  * @__NO_SIDE_EFFECTS__
  */ function Scoped(scope) {
     return function(Class) {
-        const metadata = getMetadata(Class);
+        const ctor = Class;
+        const metadata = getMetadata(ctor);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === scope, ()=>{
             const { value, appliedBy } = currentScope;
             const by = appliedBy === "Scoped" ? `another @${appliedBy} decorator` : `@${appliedBy}`;
-            return `class ${Class.name}: 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.`;
+            const className = getTokenName(ctor);
+            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 = {
             value: scope,
@@ -1209,10 +1232,7 @@ function OptionalAll(token) {
         use (key, wrap) {
             // We need to bind the 'this' context of the function to the container
             // before passing it to the middleware wrapper.
-            //
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access,@typescript-eslint/no-unsafe-call
             const fn = container[key].bind(container);
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
             container[key] = wrap(fn);
             return composer;
         }