@lppedd/di-wise-neo 0.14.0 → 0.14.2

package/dist/cjs/index.d.ts

@@ -55,18 +55,14 @@ interface Type<T> {
      * The name of the type.
      */
     readonly name: string;
-    /**
-     * Returns the stringified representation of the type.
-     */
-    readonly toString: () => string;
     /**
      * Ensures that different `Type<T>` types are not structurally compatible.
      *
-     * This property is never used at runtime.
+     * This property is always `undefined` and is never used at runtime.
      *
      * @private
      */
-    readonly __type?: T;
+    readonly __type: T | undefined;
 }
 /**
  * An injectable type `T` with a default {@link Provider} and optional default registration options.
@@ -91,7 +87,7 @@ interface Constructor<Instance extends object> {
 /**
  * Token type.
  */
-type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value> : Type<Value>;
+type Token<Value = any> = [Value] extends [object] ? Type<Value> | Constructor<Value & object> : Type<Value>;
 /**
  * Describes a {@link Token} array with at least one element.
  */
@@ -621,13 +617,19 @@ 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;
 /**
@@ -636,7 +638,10 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
  * Allows referencing a token declared later in the file by using the
  * {@link forwardRef} 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
@@ -685,14 +690,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;
 /**
@@ -702,7 +711,9 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
  * Allows referencing a token declared later in the file by using the
  * {@link forwardRef} 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
@@ -738,11 +749,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;
 /**
@@ -752,6 +769,9 @@ declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
  * Allows referencing a token declared later in the file by using the
  * {@link forwardRef} 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 {
@@ -767,12 +787,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;
 /**
@@ -783,6 +807,8 @@ declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
  * Allows referencing a token declared later in the file by using the
  * {@link forwardRef} helper function.
  *
+ * Throws an error if a circular dependency is detected.
+ *
  * @example
  * ```ts
  * class Wizard {
@@ -821,13 +847,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;
 /**
@@ -836,7 +868,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
@@ -860,7 +892,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
@@ -882,13 +914,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[];
 
@@ -1048,11 +1084,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;
 /**
@@ -1060,7 +1102,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.
@@ -1072,7 +1114,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.
@@ -1083,11 +1125,15 @@ 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[];
 

package/dist/cjs/index.js

@@ -337,7 +337,6 @@ const Scope = {
    */ Container: "Container"
 };
 
-// @internal
 // @__NO_SIDE_EFFECTS__
 function createType(typeName, provider, options) {
     const name = `Type<${typeName}>`;
@@ -575,13 +574,66 @@ function isDisposable(value) {
             if (isConstructor(token)) {
                 this.registerClass(token);
             } else {
-                this.registerType(token, token.provider, token.options);
+                this.registerToken(token, token.provider, token.options);
             }
         } else {
-            this.registerType(...args);
+            this.registerToken(...args);
         }
         return this;
     }
+    unregister(token, name) {
+        this.checkDisposed();
+        const registrations = this.myTokenRegistry.delete(token, name);
+        const values = new Set();
+        for (const registration of registrations){
+            const value = registration.value;
+            if (value) {
+                values.add(value.current);
+            }
+        }
+        return Array.from(values);
+    }
+    resolve(token, name) {
+        this.checkDisposed();
+        return this.resolveToken(token, name, false);
+    }
+    tryResolve(token, name) {
+        this.checkDisposed();
+        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) {
+            return;
+        }
+        // Dispose children containers first
+        for (const child of this.myChildren){
+            child.dispose();
+        }
+        this.myChildren.clear();
+        // Remove ourselves from our parent container
+        this.myParent?.myChildren?.delete(this);
+        this.myDisposed = true;
+        const [, registrations] = this.myTokenRegistry.deleteAll();
+        const disposedRefs = new Set();
+        // Dispose all resolved (aka instantiated) tokens that implement the Disposable interface
+        for (const registration of registrations){
+            const value = registration.value?.current;
+            if (isDisposable(value) && !disposedRefs.has(value)) {
+                disposedRefs.add(value);
+                value.dispose();
+            }
+        }
+        // Allow values to be GCed
+        disposedRefs.clear();
+    }
     registerClass(Class) {
         const metadata = getMetadata(Class);
         const name = metadata.name;
@@ -614,7 +666,7 @@ function isDisposable(value) {
             this.resolveProviderValue(Class, registration);
         }
     }
-    registerType(token, provider, options) {
+    registerToken(token, provider, options) {
         const name = provider.name;
         check(name === undefined || name.trim(), `name qualifier for token ${getTokenName(token)} must not be empty`);
         if (isClassProvider(provider)) {
@@ -647,59 +699,6 @@ function isDisposable(value) {
             });
         }
     }
-    unregister(token, name) {
-        this.checkDisposed();
-        const registrations = this.myTokenRegistry.delete(token, name);
-        const values = new Set();
-        for (const registration of registrations){
-            const value = registration.value;
-            if (value) {
-                values.add(value.current);
-            }
-        }
-        return Array.from(values);
-    }
-    resolve(token, name) {
-        this.checkDisposed();
-        return this.resolveToken(token, name, false);
-    }
-    tryResolve(token, name) {
-        this.checkDisposed();
-        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) {
-            return;
-        }
-        // Dispose children containers first
-        for (const child of this.myChildren){
-            child.dispose();
-        }
-        this.myChildren.clear();
-        // Remove ourselves from our parent container
-        this.myParent?.myChildren?.delete(this);
-        this.myDisposed = true;
-        const [, registrations] = this.myTokenRegistry.deleteAll();
-        const disposedRefs = new Set();
-        // Dispose all resolved (aka instantiated) tokens that implement the Disposable interface
-        for (const registration of registrations){
-            const value = registration.value?.current;
-            if (isDisposable(value) && !disposedRefs.has(value)) {
-                disposedRefs.add(value);
-                value.dispose();
-            }
-        }
-        // Allow values to be GCed
-        disposedRefs.clear();
-    }
     resolveToken(token, name, optional) {
         let registration = this.myTokenRegistry.get(token, name);
         if (!registration && isConstructor(token)) {
@@ -1008,6 +1007,7 @@ function isDisposable(value) {
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function forwardRef(token) {
     return {
         getRefTokens: ()=>{
@@ -1083,6 +1083,7 @@ 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)=>{
@@ -1093,9 +1094,8 @@ function Inject(token) {
     };
 }
 
-/**
- * @__NO_SIDE_EFFECTS__
- */ function Injectable(...args) {
+// @__NO_SIDE_EFFECTS__
+function Injectable(...args) {
     return function(Class) {
         const metadata = getMetadata(Class);
         const arg0 = args[0];
@@ -1113,6 +1113,7 @@ function Inject(token) {
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function InjectAll(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("InjectAll", target, propertyKey, parameterIndex, (dependency)=>{
@@ -1165,6 +1166,7 @@ function InjectAll(token) {
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function Optional(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("Optional", target, propertyKey, parameterIndex, (dependency)=>{
@@ -1175,6 +1177,7 @@ function Optional(token) {
     };
 }
 
+// @__NO_SIDE_EFFECTS__
 function OptionalAll(token) {
     return function(target, propertyKey, parameterIndex) {
         updateParameterMetadata("OptionalAll", target, propertyKey, parameterIndex, (dependency)=>{