@lppedd/di-wise-neo 0.18.0 → 0.18.1

package/dist/cjs/index.d.ts

@@ -1,3 +1,6 @@
+type ClassDecorator<Class extends object> = (target: Constructor<Class>) => Constructor<Class> | void;
+type ParameterDecorator = (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
+
 declare const Scope: {
     /**
      * Creates a new value every time the token is resolved.
@@ -126,11 +129,8 @@ declare function createType<T>(typeName: string, provider: Provider<T>, options?
 interface ClassRef<Instance extends object> {
     readonly getRefClass: () => Constructor<Instance>;
 }
-interface TokensRef<Value> {
-    readonly getRefTokens: () => Set<Token<Value>>;
-}
 interface TokenRef<Value> {
-    readonly getRefToken: () => Token<Value>;
+    readonly getRefTokens: () => Set<Token<Value>>;
 }
 /**
  * Allows referencing a class declared later in the file by wrapping it
@@ -140,15 +140,12 @@ interface TokenRef<Value> {
  */
 declare function classRef<Instance extends object>(Class: () => Constructor<Instance>): ClassRef<Instance>;
 /**
- * Allows referencing tokens declared later in the file by wrapping them
- * in a lazily evaluated function.
- */
-declare function tokenRef<Value>(token: () => Tokens<Value>): TokensRef<Value>;
-/**
- * Allows referencing a token declared later in the file by wrapping it
- * in a lazily evaluated function.
+ * Allows referencing one or multiple tokens declared later in the file by wrapping them
+ * into a lazily evaluated function.
+ *
+ * @__NO_SIDE_EFFECTS__
  */
-declare function tokenRef<Value>(token: () => Token<Value>): TokenRef<Value>;
+declare function tokenRef<Value>(token: () => Token<Value> | Tokens<Value>): TokenRef<Value>;
 
 /**
  * Provides a class instance for a token via a class constructor.
@@ -320,14 +317,14 @@ interface ContainerHook {
      * - For **Transient**-scoped tokens, it is called each time the token is resolved,
      *   which might mean multiple times per resolution graph.
      *
-     * @param value The provided value.
-     * @param scope The {@link Scope} of the provided value.
+     * @param value - The provided value.
+     * @param scope - The {@link Scope} of the provided value.
      */
     readonly onProvide?: (value: unknown, scope: Scope) => void;
     /**
      * Called after the container has been disposed.
      *
-     * @param values All values that were cached by the container.
+     * @param values - All distinct values that were cached by the disposed container.
      *   Currently, only **Container**-scoped token values are cached.
      */
     readonly onDispose?: (values: unknown[]) => void;
@@ -355,10 +352,10 @@ interface Container {
      */
     createChild(options?: Partial<ChildContainerOptions>): Container;
     /**
-     * Clears and returns all distinct cached values from this container's internal registry.
+     * Clears and returns all distinct values that were cached by this container.
      * Values from {@link ValueProvider} registrations are not included, as they are never cached.
      *
-     * Note that only this container is affected. Parent containers, if any, remain unchanged.
+     * Note that only this container is affected. Parent or child containers, if any, remain unchanged.
      */
     clearCache(): unknown[];
     /**
@@ -388,10 +385,11 @@ interface Container {
     /**
      * Removes all registrations from this container's internal registry.
      *
-     * Returns an array of distinct cached values that were stored within the removed registrations.
-     * Values from {@link ValueProvider} registrations are not included, as they are not cached.
+     * Returns an array of the distinct values that were cached by this container for the
+     * removed registrations. Values from {@link ValueProvider} registrations are not included,
+     * as they are not cached.
      *
-     * Note that only this container is affected. Parent containers, if any, remain unchanged.
+     * Note that only this container is affected. Parent or child containers, if any, remain unchanged.
      */
     resetRegistry(): unknown[];
     /**
@@ -440,10 +438,11 @@ interface Container {
     /**
      * Removes all registrations for the given token from the container's internal registry.
      *
-     * Returns an array of distinct cached values that were stored within the removed registrations.
-     * Values from {@link ValueProvider} registrations are not included, as they are not cached.
+     * Returns an array of the distinct values that were cached by this container for the
+     * removed registrations. Values from {@link ValueProvider} registrations are not included,
+     * as they are not cached.
      *
-     * Note that only this container is affected. Parent containers, if any, remain unchanged.
+     * Note that only this container is affected. Parent or child containers, if any, remain unchanged.
      */
     unregister<Value>(token: Token<Value>, name?: string): Value[];
     /**
@@ -658,7 +657,7 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function AutoRegister(): ClassDecorator;
+declare function AutoRegister<This extends object>(): ClassDecorator<This>;
 
 /**
  * Class decorator that sets the class scope to **Container** and enables
@@ -679,7 +678,7 @@ declare function AutoRegister(): ClassDecorator;
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function EagerInstantiate(): ClassDecorator;
+declare function EagerInstantiate<This extends object>(): ClassDecorator<This>;
 
 /**
  * Parameter decorator that injects the instance associated with the given class.
@@ -733,7 +732,14 @@ declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  * class Wand {}
  * ```
  */
-declare function Injectable<This extends object, Value extends This>(...tokens: Tokens<Value>): ClassDecorator;
+declare function Injectable<Value, This extends Value & object>(token: Token<Value>): ClassDecorator<This>;
+declare function Injectable<VA, VB, This extends VA & VB & object>(tokenA: Token<VA>, //
+tokenB: Token<VB>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, This extends VA & VB & VC & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, VD, This extends VA & VB & VC & VD & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>, tokenD: Token<VD>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, VD, VE, This extends VA & VB & VC & VD & VE & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>, tokenD: Token<VD>, tokenE: Token<VE>): ClassDecorator<This>;
+declare function Injectable<VA, VB, VC, VD, VE, VF, This extends VA & VB & VC & VD & VE & VF & object>(tokenA: Token<VA>, tokenB: Token<VB>, tokenC: Token<VC>, tokenD: Token<VD>, tokenE: Token<VE>, tokenF: Token<VF>): ClassDecorator<This>;
+declare function Injectable<This extends object>(...tokens: Tokens<unknown>): ClassDecorator<This>;
 /**
  * Class decorator that registers additional aliasing tokens for the decorated type
  * when the type is first registered in the container.
@@ -751,7 +757,7 @@ declare function Injectable<This extends object, Value extends This>(...tokens:
  * class Weapon {}
  * ```
  */
-declare function Injectable<This extends object, Value extends This>(tokens: TokenRef<Value> | TokensRef<Value>): ClassDecorator;
+declare function Injectable<Value, This extends Value & object>(tokens: TokenRef<Value>): ClassDecorator<This>;
 
 /**
  * Parameter decorator that injects all instances provided by the registrations
@@ -811,7 +817,7 @@ declare function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Named(name: string): ClassDecorator & ParameterDecorator;
+declare function Named<This extends object>(name: string): ClassDecorator<This> & ParameterDecorator;
 
 /**
  * Parameter decorator that injects the instance associated with the given class,
@@ -909,7 +915,7 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function Scoped(scope: Scope): ClassDecorator;
+declare function Scoped<This extends object>(scope: Scope): ClassDecorator<This>;
 
 /**
  * Injects the instance associated with the given class.
@@ -1000,7 +1006,7 @@ declare function injectBy<Value>(thisArg: any, token: Token<Value>, name?: strin
  * Asserts that the current stack frame is within an injection context,
  * meaning it has access to injection functions (`inject`, `optional`, etc.).
  *
- * @param fn The function performing the assertion, or a string name used in the error message.
+ * @param fn - The function performing the assertion, or a string name used in the error message.
  * @throws {Error} If the current stack frame is not within an injection context.
  */
 declare function assertInjectionContext(fn: Function | string): void;
@@ -1111,14 +1117,14 @@ 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.
- *
- * @remarks
- * This API affects the core class identity resolution mechanism of the DI system.
+ * **IMPORTANT**:
+ * this API affects the core class identity resolution mechanism of the DI system.
  * Incorrect usage may cause metadata to be misassociated, leading to subtle errors.
  * Use only when manipulating constructors (e.g., via decorators or proxies),
  * and ensure the mapping is correct.
+ *
+ * @param transformedClass - The constructor function returned by a class decorator or factory.
+ * @param originalClass - The original constructor function.
  */
 declare function setClassIdentityMapping<T extends object>(transformedClass: Constructor<T>, originalClass: Constructor<T>): void;
 
@@ -1180,4 +1186,4 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
 declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value | undefined;
 
 export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, assertInjectionContext, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
-export type { ChildContainerOptions, ClassProvider, ClassRef, Constructor, Container, ContainerHook, ContainerOptions, ExistingProvider, FactoryProvider, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };
+export type { ChildContainerOptions, ClassProvider, ClassRef, Constructor, Container, ContainerHook, ContainerOptions, ExistingProvider, FactoryProvider, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, Type, ValueProvider };

package/dist/cjs/index.js

@@ -33,8 +33,9 @@ function throwResolutionError(tokenInfo, aliases, cause) {
 // @internal
 function throwParameterResolutionError(ctor, methodKey, dependency, cause) {
     const location = getLocation(ctor, methodKey);
+    const [token] = dependency.tokenRef.getRefTokens();
     const tokenName = getFullTokenName([
-        dependency.tokenRef?.getRefToken(),
+        token,
         dependency.name
     ]);
     const msg = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
@@ -167,7 +168,7 @@ function ensureInjectionContext(name) {
  * Asserts that the current stack frame is within an injection context,
  * meaning it has access to injection functions (`inject`, `optional`, etc.).
  *
- * @param fn The function performing the assertion, or a string name used in the error message.
+ * @param fn - The function performing the assertion, or a string name used in the error message.
  * @throws {Error} If the current stack frame is not within an injection context.
  */ function assertInjectionContext(fn) {
     const name = typeof fn === "function" ? `${fn.name || "<unnamed>"}()` : fn;
@@ -226,8 +227,12 @@ function injectBy(thisArg, token, name) {
         getRefClass: ()=>Class()
     };
 }
-// @__NO_SIDE_EFFECTS__
-function tokenRef(token) {
+/**
+ * Allows referencing one or multiple tokens declared later in the file by wrapping them
+ * into a lazily evaluated function.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function tokenRef(token) {
     return {
         getRefTokens: ()=>{
             // Normalize the single token here so that we don't have to do it at every getRefTokens call site
@@ -236,11 +241,6 @@ function tokenRef(token) {
                 tokenOrTokens
             ];
             return new Set(tokensArray);
-        },
-        getRefToken: ()=>{
-            const tokenOrTokens = token();
-            check(!Array.isArray(tokenOrTokens), "internal error: ref tokens should be a single token");
-            return tokenOrTokens;
         }
     };
 }
@@ -249,12 +249,8 @@ function isClassRef(value) {
     return value != null && typeof value === "object" && typeof value.getRefClass === "function";
 }
 // @internal
-function isTokensRef(value) {
-    return value != null && typeof value === "object" && typeof value.getRefTokens === "function";
-}
-// @internal
 function isTokenRef(value) {
-    return value != null && typeof value === "object" && typeof value.getRefToken === "function";
+    return value != null && typeof value === "object" && typeof value.getRefTokens === "function";
 }
 
 // @internal
@@ -264,7 +260,7 @@ class Metadata {
             ctor: [],
             methods: new Map()
         };
-        this.tokensRef = {
+        this.tokenRef = {
             getRefTokens: ()=>new Set()
         };
         this.provider = {
@@ -335,14 +331,14 @@ function getMetadata(classOrRef) {
  * 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.
- *
- * @remarks
- * This API affects the core class identity resolution mechanism of the DI system.
+ * **IMPORTANT**:
+ * this API affects the core class identity resolution mechanism of the DI system.
  * Incorrect usage may cause metadata to be misassociated, leading to subtle errors.
  * Use only when manipulating constructors (e.g., via decorators or proxies),
  * and ensure the mapping is correct.
+ *
+ * @param transformedClass - The constructor function returned by a class decorator or factory.
+ * @param originalClass - The original constructor function.
  */ function setClassIdentityMapping(transformedClass, originalClass) {
     classIdentityMap.set(transformedClass, originalClass);
 }
@@ -556,16 +552,12 @@ class TokenRegistry {
     clearCache() {
         const values = new Set();
         for (const registrations of this.myRegistrations.values()){
-            for(let i = 0; i < registrations.length; i++){
-                const registration = registrations[i];
+            for (const registration of registrations){
                 const valueRef = registration.valueRef;
                 if (valueRef) {
                     values.add(valueRef.current);
                 }
-                registrations[i] = {
-                    ...registration,
-                    valueRef: undefined
-                };
+                registration.valueRef = undefined;
             }
         }
         return Array.from(values);
@@ -777,7 +769,7 @@ function isDisposable(value) {
         this.myTokenRegistry.put(Class, registration);
         // Register the additional tokens specified via class decorators.
         // These tokens will point to the original Class token and will have the same scope.
-        for (const token of metadata.tokensRef.getRefTokens()){
+        for (const token of metadata.tokenRef.getRefTokens()){
             this.myTokenRegistry.put(token, {
                 name: name,
                 provider: {
@@ -1063,7 +1055,7 @@ function isDisposable(value) {
     }
     // Call context: decorator-based injection
     resolveDependency(dependency, instance) {
-        const token = dependency.tokenRef?.getRefToken();
+        const [token] = dependency.tokenRef.getRefTokens();
         check(token, `token passed to @${dependency.appliedBy} was undefined (possible circular imports)`);
         const name = dependency.name;
         switch(dependency.appliedBy){
@@ -1139,12 +1131,11 @@ function isDisposable(value) {
  * @__NO_SIDE_EFFECTS__
  */ function EagerInstantiate() {
     return function(Class) {
-        const ctor = Class;
-        const metadata = getMetadata(ctor);
+        const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === "Container", ()=>{
             const { value, appliedBy } = currentScope;
-            const className = getTokenName(ctor);
+            const className = getTokenName(Class);
             return `class ${className}: scope ${value} was already set by @${appliedBy},\n  ` + `but @EagerInstantiate is trying to set a conflicting scope Container.\n  ` + `Only one decorator should set the class scope, or all must agree on the same value.`;
         });
         metadata.eagerInstantiate = true;
@@ -1171,12 +1162,12 @@ function Injectable(...args) {
     return function(Class) {
         const metadata = getMetadata(Class);
         const arg0 = args[0];
-        const tokensRef = isTokensRef(arg0) ? arg0 : tokenRef(()=>args);
-        const existingTokensRef = metadata.tokensRef;
-        metadata.tokensRef = {
+        const ref = isTokenRef(arg0) ? arg0 : tokenRef(()=>args);
+        const existingTokensRef = metadata.tokenRef;
+        metadata.tokenRef = {
             getRefTokens: ()=>{
                 const existingTokens = existingTokensRef.getRefTokens();
-                for (const token of tokensRef.getRefTokens()){
+                for (const token of ref.getRefTokens()){
                     existingTokens.add(token);
                 }
                 return existingTokens;
@@ -1219,9 +1210,9 @@ function InjectAll(token) {
     return function(target, propertyKey, parameterIndex) {
         if (parameterIndex === undefined) {
             // The decorator has been applied to the class
-            const ctor = target;
-            const metadata = getMetadata(ctor);
-            const className = getTokenName(ctor);
+            const Class = target;
+            const metadata = getMetadata(Class);
+            const className = getTokenName(Class);
             check(metadata.name === undefined, `multiple @Named decorators on class ${className}, but only one is allowed`);
             metadata.name = name;
         } else {
@@ -1284,13 +1275,12 @@ function OptionalAll(token) {
  * @__NO_SIDE_EFFECTS__
  */ function Scoped(scope) {
     return function(Class) {
-        const ctor = Class;
-        const metadata = getMetadata(ctor);
+        const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
         check(!currentScope || currentScope.value === scope, ()=>{
             const { value, appliedBy } = currentScope;
             const by = appliedBy === "Scoped" ? `another @${appliedBy} decorator` : `@${appliedBy}`;
-            const className = getTokenName(ctor);
+            const className = getTokenName(Class);
             return `class ${className}: scope ${value} was already set by ${by},\n  ` + `but @Scoped is trying to set a conflicting scope ${scope}.\n  ` + `Only one decorator should set the class scope, or all must agree on the same value.`;
         });
         metadata.scope = {