@lppedd/di-wise-neo 0.14.1 → 0.15.0

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,47 +624,39 @@ 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.
  *
- * Throws an error if the class is not registered in the container.
+ * Throws an error if:
+ * - The class is not registered in the container.
+ * - A circular dependency is detected. Use function injection with {@link injectBy}
+ *   if resolving circular dependencies is necessary.
  */
 declare function Inject<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
  * Parameter decorator that injects the value associated with the given token.
  *
- * Throws an error if the token is not registered in the container.
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected. Use function injection with {@link injectBy}
+ *   if resolving circular dependencies is necessary.
  */
 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.
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected. Use function injection with {@link injectBy}
+ *   if resolving circular dependencies is necessary.
  *
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@Inject(forwardRef(() => Wand)) readonly wand: Wand) {}
+ *   constructor(@Inject(tokenRef(() => Wand)) readonly wand: Wand) {}
  * }
  * // Other code...
  * class Wand {}
@@ -665,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 {}
@@ -681,14 +700,18 @@ declare function Injectable<This extends object, Value extends This>(tokens: Tok
  * Parameter decorator that injects all instances provided by the registrations
  * associated with the given class.
  *
- * Throws an error if the class is not registered in the container.
+ * Throws an error if:
+ * - The class is not registered in the container.
+ * - A circular dependency is detected.
  */
 declare function InjectAll<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
  * Parameter decorator that injects all values provided by the registrations
  * associated with the given token.
  *
- * Throws an error if the token is not registered in the container.
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected.
  */
 declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
 /**
@@ -696,14 +719,16 @@ 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.
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected.
  *
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@InjectAll(forwardRef(() => Wand)) readonly wands: Wand[]) {}
+ *   constructor(@InjectAll(tokenRef(() => Wand)) readonly wands: Wand[]) {}
  * }
  * // Other code...
  * class Wand {}
@@ -734,11 +759,17 @@ declare function Named(name: string): ClassDecorator & ParameterDecorator;
 /**
  * Parameter decorator that injects the instance associated with the given class,
  * or `undefined` if the class is not registered in the container.
+ *
+ * Throws an error if a circular dependency is detected. Use function injection
+ * with {@link optionalBy} if resolving circular dependencies is necessary.
  */
 declare function Optional<Instance extends object>(Class: Constructor<Instance>): ParameterDecorator;
 /**
  * Parameter decorator that injects the value associated with the given token,
  * or `undefined` if the token is not registered in the container.
+ *
+ * Throws an error if a circular dependency is detected. Use function injection
+ * with {@link optionalBy} if resolving circular dependencies is necessary.
  */
 declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
 /**
@@ -746,12 +777,15 @@ 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.
  *
  * @example
  * ```ts
  * class Wizard {
- *   constructor(@Optional(forwardRef(() => Wand)) readonly wand: Wand | undefined) {}
+ *   constructor(@Optional(tokenRef(() => Wand)) readonly wand: Wand | undefined) {}
  * }
  * // Other code...
  * class Wand {}
@@ -763,12 +797,16 @@ 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
  * in the container.
+ *
+ * Throws an error if a circular dependency is detected.
  */
 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
  * in the container.
+ *
+ * Throws an error if a circular dependency is detected.
  */
 declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
 /**
@@ -777,12 +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 {}
@@ -817,13 +857,19 @@ declare function Scoped(scope: Scope): ClassDecorator;
 /**
  * Injects the instance associated with the given class.
  *
- * Throws an error if the class is not registered in the container.
+ * Throws an error if:
+ * - The class is not registered in the container.
+ * - A circular dependency is detected. Use {@link injectBy} if resolving
+ *   circular dependencies is necessary.
  */
 declare function inject<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance;
 /**
  * Injects the value associated with the given token.
  *
- * Throws an error if the token is not registered in the container.
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected. Use {@link injectBy} if resolving
+ *   circular dependencies is necessary.
  */
 declare function inject<Value>(token: Token<Value>, name?: string): Value;
 /**
@@ -832,7 +878,7 @@ declare function inject<Value>(token: Token<Value>, name?: string): Value;
  * Throws an error if the class is not registered in the container.
  *
  * Compared to {@link inject}, `injectBy` accepts a `thisArg` argument
- * (the containing class) which is used to resolve circular dependencies.
+ * (e.g., the containing class instance) which is used to resolve circular dependencies.
  *
  * @example
  * ```ts
@@ -856,7 +902,7 @@ declare function injectBy<Instance extends object>(thisArg: any, Class: Construc
  * Throws an error if the token is not registered in the container.
  *
  * Compared to {@link inject}, `injectBy` accepts a `thisArg` argument
- * (the containing class) which is used to resolve circular dependencies.
+ * (e.g., the containing class instance) which is used to resolve circular dependencies.
  *
  * @example
  * ```ts
@@ -878,13 +924,17 @@ declare function injectBy<Value>(thisArg: any, token: Token<Value>, name?: strin
 /**
  * Injects all instances provided by the registrations associated with the given class.
  *
- * Throws an error if the class is not registered in the container.
+ * Throws an error if:
+ * - The class is not registered in the container.
+ * - A circular dependency is detected.
  */
 declare function injectAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
 /**
  * Injects all values provided by the registrations associated with the given token.
  *
- * Throws an error if the token is not registered in the container.
+ * Throws an error if:
+ * - The token is not registered in the container.
+ * - A circular dependency is detected.
  */
 declare function injectAll<Value>(token: Token<Value>): Value[];
 
@@ -1044,11 +1094,17 @@ declare function applyMiddleware(container: Container, middlewares: Middleware[]
 /**
  * Injects the instance associated with the given class,
  * or `undefined` if the class is not registered in the container.
+ *
+ * Throws an error if a circular dependency is detected.
+ * Use {@link optionalBy} if resolving circular dependencies is necessary.
  */
 declare function optional<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance | undefined;
 /**
  * Injects the value associated with the given token,
  * or `undefined` if the token is not registered in the container.
+ *
+ * Throws an error if a circular dependency is detected.
+ * Use {@link optionalBy} if resolving circular dependencies is necessary.
  */
 declare function optional<Value>(token: Token<Value>, name?: string): Value | undefined;
 /**
@@ -1056,7 +1112,7 @@ declare function optional<Value>(token: Token<Value>, name?: string): Value | un
  * or `undefined` if the class is not registered in the container.
  *
  * Compared to {@link optional}, `optionalBy` accepts a `thisArg` argument
- * (the containing class) which is used to resolve circular dependencies.
+ * (e.g., the containing class instance) which is used to resolve circular dependencies.
  *
  * @param thisArg - The containing instance, used to help resolve circular dependencies.
  * @param Class - The class to resolve.
@@ -1068,7 +1124,7 @@ declare function optionalBy<Instance extends object>(thisArg: any, Class: Constr
  * or `undefined` if the token is not registered in the container.
  *
  * Compared to {@link optional}, `optionalBy` accepts a `thisArg` argument
- * (the containing class) which is used to resolve circular dependencies.
+ * (e.g., the containing class instance) which is used to resolve circular dependencies.
  *
  * @param thisArg - The containing instance, used to help resolve circular dependencies.
  * @param token - The token to resolve.
@@ -1079,13 +1135,17 @@ declare function optionalBy<Value>(thisArg: any, token: Token<Value>, name?: str
 /**
  * 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.
+ *
+ * Throws an error if a circular dependency is detected.
  */
 declare function optionalAll<Instance extends object>(Class: Constructor<Instance>): Instance[];
 /**
  * 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.
+ *
+ * Throws an error if a circular dependency is detected.
  */
 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

@@ -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) {
@@ -337,7 +379,6 @@ const Scope = {
    */ Container: "Container"
 };
 
-// @internal
 // @__NO_SIDE_EFFECTS__
 function createType(typeName, provider, options) {
     const name = `Type<${typeName}>`;
@@ -1008,32 +1049,6 @@ function isDisposable(value) {
     };
 }
 
-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
@@ -1083,23 +1098,23 @@ function describeParam(target, methodKey, parameterIndex) {
     return `${location}(parameter #${parameterIndex})`;
 }
 
+// @__NO_SIDE_EFFECTS__
 function Inject(token) {
     return function(target, propertyKey, parameterIndex) {
         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);
         });
     };
 }
 
-/**
- * @__NO_SIDE_EFFECTS__
- */ function Injectable(...args) {
+// @__NO_SIDE_EFFECTS__
+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: ()=>{
@@ -1113,12 +1128,13 @@ function Inject(token) {
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function InjectAll(token) {
     return function(target, propertyKey, parameterIndex) {
         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);
         });
     };
@@ -1165,22 +1181,24 @@ function InjectAll(token) {
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function Optional(token) {
     return function(target, propertyKey, parameterIndex) {
         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);
         });
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function OptionalAll(token) {
     return function(target, propertyKey, parameterIndex) {
         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);
         });
     };
@@ -1318,9 +1336,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;
@@ -1328,4 +1346,5 @@ exports.optional = optional;
 exports.optionalAll = optionalAll;
 exports.optionalBy = optionalBy;
 exports.setClassIdentityMapping = setClassIdentityMapping;
+exports.tokenRef = tokenRef;
 //# sourceMappingURL=index.js.map