@lppedd/di-wise-neo 0.11.2 → 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): Value[];
-    resolveAll<Value>(token: Token<Value>, optional: true): Value[];
-    resolveAll<Value>(token: Token<Value>, optional?: boolean): Value[];
+    tryResolveAll<Value>(token: Token<Value>): Value[];
     /**
      * Disposes this container and all its cached values.
      *
@@ -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.

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,39 +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)?.value;
+        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((result)=>result !== undefined).map((result)=>result.value);
+        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) {
@@ -705,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)){
@@ -916,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() {