@lppedd/di-wise-neo 0.14.2 → 0.15.1

package/README.md

@@ -435,11 +435,11 @@ Normally, attempting to do that would result in a `ReferenceError`:
 
 > ReferenceError: Cannot access 'IStore' before initialization
 
-We can work around this problem by using the `forwardRef` helper function:
+We can work around this problem by using the `tokenRef` helper function:
 
 ```ts
 export class ExtensionContext {
-  constructor(@OptionalAll(forwardRef(() => IStore)) readonly stores: Store[]) {}
+  constructor(@OptionalAll(tokenRef(() => IStore)) readonly stores: Store[]) {}
 
   /* ... */
 }

package/dist/cjs/index.d.ts

@@ -119,6 +119,33 @@ declare function createType<T>(typeName: string): Type<T>;
  */
 declare function createType<T>(typeName: string, provider: Provider<T>, options?: RegistrationOptions): ProviderType<T>;
 
+interface ClassRef<Instance extends object> {
+    readonly getRefClass: () => Constructor<Instance>;
+}
+interface TokensRef<Value = any> {
+    readonly getRefTokens: () => Set<Token<Value>>;
+}
+interface TokenRef<Value = any> {
+    readonly getRefToken: () => Token<Value>;
+}
+/**
+ * Allows referencing a class declared later in the file by wrapping it
+ * in a lazily evaluated function.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+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.
+ */
+declare function tokenRef<Value>(token: () => Token<Value>): TokenRef<Value>;
+
 /**
  * Provides a class instance for a token via a class constructor.
  */
@@ -126,7 +153,7 @@ interface ClassProvider<Instance extends object> {
     /**
      * The class to instantiate for the token.
      */
-    readonly useClass: Constructor<Instance>;
+    readonly useClass: Constructor<Instance> | ClassRef<Instance>;
     /**
      * An optional name to qualify this provider.
      * If specified, the token must be resolved using the same name.
@@ -597,23 +624,6 @@ declare function AutoRegister(): ClassDecorator;
  */
 declare function EagerInstantiate(): ClassDecorator;
 
-interface TokensRef<Value = any> {
-    readonly getRefTokens: () => Set<Token<Value>>;
-}
-interface TokenRef<Value = any> {
-    readonly getRefToken: () => Token<Value>;
-}
-/**
- * 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 declared later in the file by wrapping it
- * in a lazily evaluated function.
- */
-declare function forwardRef<Value>(token: () => Token<Value>): TokenRef<Value>;
-
 /**
  * Parameter decorator that injects the instance associated with the given class.
  *
@@ -636,7 +646,7 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
  * Parameter decorator that injects the value associated with the given token.
  *
  * Allows referencing a token declared later in the file by using the
- * {@link forwardRef} helper function.
+ * {@link tokenRef} helper function.
  *
  * Throws an error if:
  * - The token is not registered in the container.
@@ -646,7 +656,7 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@Inject(forwardRef(() => Wand)) readonly wand: Wand) {}
+ *   constructor(@Inject(tokenRef(() => Wand)) readonly wand: Wand) {}
  * }
  * // Other code...
  * class Wand {}
@@ -674,11 +684,11 @@ declare function Injectable<This extends object, Value extends This>(...tokens:
  * The container uses {@link ExistingProvider} under the hood.
  *
  * Allows referencing tokens that are declared later in the file by using
- * the {@link forwardRef} helper function.
+ * the {@link tokenRef} helper function.
  *
  * @example
  * ```ts
- * @Injectable(forwardRef() => Weapon) // Weapon is declared after Wand
+ * @Injectable(tokenRef() => Weapon) // Weapon is declared after Wand
  * class Wizard {}
  * // Other code...
  * class Weapon {}
@@ -709,7 +719,7 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
  * associated with the given token.
  *
  * Allows referencing a token declared later in the file by using the
- * {@link forwardRef} helper function.
+ * {@link tokenRef} helper function.
  *
  * Throws an error if:
  * - The token is not registered in the container.
@@ -718,7 +728,7 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@InjectAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
+ *   constructor(@InjectAll(tokenRef(() => Wand)) readonly wands: Wand[]) {}
  * }
  * // Other code...
  * class Wand {}
@@ -767,7 +777,7 @@ declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
  * or `undefined` if the token is not registered in the container.
  *
  * Allows referencing a token declared later in the file by using the
- * {@link forwardRef} helper function.
+ * {@link tokenRef} helper function.
  *
  * Throws an error if a circular dependency is detected. Use function injection
  * with {@link optionalBy} if resolving circular dependencies is necessary.
@@ -775,7 +785,7 @@ declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@Optional(forwardRef(() => Wand)) readonly wand: Wand | undefined) {}
+ *   constructor(@Optional(tokenRef(() => Wand)) readonly wand: Wand | undefined) {}
  * }
  * // Other code...
  * class Wand {}
@@ -805,14 +815,14 @@ declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
  * in the container.
  *
  * Allows referencing a token declared later in the file by using the
- * {@link forwardRef} helper function.
+ * {@link tokenRef} helper function.
  *
  * Throws an error if a circular dependency is detected.
  *
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@OptionalAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
+ *   constructor(@OptionalAll(tokenRef(() => Wand)) readonly wands: Wand[]) {}
  * }
  * // Other code...
  * class Wand {}
@@ -1137,5 +1147,5 @@ declare function optionalAll<Instance extends object>(Class: Constructor<Instanc
  */
 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, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };
+export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, classRef, createContainer, createType, inject, injectAll, injectBy, optional, optionalAll, optionalBy, setClassIdentityMapping, tokenRef };
+export type { ClassProvider, ClassRef, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, ProviderType, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };

package/dist/cjs/index.js

@@ -34,7 +34,7 @@ function throwResolutionError(tokenInfo, aliases, cause) {
 function throwParameterResolutionError(ctor, methodKey, dependency, cause) {
     const location = getLocation(ctor, methodKey);
     const tokenName = getFullTokenName([
-        dependency.tokenRef.getRefToken(),
+        dependency.tokenRef?.getRefToken(),
         dependency.name
     ]);
     const msg = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
@@ -56,7 +56,7 @@ function getTokenName(token) {
     return token.name || "<unnamed>";
 }
 function getFullTokenName([token, name]) {
-    const tokenName = token.name || "<unnamed>";
+    const tokenName = token ? token.name || "<unnamed>" : "<undefined token>";
     return name ? `${tokenName}["${name}"]` : tokenName;
 }
 function getCause(error) {
@@ -186,6 +186,47 @@ function injectAll(token) {
     return context.container.resolveAll(token);
 }
 
+/**
+ * Allows referencing a class declared later in the file by wrapping it
+ * in a lazily evaluated function.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function classRef(Class) {
+    return {
+        getRefClass: ()=>Class()
+    };
+}
+// @__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
+            const tokenOrTokens = token();
+            const tokensArray = Array.isArray(tokenOrTokens) ? tokenOrTokens : [
+                tokenOrTokens
+            ];
+            return new Set(tokensArray);
+        },
+        getRefToken: ()=>{
+            const tokenOrTokens = token();
+            check(!Array.isArray(tokenOrTokens), "internal error: ref tokens should be a single token");
+            return tokenOrTokens;
+        }
+    };
+}
+// @internal
+function isClassRef(value) {
+    return value && typeof value === "object" && typeof value.getRefClass === "function";
+}
+// @internal
+function isTokensRef(value) {
+    return value && typeof value === "object" && typeof value.getRefTokens === "function";
+}
+// @internal
+function isTokenRef(value) {
+    return value && typeof value === "object" && typeof value.getRefToken === "function";
+}
+
 // @internal
 class Metadata {
     constructor(Class){
@@ -234,7 +275,8 @@ class Metadata {
     }
 }
 // @internal
-function getMetadata(Class) {
+function getMetadata(classOrRef) {
+    const Class = isClassRef(classOrRef) ? classOrRef.getRefClass() : classOrRef;
     const originalClass = classIdentityMap.get(Class) ?? Class;
     let metadata = metadataMap.get(originalClass);
     if (!metadata) {
@@ -890,6 +932,7 @@ function isDisposable(value) {
         }
         return [];
     }
+    // Call context: decorator-based injection
     injectMethodDependencies(registration, instance) {
         const dependencies = registration.dependencies;
         if (dependencies) {
@@ -913,6 +956,7 @@ function isDisposable(value) {
         }
         return instance;
     }
+    // Call context: decorator-based injection
     resolveArgs(deps, ctor, instance, methodKey) {
         const sortedDeps = deps.sort((a, b)=>a.index - b.index);
         const args = [];
@@ -925,8 +969,10 @@ function isDisposable(value) {
         }
         return args;
     }
+    // Call context: decorator-based injection
     resolveDependency(dependency, instance) {
-        const token = dependency.tokenRef.getRefToken();
+        const token = dependency.tokenRef?.getRefToken();
+        check(token, `token passed to @${dependency.appliedBy} was undefined (possible circular imports)`);
         const name = dependency.name;
         switch(dependency.appliedBy){
             case "Inject":
@@ -1007,33 +1053,6 @@ function isDisposable(value) {
     };
 }
 
-// @__NO_SIDE_EFFECTS__
-function forwardRef(token) {
-    return {
-        getRefTokens: ()=>{
-            // 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
-            ];
-            return new Set(tokensArray);
-        },
-        getRefToken: ()=>{
-            const tokenOrTokens = token();
-            check(!Array.isArray(tokenOrTokens), "internal error: ref tokens should be a single token");
-            return tokenOrTokens;
-        }
-    };
-}
-// @internal
-function isTokensRef(value) {
-    return value && typeof value === "object" && typeof value.getRefTokens === "function";
-}
-// @internal
-function isTokenRef(value) {
-    return value && typeof value === "object" && typeof value.getRefToken === "function";
-}
-
 // @internal
 function updateParameterMetadata(decorator, target, methodKey, parameterIndex, updateFn) {
     // Error out immediately if the decorator has been applied to a static method
@@ -1089,7 +1108,7 @@ function Inject(token) {
         updateParameterMetadata("Inject", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Inject";
-            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+            dependency.tokenRef = isTokenRef(token) ? token : tokenRef(()=>token);
         });
     };
 }
@@ -1099,7 +1118,7 @@ function Injectable(...args) {
     return function(Class) {
         const metadata = getMetadata(Class);
         const arg0 = args[0];
-        const tokensRef = isTokensRef(arg0) ? arg0 : forwardRef(()=>args);
+        const tokensRef = isTokensRef(arg0) ? arg0 : tokenRef(()=>args);
         const existingTokensRef = metadata.tokensRef;
         metadata.tokensRef = {
             getRefTokens: ()=>{
@@ -1119,7 +1138,7 @@ function InjectAll(token) {
         updateParameterMetadata("InjectAll", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "InjectAll";
-            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+            dependency.tokenRef = isTokenRef(token) ? token : tokenRef(()=>token);
             checkNamedDecorator(dependency, target, propertyKey, parameterIndex);
         });
     };
@@ -1172,7 +1191,7 @@ function Optional(token) {
         updateParameterMetadata("Optional", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "Optional";
-            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+            dependency.tokenRef = isTokenRef(token) ? token : tokenRef(()=>token);
         });
     };
 }
@@ -1183,7 +1202,7 @@ function OptionalAll(token) {
         updateParameterMetadata("OptionalAll", target, propertyKey, parameterIndex, (dependency)=>{
             checkSingleDecorator(dependency, target, propertyKey, parameterIndex);
             dependency.appliedBy = "OptionalAll";
-            dependency.tokenRef = isTokenRef(token) ? token : forwardRef(()=>token);
+            dependency.tokenRef = isTokenRef(token) ? token : tokenRef(()=>token);
             checkNamedDecorator(dependency, target, propertyKey, parameterIndex);
         });
     };
@@ -1321,9 +1340,9 @@ exports.Scope = Scope;
 exports.Scoped = Scoped;
 exports.applyMiddleware = applyMiddleware;
 exports.build = build;
+exports.classRef = classRef;
 exports.createContainer = createContainer;
 exports.createType = createType;
-exports.forwardRef = forwardRef;
 exports.inject = inject;
 exports.injectAll = injectAll;
 exports.injectBy = injectBy;
@@ -1331,4 +1350,5 @@ exports.optional = optional;
 exports.optionalAll = optionalAll;
 exports.optionalBy = optionalBy;
 exports.setClassIdentityMapping = setClassIdentityMapping;
+exports.tokenRef = tokenRef;
 //# sourceMappingURL=index.js.map