@lppedd/di-wise-neo 0.10.0 → 0.11.0

package/dist/es/index.d.mts

@@ -147,7 +147,26 @@ interface ExistingProvider<Value> {
     /**
      * The existing token to alias.
      */
-    readonly useExisting: Token<Value>;
+    readonly useExisting: Token<Value> | {
+        readonly token: Token<Value>;
+        readonly name?: string;
+    };
+    /**
+     * An optional name to qualify this provider.
+     * If specified, the token must be resolved using the same name.
+     *
+     * @example
+     * ```ts
+     * export class ExtensionContext {
+     *   // Decorator-based injection
+     *   constructor(@Inject(ISecretStorage) @Named("persistent") secretStorage: SecretStorage) {}
+     *
+     *   // Function-based injection
+     *   constructor(secretStorage = inject(ISecretStorage, "persistent")) {}
+     * }
+     * ```
+     */
+    readonly name?: string;
 }
 /**
  * A token provider.
@@ -324,7 +343,8 @@ interface Container {
      *
      * If the class is not registered, but it is decorated with {@link AutoRegister},
      * or {@link ContainerOptions.autoRegister} is true, the class is registered automatically.
-     * Otherwise, resolution fails.
+     * Otherwise, the resolution fails.
+     *
      * The scope for the automatic registration is determined by either
      * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
      *
@@ -372,7 +392,8 @@ interface Container {
      *
      * If the class is not registered, but it is decorated with {@link AutoRegister},
      * or {@link ContainerOptions.autoRegister} is true, the class is registered automatically.
-     * Otherwise, resolution fails.
+     * Otherwise, the resolution fails.
+     *
      * The scope for the automatic registration is determined by either
      * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
      *

package/dist/es/index.mjs

@@ -5,27 +5,38 @@ function check(condition, message) {
     }
 }
 // @internal
-function expectNever(value) {
-    throw new TypeError(tag(`unexpected value ${String(value)}`));
+function throwUnregisteredError(tokenInfo) {
+    throw new Error(tag(`unregistered token ${getFullTokenName(tokenInfo)}`));
 }
 // @internal
-function throwUnregisteredError(token, name) {
-    const spec = name !== undefined ? `[name=${name}]` : "";
-    throw new Error(tag(`unregistered token ${getTokenName(token)}${spec}`));
+function throwTargetUnregisteredError(tokenInfo, aliases) {
+    const path = aliases.length > 0 ? ` (alias for ${getTokenPath(aliases)})` : "";
+    const desc = getFullTokenName(tokenInfo) + path;
+    const cause = `\n  [cause] useExisting points to unregistered token ${getFullTokenName(aliases.at(-1))}`;
+    throw new Error(tag(`failed to resolve token ${desc}`) + cause);
 }
 // @internal
-function throwExistingUnregisteredError(token, cause) {
-    const msg = tag(`failed to resolve token ${getTokenName(token)}`);
-    throw isError(cause) ? new Error(`${msg}\n  [cause] ${untag(cause.message)}`, {
+function throwCircularAliasError(aliases) {
+    const path = getTokenPath(aliases);
+    throw new Error(tag(`circular alias detected while resolving ${path}`));
+}
+// @internal
+function throwResolutionError(tokenInfo, aliases, cause) {
+    const path = aliases.length > 0 ? ` (alias for ${getTokenPath(aliases)})` : "";
+    const desc = getFullTokenName(tokenInfo) + path;
+    throw new Error(tag(`failed to resolve token ${desc}`) + getCause(cause), {
         cause
-    }) : new Error(`${msg}\n  [cause] the aliased token ${getTokenName(cause)} is not registered`);
+    });
 }
 // @internal
 function throwParameterResolutionError(ctor, methodKey, dependency, cause) {
     const location = getLocation(ctor, methodKey);
-    const tokenName = getTokenName(dependency.tokenRef.getRefToken());
+    const tokenName = getFullTokenName([
+        dependency.tokenRef.getRefToken(),
+        dependency.name
+    ]);
     const msg = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
-    throw new Error(`${msg}\n  [cause] ${untag(cause.message)}`, {
+    throw new Error(msg + getCause(cause), {
         cause
     });
 }
@@ -35,11 +46,27 @@ function getLocation(ctor, methodKey) {
     return methodKey ? `${ctorName}.${String(methodKey)}` : ctorName;
 }
 // @internal
+function getTokenPath(tokens) {
+    return tokens.map(getFullTokenName).join(" \u2192 ");
+}
+// @internal
 function getTokenName(token) {
     return token.name || "<unnamed>";
 }
+function getFullTokenName(tokenInfo) {
+    const [token, name] = tokenInfo;
+    const tokenName = token.name || "<unnamed>";
+    return name ? `${tokenName}["${name}"]` : tokenName;
+}
+function getCause(error) {
+    if (!error) {
+        return "";
+    }
+    const msg = isError(error) ? error.message : String(error);
+    return `\n  [cause] ${untag(msg)}`;
+}
 function isError(value) {
-    return value && value.stack && value.message && typeof value.message === "string";
+    return value?.stack && typeof value?.message === "string";
 }
 function tag(message) {
     return `[di-wise-neo] ${message}`;
@@ -301,9 +328,8 @@ const Scope = {
     Container: "Container"
 };
 
+const typeSymbol = Symbol("di-wise-neo.typeToken");
 /**
- * Type API.
- */ /**
  * Creates a type token.
  *
  * @example
@@ -317,6 +343,7 @@ const Scope = {
         name: `Type<${typeName}>`,
         inter: createType,
         union: createType,
+        __type: typeSymbol,
         toString () {
             return type.name;
         }
@@ -324,6 +351,10 @@ const Scope = {
     return type;
 }
 // @internal
+function isType(token) {
+    return token.__type === typeSymbol;
+}
+// @internal
 function isConstructor(token) {
     return typeof token === "function";
 }
@@ -429,8 +460,7 @@ class TokenRegistry {
         return Array.from(values);
     }
     getAllFromParent(token, name) {
-        const thisRegistrations = this.myMap.get(token);
-        let registrations = thisRegistrations || this.myParent?.getAllFromParent(token, name);
+        let registrations = this.myMap.get(token) || this.myParent?.getAllFromParent(token, name);
         if (registrations && name !== undefined) {
             registrations = registrations.filter((r)=>r.name === name);
             check(registrations.length < 2, `internal error: more than one registration named '${name}'`);
@@ -545,8 +575,9 @@ function isDisposable(value) {
         if (args.length === 1) {
             const Class = args[0];
             const metadata = getMetadata(Class);
+            const name = metadata.name;
             const registration = {
-                name: metadata.name,
+                name: name,
                 // The provider is of type ClassProvider, initialized by getMetadata
                 provider: metadata.provider,
                 options: {
@@ -560,8 +591,12 @@ function isDisposable(value) {
             // These tokens will point to the original Class token and will have the same scope.
             for (const token of metadata.tokensRef.getRefTokens()){
                 this.myTokenRegistry.set(token, {
+                    name: name,
                     provider: {
-                        useExisting: Class
+                        useExisting: {
+                            token: Class,
+                            name: name
+                        }
                     }
                 });
             }
@@ -571,9 +606,8 @@ function isDisposable(value) {
             }
         } else {
             const [token, provider, options] = args;
-            const existingProvider = isExistingProvider(provider);
-            const name = existingProvider ? undefined : provider.name;
-            check(name === undefined || name.trim(), `the name qualifier for token ${getTokenName(token)} must not be empty`);
+            const name = provider.name;
+            check(name === undefined || name.trim(), `name qualifier for token ${getTokenName(token)} must not be empty`);
             if (isClassProvider(provider)) {
                 const metadata = getMetadata(provider.useClass);
                 const registration = {
@@ -593,8 +627,9 @@ function isDisposable(value) {
                     this.resolveProviderValue(token, registration);
                 }
             } else {
-                if (existingProvider) {
-                    check(token !== provider.useExisting, `token ${getTokenName(token)} cannot alias itself via useExisting`);
+                if (isExistingProvider(provider)) {
+                    const [targetToken] = this.getTargetToken(provider);
+                    check(token !== targetToken, `token ${getTokenName(token)} cannot alias itself via useExisting`);
                 }
                 this.myTokenRegistry.set(token, {
                     name: name,
@@ -631,10 +666,7 @@ function isDisposable(value) {
         if (!registration && isConstructor(token)) {
             registration = this.autoRegisterClass(token, localName);
         }
-        if (registration) {
-            return this.resolveRegistration(token, registration, localName);
-        }
-        return localOptional ? undefined : throwUnregisteredError(token, localName);
+        return this.resolveRegistration(token, registration, localOptional, localName);
     }
     resolveAll(token, optional) {
         this.checkDisposed();
@@ -647,11 +679,13 @@ function isDisposable(value) {
                 ];
             }
         }
-        if (registrations.length > 0) {
-            return registrations //
-            .map((registration)=>this.resolveRegistration(token, registration)).filter((value)=>value != null);
+        if (registrations.length === 0 && !optional) {
+            throwUnregisteredError([
+                token
+            ]);
         }
-        return optional ? [] : throwUnregisteredError(token);
+        return registrations //
+        .map((registration)=>this.resolveRegistration(token, registration, optional)).filter((value)=>value != null);
     }
     dispose() {
         if (this.myDisposed) {
@@ -678,26 +712,57 @@ function isDisposable(value) {
         // Allow values to be GCed
         disposedRefs.clear();
     }
-    resolveRegistration(token, registration, name) {
-        let currRegistration = registration;
-        while(isExistingProvider(currRegistration.provider)){
-            const targetToken = currRegistration.provider.useExisting;
-            currRegistration = this.myTokenRegistry.get(targetToken, name);
-            if (!currRegistration) {
-                throwExistingUnregisteredError(token, targetToken);
+    resolveRegistration(token, registration, optional, name) {
+        const aliases = [];
+        while(registration && isExistingProvider(registration.provider)){
+            const [targetToken, targetName] = this.getTargetToken(registration.provider);
+            if (aliases.some(([t])=>t === targetToken)) {
+                throwCircularAliasError([
+                    [
+                        token,
+                        name
+                    ],
+                    ...aliases
+                ]);
+            }
+            // eslint-disable-next-line no-param-reassign
+            registration = this.myTokenRegistry.get(targetToken, targetName);
+            aliases.push([
+                targetToken,
+                targetName
+            ]);
+            if (!registration && !optional) {
+                throwTargetUnregisteredError([
+                    token,
+                    name
+                ], aliases);
             }
         }
+        if (!registration) {
+            return optional ? undefined : throwUnregisteredError([
+                token,
+                name
+            ]);
+        }
         try {
-            return this.resolveProviderValue(token, currRegistration);
+            return this.resolveProviderValue(token, registration);
         } catch (e) {
-            // If we were trying to resolve a token registered via ExistingProvider,
-            // we must add the cause of the error to the message
-            if (isExistingProvider(registration.provider)) {
-                throwExistingUnregisteredError(token, e);
-            }
-            throw e;
+            throwResolutionError([
+                token,
+                name
+            ], aliases, e);
         }
     }
+    getTargetToken(provider) {
+        const token = provider.useExisting;
+        return isType(token) || isConstructor(token) //
+         ? [
+            token
+        ] : [
+            token.token,
+            token.name
+        ];
+    }
     autoRegisterClass(Class, name) {
         const metadata = getMetadata(Class);
         const autoRegister = metadata.autoRegister ?? this.myOptions.autoRegister;
@@ -728,8 +793,7 @@ function isDisposable(value) {
         if (isValueProvider(provider)) {
             return provider.useValue;
         }
-        check(!isExistingProvider(provider), "internal error: unexpected ExistingProvider");
-        expectNever(provider);
+        check(false, "internal error: unexpected ExistingProvider");
     }
     resolveScopedValue(token, registration, factory) {
         let context = useInjectionContext();
@@ -744,7 +808,9 @@ function isDisposable(value) {
         if (resolution.stack.has(provider)) {
             const dependentRef = resolution.dependents.get(provider);
             check(dependentRef, ()=>{
-                const path = resolution.tokenStack.map(getTokenName).concat(getTokenName(token)).join(" → ");
+                const path = getTokenPath(resolution.tokenStack.concat(token).map((t)=>[
+                        t
+                    ]));
                 return `circular dependency detected while resolving ${path}`;
             });
             return dependentRef.current;
@@ -808,7 +874,7 @@ function isDisposable(value) {
                 check(ctor.length === ctorDeps.length, ()=>{
                     const location = getLocation(ctor);
                     const msg = `${location} expected ${ctor.length} decorated constructor parameters`;
-                    return msg + `, but found ${ctorDeps.length}`;
+                    return `${msg}, but found ${ctorDeps.length}`;
                 });
                 return this.resolveArgs(ctorDeps, ctor);
             }
@@ -830,7 +896,7 @@ function isDisposable(value) {
                 check(methodDeps.length === method.length, ()=>{
                     const location = getLocation(ctor, methodKey);
                     const msg = `${location} expected ${method.length} decorated method parameters`;
-                    return msg + `, but found ${methodDeps.length}`;
+                    return `${msg}, but found ${methodDeps.length}`;
                 });
                 const args = this.resolveArgs(methodDeps, ctor, instance, methodKey);
                 method.bind(instance)(...args);
@@ -865,7 +931,7 @@ function isDisposable(value) {
         }
     }
     checkDisposed() {
-        check(!this.myDisposed, "the container is disposed");
+        check(!this.myDisposed, "container is disposed");
     }
 }
 
@@ -1070,7 +1136,7 @@ function InjectAll(token) {
  *
  * @__NO_SIDE_EFFECTS__
  */ function Named(name) {
-    check(name.trim(), "the @Named qualifier must not be empty");
+    check(name.trim(), "@Named qualifier must not be empty");
     return function(target, propertyKey, parameterIndex) {
         if (parameterIndex === undefined) {
             // The decorator has been applied to the class