@lppedd/di-wise-neo 0.11.1 → 0.12.0

package/dist/es/index.d.mts

@@ -145,7 +145,19 @@ interface ValueProvider<Value> {
  */
 interface ExistingProvider<Value> {
     /**
-     * The existing token to alias.
+     * The existing token to alias, with an optional name qualifier.
+     *
+     * @example
+     * ```ts
+     * container.register(ISecretStorage, {
+     *   useExisting: PersistentSecretStorage,
+     * });
+     *
+     * // Or in case we need to alias a name-qualified token
+     * container.register(ISecretStorage, {
+     *   useExisting: [PersistentSecretStorage, "fileSystem"],
+     * });
+     * ```
      */
     readonly useExisting: Token<Value> | [Token<Value>, string?];
     /**
@@ -171,8 +183,22 @@ interface ExistingProvider<Value> {
 type Provider<Value = any> = ClassProvider<Value & object> | FactoryProvider<Value> | ValueProvider<Value> | ExistingProvider<Value>;
 
 declare const Scope: {
+    /**
+     * Creates a new value every time the token is resolved.
+     */
     readonly Transient: "Transient";
+    /**
+     * Creates and caches a single value per token resolution graph.
+     *
+     * The same value is reused during a single resolution request and is subsequently discarded.
+     */
     readonly Resolution: "Resolution";
+    /**
+     * Creates and caches a single value per container.
+     *
+     * If the value is not found in the current container, it is looked up in the parent container,
+     * and so on. It effectively behaves like a _singleton_ scope but allows container-specific overrides.
+     */
     readonly Container: "Container";
 };
 type Scope = (typeof Scope)[keyof typeof Scope];
@@ -345,9 +371,8 @@ interface Container {
      * The scope for the automatic registration is determined by either
      * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
      *
-     * If `optional` is false or is not passed and the class is not registered in the container
-     * (and could not be auto-registered), an error is thrown.
-     * Otherwise, if `optional` is true, `undefined` is returned.
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided instance is returned.
@@ -359,17 +384,13 @@ interface Container {
      * in the container's internal registry.
      */
     resolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: false, name?: string): Instance;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional: true, name?: string): Instance | undefined;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: boolean, name?: string): Instance | undefined;
     /**
      * Resolves the given token to the value associated with it.
      *
      * If the token is registered in this container or any of its parent containers,
      * its value is resolved using the most recent registration.
      *
-     * If `optional` is false or not passed and the token is not registered in the container,
-     * an error is thrown. Otherwise, if `optional` is true, `undefined` is returned.
+     * If the token is not registered in this container or any of its parent containers, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided value is returned.
@@ -381,9 +402,51 @@ interface Container {
      * in the container's internal registry.
      */
     resolve<Value>(token: Token<Value>, name?: string): Value;
-    resolve<Value>(token: Token<Value>, optional?: false, name?: string): Value;
-    resolve<Value>(token: Token<Value>, optional: true, name?: string): Value | undefined;
-    resolve<Value>(token: Token<Value>, optional?: boolean, name?: string): Value | undefined;
+    /**
+     * Resolves the given class to the instance associated with it.
+     *
+     * If the class is registered in this container or any of its parent containers,
+     * an instance is created using the most recent registration.
+     *
+     * 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, the resolution fails.
+     *
+     * The scope for the automatic registration is determined by either
+     * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
+     *
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, `undefined` is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided instance is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the instance.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
+     *
+     * If the class is registered with _container_ scope, the resolved instance is cached
+     * in the container's internal registry.
+     */
+    tryResolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance | undefined;
+    /**
+     * Tries to resolve the given token to the value associated with it.
+     *
+     * If the token is registered in this container or any of its parent containers,
+     * its value is resolved using the most recent registration.
+     *
+     * If the token is not registered in this container or any of its parent containers,
+     * `undefined` is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided value is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the value.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
+     *
+     * If the token is registered with _container_ scope, the resolved value is cached
+     * in the container's internal registry.
+     */
+    tryResolve<Value>(token: Token<Value>, name?: string): Value | undefined;
     /**
      * Resolves the given class to all instances provided by the registrations associated with it.
      *
@@ -394,9 +457,8 @@ interface Container {
      * The scope for the automatic registration is determined by either
      * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
      *
-     * If `optional` is false or is not passed and the class is not registered in the container
-     * (and could not be auto-registered), an error is thrown.
-     * Otherwise, if `optional` is true, an empty array is returned.
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided instance is returned.
@@ -408,17 +470,12 @@ interface Container {
      * in the container's internal registry.
      *
      * A separate instance of the class is created for each provider.
-     *
-     * @see The documentation for `resolve(Class: Constructor)`
      */
-    resolveAll<Instance extends object>(Class: Constructor<Instance>, optional?: false): Instance[];
-    resolveAll<Instance extends object>(Class: Constructor<Instance>, optional: true): Instance[];
-    resolveAll<Instance extends object>(Class: Constructor<Instance>, optional?: boolean): Instance[];
+    resolveAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
     /**
      * Resolves the given token to all values provided by the registrations associated with it.
      *
-     * If `optional` is false or not passed and the token is not registered in the container,
-     * an error is thrown. Otherwise, if `optional` is true, an empty array is returned.
+     * If the token is not registered in this container or any of its parent containers, an error is thrown.
      *
      * The resolution behavior depends on the {@link Provider} used during registration:
      * - For {@link ValueProvider}, the explicitly provided value is returned.
@@ -428,12 +485,49 @@ interface Container {
      *
      * If the token is registered with _container_ scope, the resolved values are cached
      * in the container's internal registry.
+     */
+    resolveAll<Value>(token: Token<Value>): Value[];
+    /**
+     * Resolves the given class to all instances provided by the registrations associated with it.
+     *
+     * 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, the resolution fails.
      *
-     * @see The documentation for `resolve(token: Token)`
+     * The scope for the automatic registration is determined by either
+     * the {@link Scoped} decorator on the class, or {@link ContainerOptions.defaultScope}.
+     *
+     * If the class is not registered in this container or any of its parent containers
+     * and could not be auto-registered, an empty array is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided instance is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the instance.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the instance is resolved by referring to another registered token.
+     *
+     * If the class is registered with _container_ scope, the resolved instances are cached
+     * in the container's internal registry.
+     *
+     * A separate instance of the class is created for each provider.
+     */
+    tryResolveAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
+    /**
+     * Resolves the given token to all values provided by the registrations associated with it.
+     *
+     * If the token is not registered in this container or any of its parent containers,
+     * an empty array is returned instead.
+     *
+     * The resolution behavior depends on the {@link Provider} used during registration:
+     * - For {@link ValueProvider}, the explicitly provided value is returned.
+     * - For {@link FactoryProvider}, the factory function is invoked to create the value.
+     * - For {@link ClassProvider}, a new instance of the class is created according to its scope.
+     * - For {@link ExistingProvider}, the value is resolved by referring to another registered token.
+     *
+     * If the token is registered with _container_ scope, the resolved values are cached
+     * in the container's internal registry.
      */
-    resolveAll<Value>(token: Token<Value>, optional?: false): NonNullable<Value>[];
-    resolveAll<Value>(token: Token<Value>, optional: true): NonNullable<Value>[];
-    resolveAll<Value>(token: Token<Value>, optional?: boolean): NonNullable<Value>[];
+    tryResolveAll<Value>(token: Token<Value>): Value[];
     /**
      * Disposes this container and all its cached values.
      *
@@ -450,7 +544,7 @@ interface Container {
 declare function createContainer(options?: Partial<ContainerOptions>): Container;
 
 /**
- * Class decorator that enables auto-registration of an unregistered class,
+ * Class decorator that enables auto-registration of an unregistered class
  * when the class is first resolved from the container.
  *
  * @example
@@ -536,7 +630,7 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
- * Class decorator that registers additional aliasing tokens for the decorated type,
+ * Class decorator that registers additional aliasing tokens for the decorated type
  * when the type is first registered in the container.
  *
  * The container uses {@link ExistingProvider} under the hood.
@@ -549,7 +643,7 @@ declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  */
 declare function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
 /**
- * Class decorator that registers additional aliasing tokens for the decorated type,
+ * Class decorator that registers additional aliasing tokens for the decorated type
  * when the type is first registered in the container.
  *
  * The container uses {@link ExistingProvider} under the hood.
@@ -651,19 +745,19 @@ declare function Optional<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
  * Parameter decorator that injects all instances provided by the registrations
- * associated with the given class, or an empty array if the class is not registered
+ * associated with the given class or an empty array if the class is not registered
  * in the container.
  */
 declare function OptionalAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
  * Parameter decorator that injects all values provided by the registrations
- * associated with the given token, or an empty array if the token is not registered
+ * associated with the given token or an empty array if the token is not registered
  * in the container.
  */
 declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
 /**
  * Parameter decorator that injects all values provided by the registrations
- * associated with the given token, or an empty array if the token is not registered
+ * associated with the given token or an empty array if the token is not registered
  * in the container.
  *
  * Allows referencing a token declared later in the file by using the
@@ -776,7 +870,7 @@ declare function injectAll<Instance extends object>(Class: Constructor<Instance>
  *
  * Throws an error if the token is not registered in the container.
  */
-declare function injectAll<Value>(token: Token<Value>): NonNullable<Value>[];
+declare function injectAll<Value>(token: Token<Value>): Value[];
 
 /**
  * Injector API.
@@ -805,7 +899,7 @@ interface Injector {
      *
      * Throws an error if the token is not registered in the container.
      */
-    injectAll<Value>(token: Token<Value>): NonNullable<Value>[];
+    injectAll<Value>(token: Token<Value>): Value[];
     /**
      * Injects the instance associated with the given class,
      * or `undefined` if the class is not registered in the container.
@@ -817,15 +911,15 @@ interface Injector {
      */
     optional<Value>(token: Token<Value>, name?: string): Value | undefined;
     /**
-     * Injects all instances provided by the registrations associated with the given class,
+     * Injects all instances provided by the registrations associated with the given class
      * or an empty array if the class is not registered in the container.
      */
     optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
     /**
-     * Injects all values provided by the registrations associated with the given token,
+     * Injects all values provided by the registrations associated with the given token
      * or an empty array if the token is not registered in the container.
      */
-    optionalAll<Value>(token: Token<Value>): NonNullable<Value>[];
+    optionalAll<Value>(token: Token<Value>): Value[];
     /**
      * Runs a function inside the injection context of this injector.
      *
@@ -833,7 +927,7 @@ interface Injector {
      * are only usable synchronously: they cannot be called from asynchronous callbacks
      * or after any `await` points.
      *
-     * @param fn The function to be run in the context of this injector.
+     * @param fn - The function to be run in the context of this injector.
      * @returns The return value of the function, if any.
      */
     runInContext<ReturnType>(fn: () => ReturnType): ReturnType;
@@ -865,8 +959,8 @@ declare const Injector: Type<Injector>;
  * 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.
+ * @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.
@@ -909,7 +1003,7 @@ interface Middleware {
 /**
  * Applies middleware functions to a container.
  *
- * Middlewares are applied in array order, but execute in reverse order.
+ * Middlewares are applied in array order but execute in reverse order.
  *
  * @example
  * ```ts
@@ -967,15 +1061,15 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
 declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
 
 /**
- * Injects all instances provided by the registrations associated with the given class,
+ * Injects all instances provided by the registrations associated with the given class
  * or an empty array if the class is not registered in the container.
  */
 declare function optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
 /**
- * Injects all values provided by the registrations associated with the given token,
+ * Injects all values provided by the registrations associated with the given token
  * or an empty array if the token is not registered in the container.
  */
-declare function optionalAll<Value>(token: Token<Value>): NonNullable<Value>[];
+declare function optionalAll<Value>(token: Token<Value>): Value[];
 
 export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping };
 export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };

package/dist/es/index.mjs

@@ -169,10 +169,9 @@ function injectBy(thisArg, token, name) {
     if (!currentFrame) {
         return inject(token, name);
     }
-    const currentRef = {
+    const cleanup = resolution.dependents.set(currentFrame.provider, {
         current: thisArg
-    };
-    const cleanup = resolution.dependents.set(currentFrame.provider, currentRef);
+    });
     try {
         return inject(token, name);
     } finally{
@@ -262,8 +261,8 @@ function getMetadata(Class) {
  * 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.
+ * @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.
@@ -278,7 +277,7 @@ const metadataMap = new WeakMap();
 
 function optional(token, name) {
     const context = ensureInjectionContext("optional()");
-    return context.container.resolve(token, true, name);
+    return context.container.tryResolve(token, name);
 }
 function optionalBy(thisArg, token, name) {
     const context = ensureInjectionContext("optionalBy()");
@@ -287,10 +286,9 @@ function optionalBy(thisArg, token, name) {
     if (!currentFrame) {
         return optional(token, name);
     }
-    const currentRef = {
+    const cleanup = resolution.dependents.set(currentFrame.provider, {
         current: thisArg
-    };
-    const cleanup = resolution.dependents.set(currentFrame.provider, currentRef);
+    });
     try {
         return optional(token, name);
     } finally{
@@ -300,7 +298,7 @@ function optionalBy(thisArg, token, name) {
 
 function optionalAll(token) {
     const context = ensureInjectionContext("optionalAll()");
-    return context.container.resolveAll(token, true);
+    return context.container.tryResolveAll(token);
 }
 
 // @internal
@@ -321,9 +319,20 @@ function isExistingProvider(provider) {
 }
 
 const Scope = {
-    Transient: "Transient",
-    Resolution: "Resolution",
-    Container: "Container"
+    /**
+   * Creates a new value every time the token is resolved.
+   */ Transient: "Transient",
+    /**
+   * Creates and caches a single value per token resolution graph.
+   *
+   * The same value is reused during a single resolution request and is subsequently discarded.
+   */ Resolution: "Resolution",
+    /**
+   * Creates and caches a single value per container.
+   *
+   * If the value is not found in the current container, it is looked up in the parent container,
+   * and so on. It effectively behaves like a _singleton_ scope but allows container-specific overrides.
+   */ Container: "Container"
 };
 
 /**
@@ -646,40 +655,21 @@ function isDisposable(value) {
         }
         return Array.from(values);
     }
-    resolve(token, optionalOrName, name) {
+    resolve(token, name) {
         this.checkDisposed();
-        let localOptional;
-        let localName;
-        if (typeof optionalOrName === "string") {
-            localName = optionalOrName;
-        } else {
-            localOptional = optionalOrName;
-            localName = name;
-        }
-        let registration = this.myTokenRegistry.get(token, localName);
-        if (!registration && isConstructor(token)) {
-            registration = this.autoRegisterClass(token, localName);
-        }
-        return this.resolveRegistration(token, registration, localOptional, localName);
+        return this.resolveToken(token, name, false);
     }
-    resolveAll(token, optional) {
+    tryResolve(token, name) {
         this.checkDisposed();
-        let registrations = this.myTokenRegistry.getAll(token);
-        if (registrations.length === 0 && isConstructor(token)) {
-            const registration = this.autoRegisterClass(token);
-            if (registration) {
-                registrations = [
-                    registration
-                ];
-            }
-        }
-        if (registrations.length === 0 && !optional) {
-            throwUnregisteredError([
-                token
-            ]);
-        }
-        return registrations //
-        .map((registration)=>this.resolveRegistration(token, registration, optional)).filter((value)=>value != null);
+        return this.resolveToken(token, name, true);
+    }
+    resolveAll(token) {
+        this.checkDisposed();
+        return this.resolveAllToken(token, false);
+    }
+    tryResolveAll(token) {
+        this.checkDisposed();
+        return this.resolveAllToken(token, true);
     }
     dispose() {
         if (this.myDisposed) {
@@ -706,6 +696,30 @@ function isDisposable(value) {
         // Allow values to be GCed
         disposedRefs.clear();
     }
+    resolveToken(token, name, optional) {
+        let registration = this.myTokenRegistry.get(token, name);
+        if (!registration && isConstructor(token)) {
+            registration = this.autoRegisterClass(token, name);
+        }
+        return this.resolveRegistration(token, registration, optional, name)?.value;
+    }
+    resolveAllToken(token, optional) {
+        let registrations = this.myTokenRegistry.getAll(token);
+        if (registrations.length === 0 && isConstructor(token)) {
+            const registration = this.autoRegisterClass(token);
+            if (registration) {
+                registrations = [
+                    registration
+                ];
+            }
+        }
+        if (registrations.length === 0 && !optional) {
+            throwUnregisteredError([
+                token
+            ]);
+        }
+        return registrations.map((registration)=>this.resolveRegistration(token, registration, optional)).filter((result)=>result !== undefined).map((result)=>result.value);
+    }
     resolveRegistration(token, registration, optional, name) {
         const aliases = [];
         while(registration && isExistingProvider(registration.provider)){
@@ -739,7 +753,9 @@ function isDisposable(value) {
             ]);
         }
         try {
-            return this.resolveProviderValue(token, registration);
+            return {
+                value: this.resolveProviderValue(token, registration)
+            };
         } catch (e) {
             throwResolutionError([
                 token,
@@ -915,9 +931,9 @@ function isDisposable(value) {
             case "InjectAll":
                 return instance ? injectAll(token) : this.resolveAll(token);
             case "Optional":
-                return instance ? optionalBy(instance, token, name) : this.resolve(token, true, name);
+                return instance ? optionalBy(instance, token, name) : this.tryResolve(token, name);
             case "OptionalAll":
-                return instance ? optionalAll(token) : this.resolveAll(token, true);
+                return instance ? optionalAll(token) : this.tryResolveAll(token);
         }
     }
     checkDisposed() {
@@ -935,7 +951,7 @@ function isDisposable(value) {
 }
 
 /**
- * Class decorator that enables auto-registration of an unregistered class,
+ * Class decorator that enables auto-registration of an unregistered class
  * when the class is first resolved from the container.
  *
  * @example
@@ -1243,14 +1259,14 @@ function OptionalAll(token) {
         injectAll: (token)=>runInContext(()=>injectAll(token)),
         optional: (token, name)=>runInContext(()=>optional(token, name)),
         optionalAll: (token)=>runInContext(()=>optionalAll(token)),
-        runInContext
+        runInContext: runInContext
     };
 }, "Injector");
 
 /**
  * Applies middleware functions to a container.
  *
- * Middlewares are applied in array order, but execute in reverse order.
+ * Middlewares are applied in array order but execute in reverse order.
  *
  * @example
  * ```ts