@lppedd/di-wise-neo 0.9.4 → 0.11.0

package/README.md

@@ -168,14 +168,9 @@ registrar.registerCommand("my.command", () => { console.log("hey!"); });
 
 ## Container scopes
 
-The [Container][source-container] supports four **scope** types that determine how and when
+The [Container][source-container] supports three **scope** types that determine how and when
 values are cached and reused.
 
-### Inherited
-
-Inherits the scope from the requesting (dependent) token.  
-If there is no dependent (i.e., during top-level resolution), it behaves like **Transient**.
-
 ### Transient
 
 Creates a new value every time the dependency is resolved, which means values are never cached.
@@ -184,6 +179,11 @@ Creates a new value every time the dependency is resolved, which means values ar
 - a factory function registered via `FactoryProvider` is invoked on each resolution
 - a value registered via `ValueProvider` is always returned as-is
 
+> [!NOTE]
+> When a **Transient** or **Resolution**-scoped value is injected into a **Container**-scoped
+> instance, it effectively inherits the lifecycle of that instance. The value will live as long
+> as the containing instance, even though it is not cached by the container itself.
+
 ### Resolution
 
 Creates and caches a single value per resolution graph.  

package/dist/cjs/index.d.ts

@@ -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.
@@ -155,7 +174,6 @@ interface ExistingProvider<Value> {
 type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
 
 declare const Scope: {
-    readonly Inherited: "Inherited";
     readonly Transient: "Transient";
     readonly Resolution: "Resolution";
     readonly Container: "Container";
@@ -203,7 +221,7 @@ interface ContainerOptions {
     /**
      * The default scope for registrations.
      *
-     * @defaultValue Scope.Inherited
+     * @defaultValue Scope.Transient
      */
     readonly defaultScope: Scope;
 }
@@ -325,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}.
      *
@@ -373,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/cjs/index.js

@@ -7,27 +7,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 message = tag(`failed to resolve token ${getTokenName(token)}`);
-    throw isError(cause) ? new Error(`${message}\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(`${message}\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 message = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
-    throw new Error(`${message}\n  [cause] ${untag(cause.message)}`, {
+    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 + getCause(cause), {
         cause
     });
 }
@@ -37,11 +48,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}`;
@@ -298,15 +325,13 @@ function isExistingProvider(provider) {
 }
 
 const Scope = {
-    Inherited: "Inherited",
     Transient: "Transient",
     Resolution: "Resolution",
     Container: "Container"
 };
 
+const typeSymbol = Symbol("di-wise-neo.typeToken");
 /**
- * Type API.
- */ /**
  * Creates a type token.
  *
  * @example
@@ -320,6 +345,7 @@ const Scope = {
         name: `Type<${typeName}>`,
         inter: createType,
         union: createType,
+        __type: typeSymbol,
         toString () {
             return type.name;
         }
@@ -327,6 +353,10 @@ const Scope = {
     return type;
 }
 // @internal
+function isType(token) {
+    return token.__type === typeSymbol;
+}
+// @internal
 function isConstructor(token) {
     return typeof token === "function";
 }
@@ -432,8 +462,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}'`);
@@ -478,7 +507,7 @@ function isDisposable(value) {
         this.myParent = parent;
         this.myOptions = {
             autoRegister: false,
-            defaultScope: Scope.Inherited,
+            defaultScope: Scope.Transient,
             ...options
         };
         this.myTokenRegistry = new TokenRegistry(this.myParent?.myTokenRegistry);
@@ -548,8 +577,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: {
@@ -563,8 +593,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
+                        }
                     }
                 });
             }
@@ -574,9 +608,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 = {
@@ -596,8 +629,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,
@@ -634,10 +668,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();
@@ -650,11 +681,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) {
@@ -681,26 +714,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;
@@ -731,8 +795,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,16 +807,17 @@ function isDisposable(value) {
         }
         const resolution = context.resolution;
         const provider = registration.provider;
-        const options = registration.options;
         if (resolution.stack.has(provider)) {
             const dependentRef = resolution.dependents.get(provider);
             check(dependentRef, ()=>{
-                const path = resolution.tokenStack.map(getTokenName).join(" → ");
-                return `circular dependency detected while resolving ${path} → ${getTokenName(token)}`;
+                const path = getTokenPath(resolution.tokenStack.concat(token).map((t)=>[
+                        t
+                    ]));
+                return `circular dependency detected while resolving ${path}`;
             });
             return dependentRef.current;
         }
-        const scope = this.resolveScope(options?.scope, context);
+        const scope = registration.options?.scope ?? this.myOptions.defaultScope;
         const cleanups = [
             provideInjectionContext(context),
             resolution.tokenStack.push(token) && (()=>resolution.tokenStack.pop()),
@@ -800,13 +864,6 @@ function isDisposable(value) {
             cleanups.forEach((cleanup)=>cleanup && cleanup());
         }
     }
-    resolveScope(scope = this.myOptions.defaultScope, context = useInjectionContext()) {
-        if (scope === Scope.Inherited) {
-            const dependentFrame = context?.resolution.stack.peek();
-            return dependentFrame?.scope || Scope.Transient;
-        }
-        return scope;
-    }
     resolveCtorDependencies(registration) {
         const dependencies = registration.dependencies;
         if (dependencies) {
@@ -819,7 +876,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);
             }
@@ -841,7 +898,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);
@@ -876,7 +933,7 @@ function isDisposable(value) {
         }
     }
     checkDisposed() {
-        check(!this.myDisposed, "the container is disposed");
+        check(!this.myDisposed, "container is disposed");
     }
 }
 
@@ -884,7 +941,7 @@ function isDisposable(value) {
  * Creates a new container.
  */ function createContainer(options = {
     autoRegister: false,
-    defaultScope: Scope.Inherited
+    defaultScope: Scope.Transient
 }) {
     return new ContainerImpl(undefined, options);
 }
@@ -1081,7 +1138,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
@@ -1183,22 +1240,15 @@ function OptionalAll(token) {
  * ```
  */ const Injector = /*@__PURE__*/ build(()=>{
     const context = ensureInjectionContext("Injector factory");
-    const resolution = context.resolution;
-    const dependentFrame = resolution.stack.peek();
-    const dependentRef = dependentFrame && resolution.dependents.get(dependentFrame.provider);
     const runInContext = (fn)=>{
         if (useInjectionContext()) {
             return fn();
         }
-        const cleanups = [
-            provideInjectionContext(context),
-            dependentFrame && resolution.stack.push(dependentFrame.provider, dependentFrame),
-            dependentRef && resolution.dependents.set(dependentFrame.provider, dependentRef)
-        ];
+        const cleanup = provideInjectionContext(context);
         try {
             return fn();
         } finally{
-            cleanups.forEach((cleanup)=>cleanup?.());
+            cleanup();
         }
     };
     return {