@lppedd/di-wise-neo 0.18.1 → 0.20.0

package/dist/es/index.d.mts

@@ -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", {
@@ -130,22 +130,18 @@ interface ClassRef<Instance extends object> {
     readonly getRefClass: () => Constructor<Instance>;
 }
 interface TokenRef<Value> {
-    readonly getRefTokens: () => Set<Token<Value>>;
+    readonly getRefToken: () => Token<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>;
 /**
- * Allows referencing one or multiple tokens declared later in the file by wrapping them
+ * Allows referencing a token declared later in the file by wrapping it
  * into a lazily evaluated function.
- *
- * @__NO_SIDE_EFFECTS__
  */
-declare function tokenRef<Value>(token: () => Token<Value> | Tokens<Value>): TokenRef<Value>;
+declare function tokenRef<Value>(token: () => Token<Value>): TokenRef<Value>;
 
 /**
  * Provides a class instance for a token via a class constructor.
@@ -161,7 +157,7 @@ interface ClassProvider<Instance extends object> {
      *
      * Equivalent to decorating the class with `@Named(...)`.
      *
-     * @example
+     * Example:
      * ```ts
      * export class ExtensionContext {
      *   // Decorator-based injection
@@ -189,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
@@ -214,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
@@ -236,7 +232,7 @@ interface ExistingProvider<Value> {
     /**
      * The existing token to alias, with an optional name qualifier.
      *
-     * @example
+     * Example:
      * ```ts
      * container.register(ISecretStorage, {
      *   useExisting: PersistentSecretStorage,
@@ -253,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
@@ -352,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.
@@ -646,7 +642,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 {}
@@ -654,8 +650,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>;
 
@@ -666,7 +660,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 {}
@@ -675,8 +669,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>;
 
@@ -701,15 +693,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) {}
@@ -721,40 +713,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>;
-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.
+ * 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>;
@@ -781,14 +789,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[]) {}
@@ -805,7 +813,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 {}
@@ -814,8 +822,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;
 
@@ -839,13 +845,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) {}
@@ -877,12 +883,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[]) {}
@@ -898,7 +904,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 {}
@@ -912,8 +918,6 @@ declare function OptionalAll<Value>(tokens: TokenRef<Value>): ParameterDecorator
  *   { scope: "Container" },
  * );
  * ```
- *
- * @__NO_SIDE_EFFECTS__
  */
 declare function Scoped<This extends object>(scope: Scope): ClassDecorator<This>;
 
@@ -961,7 +965,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);
@@ -985,7 +989,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);
@@ -1014,7 +1018,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);
@@ -1024,7 +1028,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));
  *   }
@@ -1091,7 +1095,7 @@ interface Injector {
 /**
  * Allows performing injections outside the normal injection context window.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   private injector = inject(Injector);
@@ -1101,7 +1105,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/es/index.mjs

@@ -31,9 +31,8 @@ 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([
-        token,
+        dependency.tokenRef.getRefToken(),
         dependency.name
     ]);
     const msg = tag(`failed to resolve dependency for ${location}(parameter #${dependency.index}: ${tokenName})`);
@@ -217,21 +216,21 @@ 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()
     };
 }
-/**
- * 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) {
+// @__NO_SIDE_EFFECTS__
+function tokenRef(token) {
     return {
+        getRefToken: ()=>{
+            const tokenOrTokens = token();
+            check(!Array.isArray(tokenOrTokens), "internal error: single token expected");
+            return tokenOrTokens;
+        },
         getRefTokens: ()=>{
             // Normalize the single token here so that we don't have to do it at every getRefTokens call site
             const tokenOrTokens = token();
@@ -248,7 +247,7 @@ function isClassRef(value) {
 }
 // @internal
 function isTokenRef(value) {
-    return value != null && typeof value === "object" && typeof value.getRefTokens === "function";
+    return value != null && typeof value === "object" && typeof value.getRefToken === "function";
 }
 
 // @internal
@@ -259,6 +258,10 @@ class Metadata {
             methods: new Map()
         };
         this.tokenRef = {
+            // prettier-ignore
+            getRefToken: ()=>{
+                check(false, "internal error: unexpected call");
+            },
             getRefTokens: ()=>new Set()
         };
         this.provider = {
@@ -1053,7 +1056,7 @@ function isDisposable(value) {
     }
     // Call context: decorator-based injection
     resolveDependency(dependency, instance) {
-        const [token] = dependency.tokenRef.getRefTokens();
+        const token = dependency.tokenRef.getRefToken();
         check(token, `token passed to @${dependency.appliedBy} was undefined (possible circular imports)`);
         const name = dependency.name;
         switch(dependency.appliedBy){
@@ -1092,7 +1095,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 {}
@@ -1100,9 +1103,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;
@@ -1116,7 +1118,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 {}
@@ -1125,9 +1127,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;
@@ -1161,10 +1162,11 @@ function Injectable(...args) {
         const metadata = getMetadata(Class);
         const arg0 = args[0];
         const ref = isTokenRef(arg0) ? arg0 : tokenRef(()=>args);
-        const existingTokensRef = metadata.tokenRef;
+        const currentRef = metadata.tokenRef;
         metadata.tokenRef = {
+            getRefToken: ()=>currentRef.getRefToken(),
             getRefTokens: ()=>{
-                const existingTokens = existingTokensRef.getRefTokens();
+                const existingTokens = currentRef.getRefTokens();
                 for (const token of ref.getRefTokens()){
                     existingTokens.add(token);
                 }
@@ -1192,7 +1194,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 {}
@@ -1201,9 +1203,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) {
@@ -1255,7 +1256,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 {}
@@ -1269,9 +1270,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;
@@ -1291,7 +1291,7 @@ function OptionalAll(token) {
 /**
  * Allows performing injections outside the normal injection context window.
  *
- * @example
+ * Example:
  * ```ts
  * class Wizard {
  *   private injector = inject(Injector);
@@ -1301,13 +1301,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()) {