@lppedd/di-wise-neo 0.5.3 → 0.7.0

package/README.md

@@ -3,7 +3,8 @@
 <p align="center">Lightweight, type-safe, flexible dependency injection library for TypeScript and JavaScript</p>
 <div align="center">
 
-[![test](https://img.shields.io/github/actions/workflow/status/lppedd/di-wise-neo/test.yml.svg?branch=main)](https://github.com/lppedd/di-wise-neo/actions/workflows/test.yml)
+[![build](https://img.shields.io/github/actions/workflow/status/lppedd/di-wise-neo/test.yml.svg?branch=main)](https://github.com/lppedd/di-wise-neo/actions/workflows/test.yml)
+[![coverage](https://img.shields.io/codecov/c/github/lppedd/di-wise-neo/main?token=R9XZFTQ0BA)](https://app.codecov.io/gh/lppedd/di-wise-neo/tree/main/src)
 [![npm](https://img.shields.io/npm/v/@lppedd/di-wise-neo?color=%23de1f1f&logo=npm)](https://www.npmjs.com/package/@lppedd/di-wise-neo)
 [![npm gzipped size](https://img.shields.io/bundlejs/size/@lppedd/di-wise-neo)](https://bundlejs.com/?q=@lppedd/di-wise-neo)
 [![license](https://img.shields.io/github/license/lppedd/di-wise-neo?color=blue)](https://github.com/lppedd/di-wise-neo/blob/main/LICENSE)
@@ -17,9 +18,8 @@
 > in part thanks to TypeScript's experimental decorators. Shout out to [@exuanbo](https://github.com/exuanbo)
 > for the strong foundations!
 
-## Table of Contents
+### Table of Contents
 
-- [Why yet another library](#why-yet-another-library)
 - [Installation](#installation)
 - [API reference](#api-reference)
 - [Ergonomics & Requirements](#ergonomics)
@@ -31,7 +31,7 @@
 - [Behavioral decorators](#behavioral-decorators)
 - [Testing support](#testing-support)
 
-## Why yet another library
+### Why yet another library
 
 I've been developing VS Code extensions for a while as part of my daily work.
 It's enjoyable work! However, extensions always reach that tipping point where
@@ -79,7 +79,7 @@ the use of ECMAScript Stage 3 decorators, which do not support decorating method
 So what's the right move? Forking the best pick and refactoring it to suite my
 production needs.
 
-## Installation
+### Installation
 
 ```sh
 npm i @lppedd/di-wise-neo
@@ -93,11 +93,11 @@ pnpm add @lppedd/di-wise-neo
 yarn add @lppedd/di-wise-neo
 ```
 
-## API reference
+### API reference
 
 You can find the complete API reference at [lppedd.github.io/di-wise-neo](https://lppedd.github.io/di-wise-neo)
 
-## Ergonomics
+### Ergonomics
 
 - Does **not** depend on other libraries
 - Does **not** use [reflect-metadata](https://www.npmjs.com/package/reflect-metadata) to drive decorators
@@ -281,7 +281,9 @@ The container will translate `TaskID` to `PID` before resolving the value.
 
 The primary way to perform dependency injection in **di-wise-neo** is through
 functions like `inject(T)`, `injectAll(T)`, `optional(T)`, and `optionalAll(T)`.
-This approach is recommended because it preserves full type safety.
+
+> [!TIP]
+> Using injection functions is recommended because it preserves type safety.
 
 ### Injection context
 
@@ -442,7 +444,7 @@ export class ExtensionContext {
 
 ## Behavioral decorators
 
-The library includes three behavioral decorators that influence how classes are registered in the container.
+The library includes four behavioral decorators that influence how classes are registered in the container.
 These decorators attach metadata to the class type, which is then interpreted by the container during registration.
 
 ### `@Scoped`
@@ -471,12 +473,39 @@ container.register(
 
 In this example, `ExtensionContext` will be registered with **Resolution** scope instead.
 
+### `@Named`
+
+Marks a class or injected dependency with a unique name (qualifier), allowing the container
+to distinguish between multiple implementations of the same type.
+
+```ts
+@Named("persistent")
+@Scoped(Scope.Container)
+export class PersistentSecretStorage implements SecretStorage {
+  /* ... */
+}
+
+// Register the class with Type<SecretStorage>.
+// The container will automatically qualify the registration with 'persistent'.
+container.register(ISecretStorage, { useClass: PersistentSecretStorage });
+
+// Inject the SecretStorage dependency by name
+export class ExtensionContext {
+  constructor(@Inject(ISecretStorage) @Named("persistent") readonly secretStorage: SecretStorage) {}
+
+  /* ... */
+}
+```
+
+The container will throw an error at registration time if the name is already taken by another registration.
+
 ### `@AutoRegister`
 
-Enables automatic registration of the decorated class if it has not been registered explicitly.
+Enables automatic registration of the decorated class when it is resolved,
+if it has not been registered beforehand.
 
 ```ts
-@AutoRegister
+@AutoRegister()
 export class ExtensionContext {
   /* ... */
 }
@@ -487,19 +516,20 @@ container.resolve(ExtensionContext);
 
 ### `@EagerInstantiate`
 
-Marks a class for eager instantiation when registered with **Container** scope.
+Sets the default class scope to **Container** and marks the class for eager instantiation
+upon registration.
 
 This causes the container to immediately create and cache the instance of the class
 at registration time, instead of deferring instantiation until the first resolution.
 
 ```ts
-@EagerInstantiate
-@Scoped(Scope.Container)
+@EagerInstantiate()
 export class ExtensionContext {
   /* ... */
 }
 
-// The container immediately creates and caches the instance
+// ExtensionContext is registered with Container scope,
+// and an instance is immediately created and cached by the container
 container.register(ExtensionContext);
 ```
 

package/dist/cjs/index.d.ts

@@ -62,22 +62,81 @@ declare function createType<T>(typeName: string): Type<T>;
  * Provides a class instance for a token via a class constructor.
  */
 interface ClassProvider<Instance extends object> {
+    /**
+     * The class to instantiate for the token.
+     */
     readonly useClass: Constructor<Instance>;
+    /**
+     * An optional name to qualify this provider.
+     * If specified, the token must be resolved using the same name.
+     *
+     * Equivalent to decorating the class with `@Named(...)`.
+     *
+     * @example
+     * ```ts
+     * export class ExtensionContext {
+     *   // Decorator-based injection
+     *   constructor(@Inject(ISecretStorage) @Named("persistent") secretStorage: SecretStorage) {}
+     *
+     *   // Function-based injection
+     *   constructor(secretStorage = inject(ISecretStorage, "persistent")) {}
+     * }
+     * ```
+     */
+    readonly name?: string;
 }
 /**
  * Provides a value for a token via a factory function.
- *
- * The factory function runs inside the injection context and can
- * thus access dependencies via {@link inject}-like functions.
  */
 interface FactoryProvider<Value> {
+    /**
+     * A function that produces the value at resolution time.
+     *
+     * The function runs inside the injection context and can
+     * access dependencies via {@link inject}-like helpers.
+     */
     readonly useFactory: (...args: []) => Value;
+    /**
+     * An optional name to qualify this provider.
+     * If specified, the token must be resolved using the same name.
+     *
+     * @example
+     * ```ts
+     * export class ExtensionContext {
+     *   // Decorator-based injection
+     *   constructor(@Inject(ISecretStorage) @Named("persistent") secretStorage: SecretStorage) {}
+     *
+     *   // Function-based injection
+     *   constructor(secretStorage = inject(ISecretStorage, "persistent")) {}
+     * }
+     * ```
+     */
+    readonly name?: string;
 }
 /**
  * Provides a static - already constructed - value for a token.
  */
 interface ValueProvider<T> {
+    /**
+     * The static value to associate with the token.
+     */
     readonly useValue: T;
+    /**
+     * An optional name to qualify this provider.
+     * If specified, the token must be resolved using the same name.
+     *
+     * @example
+     * ```ts
+     * export class ExtensionContext {
+     *   // Decorator-based injection
+     *   constructor(@Inject(ISecretStorage) @Named("persistent") secretStorage: SecretStorage) {}
+     *
+     *   // Function-based injection
+     *   constructor(secretStorage = inject(ISecretStorage, "persistent")) {}
+     * }
+     * ```
+     */
+    readonly name?: string;
 }
 /**
  * Aliases another registered token.
@@ -85,6 +144,9 @@ interface ValueProvider<T> {
  * Resolving this token will return the value of the aliased one.
  */
 interface ExistingProvider<Value> {
+    /**
+     * The existing token to alias.
+     */
     readonly useExisting: Token<Value>;
 }
 /**
@@ -212,77 +274,33 @@ interface Container {
     /**
      * Returns whether the token is registered in this container or in parent containers, if any.
      */
-    isRegistered(token: Token): boolean;
-    /**
-     * Registers a concrete class, where the class acts as its own token.
-     *
-     * Tokens provided via the {@link Injectable} decorator applied to the class
-     * are also registered as aliases.
-     *
-     * The default registration scope is determined by the {@link Scoped} decorator,
-     * if present.
-     */
-    registerClass<Instance extends object>(Class: Constructor<Instance>): void;
-    /**
-     * Registers a concrete class with a token.
-     *
-     * The default registration scope is determined by the {@link Scoped} decorator
-     * applied to the class, if present, but it can be overridden by passing explicit
-     * registration options.
-     */
-    registerClass<Instance extends object, ProvidedInstance extends Instance>(token: Token<Instance>, Class: Constructor<ProvidedInstance>, options?: RegistrationOptions): void;
-    /**
-     * Registers a token whose value is produced by a factory function.
-     *
-     * The factory function runs inside the injection context and can
-     * thus access dependencies via {@link inject}-like functions.
-     */
-    registerFactory<Value, ProvidedValue extends Value>(token: Token<Value>, factory: (...args: []) => ProvidedValue, options?: RegistrationOptions): void;
-    /**
-     * Registers a token with a fixed value.
-     *
-     * The provided value is returned as-is when the token is resolved (scopes do not apply).
-     */
-    registerValue<Value, ProvidedValue extends Value>(token: Token<Value>, value: ProvidedValue): void;
-    /**
-     * Registers one or more tokens as aliases for a target token.
-     *
-     * When an alias is resolved, the target token is resolved instead.
-     */
-    registerAlias<Value, ProvidedValue extends Value>(targetToken: Token<ProvidedValue>, aliasTokens: Tokens<Value>): void;
+    isRegistered(token: Token, name?: string): boolean;
     /**
      * Registers a {@link ClassProvider}, using the class itself as its token.
      *
      * Tokens provided via the {@link Injectable} decorator applied to the class
      * are also registered as aliases.
      *
-     * The scope is determined by the {@link Scoped} decorator, if present.
-     *
-     * @see registerClass
+     * The scope is determined by the {@link Scoped} decorator - if present -
+     * or by the {@link ContainerOptions.defaultScope} value.
      */
     register<Instance extends object>(Class: Constructor<Instance>): Container;
     /**
      * Registers a {@link ClassProvider} with a token.
      *
      * The default registration scope is determined by the {@link Scoped} decorator
-     * applied to the provided class, if present, but it can be overridden by
-     * passing explicit registration options.
-     *
-     * @see registerClass
+     * applied to the provided class - if present - or by the {@link ContainerOptions.defaultScope}
+     * value, but it can be overridden by passing explicit registration options.
      */
     register<Instance extends object, ProviderInstance extends Instance>(token: Token<Instance>, provider: ClassProvider<ProviderInstance>, options?: RegistrationOptions): Container;
     /**
      * Registers a {@link FactoryProvider} with a token.
-     *
-     * @see registerFactory
      */
     register<Value, ProviderValue extends Value>(token: Token<Value>, provider: FactoryProvider<ProviderValue>, options?: RegistrationOptions): Container;
     /**
      * Registers an {@link ExistingProvider} with a token.
      *
      * The token will alias the one set in `useExisting`.
-     *
-     * @see registerAlias
      */
     register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ExistingProvider<ProviderValue>): Container;
     /**
@@ -290,8 +308,6 @@ interface Container {
      *
      * Values provided via `useValue` are never cached (scopes do not apply)
      * and are simply returned as-is.
-     *
-     * @see registerValue
      */
     register<Value, ProviderValue extends Value>(token: Token<Value>, provider: ValueProvider<ProviderValue>): Container;
     /**
@@ -302,7 +318,7 @@ interface Container {
      *
      * Note that only this container is affected. Parent containers, if any, remain unchanged.
      */
-    unregister<Value>(token: Token<Value>): Value[];
+    unregister<Value>(token: Token<Value>, name?: string): Value[];
     /**
      * Resolves the given class to the instance associated with it.
      *
@@ -328,9 +344,10 @@ interface Container {
      * If the class is registered with _container_ scope, the resolved instance is cached
      * in the container's internal registry.
      */
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: false): Instance;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional: true): Instance | undefined;
-    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: boolean): Instance | undefined;
+    resolve<Instance extends object>(Class: Constructor<Instance>, name?: string): Instance;
+    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: false, name?: string): Instance;
+    resolve<Instance extends object>(Class: Constructor<Instance>, optional: true, name?: string): Instance | undefined;
+    resolve<Instance extends object>(Class: Constructor<Instance>, optional?: boolean, name?: string): Instance | undefined;
     /**
      * Resolves the given token to the value associated with it.
      *
@@ -349,9 +366,10 @@ interface Container {
      * If the token is registered with _container_ scope, the resolved value is cached
      * in the container's internal registry.
      */
-    resolve<Value>(token: Token<Value>, optional?: false): Value;
-    resolve<Value>(token: Token<Value>, optional: true): Value | undefined;
-    resolve<Value>(token: Token<Value>, optional?: boolean): Value | undefined;
+    resolve<Value>(token: Token<Value>, name?: string): Value;
+    resolve<Value>(token: Token<Value>, optional?: false, name?: string): Value;
+    resolve<Value>(token: Token<Value>, optional: true, name?: string): Value | undefined;
+    resolve<Value>(token: Token<Value>, optional?: boolean, name?: string): Value | undefined;
     /**
      * Resolves the given class to all instances provided by the registrations associated with it.
      *
@@ -422,7 +440,7 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @example
  * ```ts
- * @AutoRegister
+ * @AutoRegister()
  * class Wizard {}
  *
  * const wizard = container.resolve(Wizard);
@@ -431,28 +449,28 @@ declare function createContainer(options?: Partial<ContainerOptions>): Container
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function AutoRegister<Ctor extends Constructor<any>>(Class: Ctor): void;
+declare function AutoRegister(): ClassDecorator;
 
 /**
- * Class decorator that enables eager instantiation of a class when it is registered
- * in the container with `Scope.Container`.
+ * Class decorator that sets the class scope to **Container** and enables
+ * eager instantiation when the class is registered in the container.
  *
  * This causes the container to immediately create and cache the instance of the class,
  * instead of deferring instantiation until the first resolution.
  *
  * @example
  * ```ts
- * @EagerInstantiate
- * @Scoped(Scope.Container)
+ * @EagerInstantiate()
  * class Wizard {}
  *
- * // A Wizard instance is immediately created and cached by the container
- * const wizard = container.register(Wizard);
+ * // Wizard is registered with Container scope, and an instance
+ * // is immediately created and cached by the container
+ * container.register(Wizard);
  * ```
  *
  * @__NO_SIDE_EFFECTS__
  */
-declare function EagerInstantiate<Ctor extends Constructor<any>>(Class: Ctor): void;
+declare function EagerInstantiate(): ClassDecorator;
 
 interface TokensRef<Value = any> {
     readonly getRefTokens: () => Set<Token<Value>>;
@@ -568,6 +586,26 @@ declare function InjectAll<Value>(token: Token<Value>): ParameterDecorator;
  */
 declare function InjectAll<Value>(tokens: TokenRef<Value>): ParameterDecorator;
 
+/**
+ * Qualifies a class or an injected parameter with a unique name.
+ *
+ * This allows the container to distinguish between multiple implementations
+ * of the same interface or type during registration and injection.
+ *
+ * @example
+ * ```ts
+ * @Named("dumbledore")
+ * class Dumbledore implements Wizard {}
+ *
+ * // Register Dumbledore with Type<Wizard>
+ * container.register(IWizard, { useClass: Dumbledore });
+ * const dumbledore = container.resolve(IWizard, "dumbledore");
+ * ```
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+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.
@@ -656,13 +694,13 @@ declare function Scoped(scope: Scope): ClassDecorator;
  *
  * Throws an error if the class is not registered in the container.
  */
-declare function inject<Instance extends object>(Class: Constructor<Instance>): Instance;
+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.
  */
-declare function inject<Value>(token: Token<Value>): Value;
+declare function inject<Value>(token: Token<Value>, name?: string): Value;
 /**
  * Injects the instance associated with the given class.
  *
@@ -684,8 +722,9 @@ declare function inject<Value>(token: Token<Value>): Value;
  *
  * @param thisArg - The containing instance, used to help resolve circular dependencies.
  * @param Class - The class to resolve.
+ * @param name - The name qualifier of the class to resolve.
  */
-declare function injectBy<Instance extends object>(thisArg: any, Class: Constructor<Instance>): Instance;
+declare function injectBy<Instance extends object>(thisArg: any, Class: Constructor<Instance>, name?: string): Instance;
 /**
  * Injects the value associated with the given token.
  *
@@ -707,8 +746,9 @@ declare function injectBy<Instance extends object>(thisArg: any, Class: Construc
  *
  * @param thisArg - The containing instance, used to help resolve circular dependencies.
  * @param token - The token to resolve.
+ * @param name - The name qualifier of the token to resolve.
  */
-declare function injectBy<Value>(thisArg: any, token: Token<Value>): Value;
+declare function injectBy<Value>(thisArg: any, token: Token<Value>, name?: string): Value;
 
 /**
  * Injects all instances provided by the registrations associated with the given class.
@@ -865,5 +905,5 @@ interface Middleware {
  */
 declare function applyMiddleware(container: Container, middlewares: Middleware[]): Container;
 
-export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy, setClassIdentityMapping };
+export { AutoRegister, EagerInstantiate, Inject, InjectAll, Injectable, Injector, Named, Optional, OptionalAll, Scope, Scoped, applyMiddleware, build, createContainer, createType, forwardRef, inject, injectAll, injectBy, setClassIdentityMapping };
 export type { ClassProvider, Constructor, Container, ContainerOptions, ExistingProvider, FactoryProvider, Middleware, MiddlewareComposer, Provider, RegistrationOptions, Token, TokenRef, Tokens, TokensRef, Type, ValueProvider };