@lppedd/di-wise-neo 0.10.0 → 0.11.1

package/dist/es/index.d.mts

@@ -116,11 +116,11 @@ interface FactoryProvider<Value> {
 /**
  * Provides a static - already constructed - value for a token.
  */
-interface ValueProvider<T> {
+interface ValueProvider<Value> {
     /**
      * The static value to associate with the token.
      */
-    readonly useValue: T;
+    readonly useValue: Value;
     /**
      * An optional name to qualify this provider.
      * If specified, the token must be resolved using the same name.
@@ -147,7 +147,23 @@ interface ExistingProvider<Value> {
     /**
      * The existing token to alias.
      */
-    readonly useExisting: Token<Value>;
+    readonly useExisting: Token<Value> | [Token<Value>, 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 +340,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 +389,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}.
      *
@@ -476,12 +494,12 @@ interface TokenRef<Value = any> {
     readonly getRefToken: () => Token<Value>;
 }
 /**
- * Allows referencing tokens that are declared later in the file by wrapping them
+ * Allows referencing tokens declared later in the file by wrapping them
  * in a lazily evaluated function.
  */
 declare function forwardRef<Value>(token: () => Tokens<Value>): TokensRef<Value>;
 /**
- * Allows referencing a token that is declared later in the file by wrapping it
+ * Allows referencing a token declared later in the file by wrapping it
  * in a lazily evaluated function.
  */
 declare function forwardRef<Value>(token: () => Token<Value>): TokenRef<Value>;
@@ -501,8 +519,8 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 /**
  * Parameter decorator that injects the value associated with the given token.
  *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
+ * Allows referencing a token declared later in the file by using the
+ * {@link forwardRef} helper function.
  *
  * Throws an error if the token is not registered in the container.
  *
@@ -567,8 +585,8 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
  * Parameter decorator that injects all values provided by the registrations
  * associated with the given token.
  *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
+ * Allows referencing a token declared later in the file by using the
+ * {@link forwardRef} helper function.
  *
  * Throws an error if the token is not registered in the container.
  *
@@ -617,8 +635,8 @@ declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
  * Parameter decorator that injects the value associated with the given token,
  * or `undefined` if the token is not registered in the container.
  *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
+ * Allows referencing a token declared later in the file by using the
+ * {@link forwardRef} helper function.
  *
  * @example
  * ```ts
@@ -648,8 +666,8 @@ declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
  * associated with the given token, or an empty array if the token is not registered
  * in the container.
  *
- * Allows referencing a token that is declared later in the file by using
- * the {@link forwardRef} helper function.
+ * Allows referencing a token declared later in the file by using the
+ * {@link forwardRef} helper function.
  *
  * @example
  * ```ts

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,26 @@ 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([token, name]) {
+    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}`;
@@ -54,8 +80,7 @@ class KeyedStack {
         return this.myKeys.has(key);
     }
     peek() {
-        const entry = this.myEntries.at(-1);
-        return entry?.value;
+        return this.myEntries.at(-1)?.value;
     }
     push(key, value) {
         check(!this.has(key), "invariant violation");
@@ -103,7 +128,7 @@ class WeakRefMap {
 // @internal
 function createResolution() {
     return {
-        tokenStack: [],
+        tokens: [],
         stack: new KeyedStack(),
         values: new WeakRefMap(),
         dependents: new WeakRefMap()
@@ -385,22 +410,22 @@ class TokenRegistry {
     }
     delete(token, name) {
         const registrations = this.myMap.get(token);
-        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;
-                }
+        if (!registrations) {
+            return [];
+        }
+        if (name !== undefined) {
+            const removed = [];
+            const updated = [];
+            for (const registration of registrations){
+                (registration.name === name ? removed : updated).push(registration);
+            }
+            if (removed.length > 0) {
+                this.myMap.set(token, updated);
+                return removed;
             }
-            this.myMap.delete(token);
         }
-        return registrations ?? [];
+        this.myMap.delete(token);
+        return registrations;
     }
     deleteAll() {
         const tokens = Array.from(this.myMap.keys());
@@ -429,8 +454,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 +569,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 +585,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: [
+                            Class,
+                            name
+                        ]
                     }
                 });
             }
@@ -571,14 +600,13 @@ 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 = {
                     // An explicit provider name overrides what is specified via @Named
-                    name: metadata.name ?? provider.name,
+                    name: metadata.name ?? name,
                     provider: metadata.provider,
                     options: {
                         // Explicit registration options override what is specified via class decorators (e.g., @Scoped)
@@ -593,8 +621,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 +660,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 +673,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 +706,53 @@ 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 Array.isArray(token) ? token : [
+            token
+        ];
+    }
     autoRegisterClass(Class, name) {
         const metadata = getMetadata(Class);
         const autoRegister = metadata.autoRegister ?? this.myOptions.autoRegister;
@@ -728,8 +783,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 +798,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.tokens.concat(token).map((t)=>[
+                        t
+                    ]));
                 return `circular dependency detected while resolving ${path}`;
             });
             return dependentRef.current;
@@ -752,7 +808,7 @@ function isDisposable(value) {
         const scope = registration.options?.scope ?? this.myOptions.defaultScope;
         const cleanups = [
             provideInjectionContext(context),
-            resolution.tokenStack.push(token) && (()=>resolution.tokenStack.pop()),
+            resolution.tokens.push(token) && (()=>resolution.tokens.pop()),
             !isBuilder(provider) && resolution.stack.push(provider, {
                 provider,
                 scope
@@ -808,7 +864,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 +886,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 +921,7 @@ function isDisposable(value) {
         }
     }
     checkDisposed() {
-        check(!this.myDisposed, "the container is disposed");
+        check(!this.myDisposed, "container is disposed");
     }
 }
 
@@ -938,8 +994,7 @@ function isDisposable(value) {
 function forwardRef(token) {
     return {
         getRefTokens: ()=>{
-            // Normalize the single token here, so that we don't have
-            // to do it at every getRefTokens call site
+            // Normalize the single token here so that we don't have to do it at every getRefTokens call site
             const tokenOrTokens = token();
             const tokensArray = Array.isArray(tokenOrTokens) ? tokenOrTokens : [
                 tokenOrTokens
@@ -1070,7 +1125,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