@lppedd/di-wise-neo 0.19.0 → 0.21.0

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
-type ClassDecorator<Class extends object> = (target: Constructor<Class>) => Constructor<Class> | void;
+type ClassDecorator<Class extends object> = <T extends Constructor<Class>>(target: T) => T | void;
 type ParameterDecorator = (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
 
 declare const Scope: {
@@ -34,7 +34,7 @@ interface RegistrationOptions {
 /**
  * Create a one-off type token from a factory function.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   wand = inject(
@@ -102,7 +102,7 @@ type Tokens<Value> = [Token<Value>, ...Token<Value>[]];
 /**
  * Creates a type token.
  *
- * @example
+ * Example:
  * ```ts
  * const ISpell = createType<Spell>("Spell");
  * container.register(ISpell, {
@@ -114,7 +114,7 @@ declare function createType<T>(typeName: string): Type<T>;
 /**
  * Creates a type token with a default {@link Provider} and optional default registration options.
  *
- * @example
+ * Example:
  * ```ts
  * // Notice how we pass in a Provider directly at type creation site
  * const ISpell = createType<Spell>("Spell", {
@@ -134,9 +134,7 @@ interface TokenRef<Value> {
 }
 /**
  * Allows referencing a class declared later in the file by wrapping it
- * in a lazily evaluated function.
- *
- * @__NO_SIDE_EFFECTS__
+ * into a lazily evaluated function.
  */
 declare function classRef<Instance extends object>(Class: () => Constructor<Instance>): ClassRef<Instance>;
 /**
@@ -159,7 +157,7 @@ interface ClassProvider<Instance extends object> {
      *
      * Equivalent to decorating the class with `@Named(...)`.
      *
-     * @example
+     * Example:
      * ```ts
      * export class ExtensionContext {
      *   // Decorator-based injection
@@ -187,7 +185,7 @@ interface FactoryProvider<Value> {
      * An optional name to qualify this provider.
      * If specified, the token must be resolved using the same name.
      *
-     * @example
+     * Example:
      * ```ts
      * export class ExtensionContext {
      *   // Decorator-based injection
@@ -212,7 +210,7 @@ interface ValueProvider<Value> {
      * An optional name to qualify this provider.
      * If specified, the token must be resolved using the same name.
      *
-     * @example
+     * Example:
      * ```ts
      * export class ExtensionContext {
      *   // Decorator-based injection
@@ -234,7 +232,7 @@ interface ExistingProvider<Value> {
     /**
      * The existing token to alias, with an optional name qualifier.
      *
-     * @example
+     * Example:
      * ```ts
      * container.register(ISecretStorage, {
      *   useExisting: PersistentSecretStorage,
@@ -251,7 +249,7 @@ interface ExistingProvider<Value> {
      * An optional name to qualify this provider.
      * If specified, the token must be resolved using the same name.
      *
-     * @example
+     * Example:
      * ```ts
      * export class ExtensionContext {
      *   // Decorator-based injection
@@ -350,7 +348,7 @@ interface Container {
      */
     createChild(options?: Partial<ChildContainerOptions>): Container;
     /**
-     * Clears and returns all distinct values that were cached by this container.
+     * Clears and returns all distinct values 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 or child containers, if any, remain unchanged.
@@ -629,11 +627,13 @@ interface Container {
      * Disposes this container and all its cached values.
      *
      * Token values implementing a `Disposable` interface (e.g., objects with a `dispose()` function)
-     * are automatically disposed during this process.
+     * are also disposed. All disposals, whether synchronous or asynchronous, are returned as promises
+     * in an array. Callers may await these promises (e.g., using `Promise.allSettled()`) if they want
+     * to ensure that all async work has completed.
      *
      * Note that children containers are disposed first, in creation order.
      */
-    dispose(): void;
+    dispose(): Promise<unknown>[];
 }
 /**
  * Creates a new container.
@@ -644,7 +644,7 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  * Class decorator that enables auto-registration of an unregistered class
  * when the class is first resolved from the container.
  *
- * @example
+ * Example:
  * ```ts
  * @AutoRegister()
  * class Wizard {}
@@ -652,8 +652,6 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  * const wizard = container.resolve(Wizard);
  * container.isRegistered(Wizard); // => true
  * ```
- *
- * @__NO_SIDE_EFFECTS__
  */
 declare function AutoRegister<This extends object>(): ClassDecorator<This>;
 
@@ -664,7 +662,7 @@ declare function AutoRegister<This extends object>(): ClassDecorator<This>;
  * This causes the container to immediately create and cache the instance of the class,
  * instead of deferring instantiation until the first resolution.
  *
- * @example
+ * Example:
  * ```ts
  * @EagerInstantiate()
  * class Wizard {}
@@ -673,8 +671,6 @@ declare function AutoRegister<This extends object>(): ClassDecorator<This>;
  * // is immediately created and cached by the container
  * container.register(Wizard);
  * ```
- *
- * @__NO_SIDE_EFFECTS__
  */
 declare function EagerInstantiate<This extends object>(): ClassDecorator<This>;
 
@@ -699,15 +695,15 @@ 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 tokenRef} helper function.
+ * This overload allows referencing a token declared later in the file by using
+ * the {@link tokenRef} helper function.
  *
  * 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
+ * Example:
  * ```ts
  * class Wizard {
  *   constructor(@Inject(tokenRef(() => Wand)) readonly wand: Wand) {}
@@ -719,39 +715,56 @@ declare function Inject<Value>(token: Token<Value>): ParameterDecorator;
 declare function Inject<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
 /**
- * Class decorator that registers additional aliasing tokens for the decorated type
- * when the type is first registered in the container.
+ * Class decorator that registers additional aliasing tokens for the decorated type.
  *
- * The container uses {@link ExistingProvider} under the hood.
+ * The aliases are added using {@link ExistingProvider}(s) when the class is first
+ * registered in the container.
  *
- * @example
+ * Example:
  * ```ts
  * @Injectable(Weapon)
- * class Wand {}
+ * class Rifle {}
+ * ```
+ *
+ * Note that `@Injectable` decorators can be stacked to add multiple aliases.
+ *
+ * Example:
+ * ```ts
+ * @Injectable(Weapon)
+ * @Injectable(Gun) // Or just @Injectable(Weapon, Gun)
+ * class Rifle {}
  * ```
  */
 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, 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>;
 /**
- * Class decorator that registers additional aliasing tokens for the decorated type
- * when the type is first registered in the container.
+ * Class decorator that registers an additional aliasing token for the decorated type.
  *
- * The container uses {@link ExistingProvider} under the hood.
+ * The alias is added using an {@link ExistingProvider} when the class is first
+ * registered in the container.
  *
- * Allows referencing tokens that are declared later in the file by using
- * the {@link tokenRef} helper function.
+ * This overload allows referencing tokens that are declared later in the file
+ * by using the {@link tokenRef} helper function.
  *
- * @example
+ * Example:
  * ```ts
- * @Injectable(tokenRef() => Weapon) // Weapon is declared after Wand
- * class Wizard {}
+ * @Injectable(tokenRef(() => Weapon)) // Weapon is declared after Rifle
+ * class Rifle {}
  * // Other code...
- * class Weapon {}
+ * const Weapon = createType("Weapon");
+ * ```
+ *
+ * Note that `@Injectable` decorators can be stacked to add multiple aliases.
+ *
+ * Example:
+ * ```ts
+ * @Injectable(tokenRef(() => Weapon))
+ * @Injectable(Gun)
+ * class Rifle {}
  * ```
  */
 declare function Injectable<Value, This extends Value & object>(tokens: TokenRef<Value>): ClassDecorator<This>;
@@ -778,14 +791,14 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
  * Parameter decorator that injects all values provided by the registrations
  * associated with the given token.
  *
- * Allows referencing a token declared later in the file by using the
- * {@link tokenRef} helper function.
+ * This overload allows referencing a token declared later in the file by using
+ * the {@link tokenRef} helper function.
  *
  * Throws an error if:
  * - The token is not registered in the container.
  * - A circular dependency is detected.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   constructor(@InjectAll(tokenRef(() => Wand)) readonly wands: Wand[]) {}
@@ -802,7 +815,7 @@ declare function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  * This allows the container to distinguish between multiple implementations
  * of the same interface or type during registration and injection.
  *
- * @example
+ * Example:
  * ```ts
  * @Named("dumbledore")
  * class Dumbledore implements Wizard {}
@@ -811,8 +824,6 @@ declare function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
  * container.register(IWizard, { useClass: Dumbledore });
  * const dumbledore = container.resolve(IWizard, "dumbledore");
  * ```
- *
- * @__NO_SIDE_EFFECTS__
  */
 declare function Named<This extends object>(name: string): ClassDecorator<This> & ParameterDecorator;
 
@@ -836,13 +847,13 @@ declare function Optional<Value>(token: Token<Value>): ParameterDecorator;
  * Parameter decorator that injects the value associated with the given token,
  * or `undefined` if the token is not registered in the container.
  *
- * Allows referencing a token declared later in the file by using the
- * {@link tokenRef} helper function.
+ * This overload allows referencing a token declared later in the file by using
+ * the {@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
+ * Example:
  * ```ts
  * class Wizard {
  *   constructor(@Optional(tokenRef(() => Wand)) readonly wand: Wand | undefined) {}
@@ -874,12 +885,12 @@ declare function OptionalAll<Value>(token: Token<Value>): ParameterDecorator;
  * associated with the given token or an empty array if the token is not registered
  * in the container.
  *
- * Allows referencing a token declared later in the file by using the
- * {@link tokenRef} helper function.
+ * This overload allows referencing a token declared later in the file by using
+ * the {@link tokenRef} helper function.
  *
  * Throws an error if a circular dependency is detected.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   constructor(@OptionalAll(tokenRef(() => Wand)) readonly wands: Wand[]) {}
@@ -895,7 +906,7 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *
  * The scope set by this decorator can be overridden by explicit registration options, if provided.
  *
- * @example
+ * Example:
  * ```ts
  * @Scoped("Container")
  * class Wizard {}
@@ -909,8 +920,6 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *   { scope: "Container" },
  * );
  * ```
- *
- * @__NO_SIDE_EFFECTS__
  */
 declare function Scoped<This extends object>(scope: Scope): ClassDecorator<This>;
 
@@ -958,7 +967,7 @@ declare function injectAll<Value>(token: Token<Value>): Value[];
  * Compared to {@link inject}, `injectBy` accepts a `thisArg` argument
  * (e.g., the containing class instance) which is used to resolve circular dependencies.
  *
- * @example
+ * Example:
  * ```ts
  * class Wand {
  *   owner = inject(Wizard);
@@ -982,7 +991,7 @@ declare function injectBy<Instance extends object>(thisArg: any, Class: Construc
  * Compared to {@link inject}, `injectBy` accepts a `thisArg` argument
  * (e.g., the containing class instance) which is used to resolve circular dependencies.
  *
- * @example
+ * Example:
  * ```ts
  * class Wand {
  *   owner = inject(Wizard);
@@ -1011,7 +1020,7 @@ declare function assertInjectionContext(fn: Function | string): void;
 /**
  * Allows performing injections outside the normal injection context window.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   private injector = inject(Injector);
@@ -1021,7 +1030,7 @@ declare function assertInjectionContext(fn: Function | string): void;
  *
  *   getWand(): Wand {
  *     // An injection context does not exist here, but the
- *     // Injector instance retains and reuse the context
+ *     // Injector instance retains and reuses the context
  *     // that was present at the time of its injection
  *     return (this.wand ??= this.injector.inject(Wand));
  *   }
@@ -1088,7 +1097,7 @@ interface Injector {
 /**
  * Allows performing injections outside the normal injection context window.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   private injector = inject(Injector);
@@ -1098,7 +1107,7 @@ interface Injector {
  *
  *   getWand(): Wand {
  *     // An injection context does not exist here, but the
- *     // Injector instance retains and reuse the context
+ *     // Injector instance retains and reuses the context
  *     // that was present at the time of its injection
  *     return (this.wand ??= this.injector.inject(Wand));
  *   }

package/dist/cjs/index.js

@@ -57,7 +57,7 @@ function getTokenName(token) {
 }
 function getFullTokenName([token, name]) {
     const tokenName = token ? token.name || "<unnamed>" : "<undefined token>";
-    return name ? `${tokenName}["${name}"]` : tokenName;
+    return name !== undefined ? `${tokenName}["${name}"]` : tokenName;
 }
 function getCause(error) {
     if (!error) {
@@ -218,10 +218,9 @@ function injectBy(thisArg, token, name) {
 
 /**
  * Allows referencing a class declared later in the file by wrapping it
- * in a lazily evaluated function.
- *
- * @__NO_SIDE_EFFECTS__
- */ function classRef(Class) {
+ * into a lazily evaluated function.
+ */ // @__NO_SIDE_EFFECTS__
+function classRef(Class) {
     return {
         getRefClass: ()=>Class()
     };
@@ -545,8 +544,12 @@ class TokenRegistry {
         return registrations;
     }
     deleteAll() {
-        const tokens = Array.from(this.myRegistrations.keys());
-        const registrations = Array.from(this.myRegistrations.values()).flat();
+        const tokens = [
+            ...this.myRegistrations.keys()
+        ];
+        const registrations = [
+            ...this.myRegistrations.values()
+        ].flat();
         this.myRegistrations.clear();
         return [
             tokens,
@@ -564,7 +567,9 @@ class TokenRegistry {
                 registration.valueRef = undefined;
             }
         }
-        return Array.from(values);
+        return [
+            ...values
+        ];
     }
     getAllFromParent(token, name) {
         let registrations = this.myRegistrations.get(token) || this.myParent?.getAllFromParent(token, name);
@@ -662,7 +667,9 @@ function isDisposable(value) {
                 values.add(valueRef.current);
             }
         }
-        return Array.from(values);
+        return [
+            ...values
+        ];
     }
     resetRegistry() {
         this.checkDisposed();
@@ -673,7 +680,9 @@ function isDisposable(value) {
                 values.add(valueRef.current);
             }
         }
-        return Array.from(values);
+        return [
+            ...values
+        ];
     }
     isRegistered(token, name) {
         this.checkDisposed();
@@ -702,7 +711,9 @@ function isDisposable(value) {
                 values.add(valueRef.current);
             }
         }
-        return Array.from(values);
+        return [
+            ...values
+        ];
     }
     resolve(token, name) {
         this.checkDisposed();
@@ -728,13 +739,14 @@ function isDisposable(value) {
     }
     dispose() {
         if (this.myDisposed) {
-            return;
+            return [];
         }
+        this.myDisposed = true;
+        const promises = [];
         // Dispose children containers first
         for (const child of this.myChildren){
-            child.dispose();
+            promises.push(...child.dispose());
         }
-        this.myDisposed = true;
         this.myChildren.clear();
         this.myParent?.myChildren?.delete(this);
         const [, registrations] = this.myTokenRegistry.deleteAll();
@@ -751,11 +763,18 @@ function isDisposable(value) {
         }
         for (const value of allValues){
             if (isDisposable(value)) {
-                value.dispose();
+                try {
+                    promises.push(Promise.resolve(value.dispose()));
+                } catch (e) {
+                    promises.push(Promise.reject(e));
+                }
             }
         }
-        this.notifyDisposeHooks(Array.from(cacheValues));
+        this.notifyDisposeHooks([
+            ...cacheValues
+        ]);
         this.myHookRegistry.clear();
+        return promises;
     }
     registerClass(Class) {
         const metadata = getMetadata(Class);
@@ -1098,7 +1117,7 @@ function isDisposable(value) {
  * Class decorator that enables auto-registration of an unregistered class
  * when the class is first resolved from the container.
  *
- * @example
+ * Example:
  * ```ts
  * @AutoRegister()
  * class Wizard {}
@@ -1106,9 +1125,8 @@ function isDisposable(value) {
  * const wizard = container.resolve(Wizard);
  * container.isRegistered(Wizard); // => true
  * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function AutoRegister() {
+ */ // @__NO_SIDE_EFFECTS__
+function AutoRegister() {
     return function(Class) {
         const metadata = getMetadata(Class);
         metadata.autoRegister = true;
@@ -1122,7 +1140,7 @@ function isDisposable(value) {
  * This causes the container to immediately create and cache the instance of the class,
  * instead of deferring instantiation until the first resolution.
  *
- * @example
+ * Example:
  * ```ts
  * @EagerInstantiate()
  * class Wizard {}
@@ -1131,9 +1149,8 @@ function isDisposable(value) {
  * // is immediately created and cached by the container
  * container.register(Wizard);
  * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function EagerInstantiate() {
+ */ // @__NO_SIDE_EFFECTS__
+function EagerInstantiate() {
     return function(Class) {
         const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
@@ -1199,7 +1216,7 @@ function InjectAll(token) {
  * This allows the container to distinguish between multiple implementations
  * of the same interface or type during registration and injection.
  *
- * @example
+ * Example:
  * ```ts
  * @Named("dumbledore")
  * class Dumbledore implements Wizard {}
@@ -1208,9 +1225,8 @@ function InjectAll(token) {
  * container.register(IWizard, { useClass: Dumbledore });
  * const dumbledore = container.resolve(IWizard, "dumbledore");
  * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function Named(name) {
+ */ // @__NO_SIDE_EFFECTS__
+function Named(name) {
     check(name.trim(), "@Named qualifier must not be empty");
     return function(target, propertyKey, parameterIndex) {
         if (parameterIndex === undefined) {
@@ -1262,7 +1278,7 @@ function OptionalAll(token) {
  *
  * The scope set by this decorator can be overridden by explicit registration options, if provided.
  *
- * @example
+ * Example:
  * ```ts
  * @Scoped("Container")
  * class Wizard {}
@@ -1276,9 +1292,8 @@ function OptionalAll(token) {
  *   { scope: "Container" },
  * );
  * ```
- *
- * @__NO_SIDE_EFFECTS__
- */ function Scoped(scope) {
+ */ // @__NO_SIDE_EFFECTS__
+function Scoped(scope) {
     return function(Class) {
         const metadata = getMetadata(Class);
         const currentScope = metadata.scope;
@@ -1298,7 +1313,7 @@ function OptionalAll(token) {
 /**
  * Allows performing injections outside the normal injection context window.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   private injector = inject(Injector);
@@ -1308,13 +1323,13 @@ function OptionalAll(token) {
  *
  *   getWand(): Wand {
  *     // An injection context does not exist here, but the
- *     // Injector instance retains and reuse the context
+ *     // Injector instance retains and reuses the context
  *     // that was present at the time of its injection
  *     return (this.wand ??= this.injector.inject(Wand));
  *   }
  * }
  * ```
- */ const Injector = /*@__PURE__*/ build(()=>{
+ */ const Injector = /* @__PURE__ */ build(()=>{
     const context = ensureInjectionContext("Injector factory");
     const runInContext = (fn)=>{
         if (useInjectionContext()) {