@adimm/x-injection 0.3.2 → 0.5.0

package/dist/index.d.ts

@@ -3,8 +3,6 @@ import { Class, Except } from 'type-fest';
 
 /** The identifier of the `GlobalAppModule`. */
 declare const GLOBAL_APP_MODULE_ID = "GlobalAppModule";
-/** The default {@link IProviderModule.identifier}. */
-declare const ANONYMOUS_MODULE_DEFAULT_ID = "AnonymousModule";
 
 declare enum InjectionScope {
     /** When the service is resolved, the same cached resolved value will be used. */
@@ -119,9 +117,7 @@ declare class ProviderModuleUtils {
      * @param defaultScope Optionally provide the default {@link InjectionScope} to use when applicable.
      * @returns `true` when the {@link provider} has been bound otherwhise `false`.
      */
-    bindToContainer<T>(provider: ProviderToken<T>, defaultScope: InjectionScope): boolean;
-    /** Low-level method which does exactly what {@link bindToContainer} does, however accepts a list of {@link providers}.  */
-    bindManyToContainer(providers: ProviderToken[], defaultScope: InjectionScope): void;
+    bindToContainer<T>(provider: DependencyProvider<T>, defaultScope: InjectionScope): boolean;
     private bindSelfTokenToContainer;
     private bindClassTokenToContainer;
     private bindValueTokenToContainer;
@@ -140,8 +136,6 @@ interface IProviderModuleNaked extends IProviderModule {
     readonly isAppModule: boolean;
     /** The low-level `InversifyJS` {@link https://inversify.io/docs/api/container/ | container} instance. */
     readonly container: Container;
-    /** Instance of the {@link ProviderModuleUtils}. */
-    readonly moduleUtils: ProviderModuleUtils;
     /** The default injection scope of this module. */
     readonly defaultScope: {
         /** Scope from `xInjection` {@link InjectionScope} enum. */
@@ -149,14 +143,31 @@ interface IProviderModuleNaked extends IProviderModule {
         /** Scope from `InversifyJS` {@link BindingScope} string union. */
         inversify: BindingScope;
     };
+    /** Instance of the {@link ProviderModuleUtils}. */
+    readonly moduleUtils: ProviderModuleUtils;
+    /** The {@link DependencyProvider | providers} resolved by this module. */
+    readonly providers: DependencyProvider[];
+    /**
+     * The imported {@link DependencyProvider | providers} resolved by this module.
+     *
+     * _It is a `dictionary` where the key is the {@link IProviderModule | module} and the value an_
+     * _array containing the imported dependencies from that module_
+     */
+    readonly importedProviders: Map<IProviderModuleNaked, DependencyProvider[]>;
+    /** What is exported from this module. */
+    readonly exports: StaticExports;
+    /** What is exported into this module. */
+    readonly imports: IProviderModuleNaked[];
     /** The module dynamic exports method. */
     readonly dynamicExports: DynamicExports | undefined;
     /** The registered `callback` which will be invoked when the internal initialization process has been completed. */
     readonly onReady: ProviderModuleOptions['onReady'];
     /** The registered `callback` which will be invoked when the {@link _dispose} method is invoked. */
     readonly onDispose: ProviderModuleOptions['onDispose'];
+    /** Can be used to override all the _imported_ providers _before_ the binding process. */
+    readonly importedProvidersMap: ProviderModuleOptionsInternal['importedProvidersMap'];
     /** It'll _completely_ re-init the `module` with the provided {@link LazyInitOptions | options}. */
-    _lazyInit(options: LazyInitOptions): void;
+    _lazyInit(options: LazyInitOptions): IProviderModule;
     /** Can be used to get the list of all the imported modules of this module. */
     _getImportedModules(): IProviderModuleNaked[];
     /** Can be used to get the list of all the providers of this module. */
@@ -319,74 +330,9 @@ interface IProviderModuleNaked extends IProviderModule {
 }
 type LazyInitOptions = Except<ProviderModuleOptions & ProviderModuleOptionsInternal, 'identifier' | 'isAppModule'>;
 
-interface IProviderModule {
-    /** The module unique ID. */
-    readonly identifier: symbol;
-    readonly isDisposed: boolean;
-    /**
-     * Can be used to retrieve a resolved `dependency` from the module container.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param isOptional When set to `false` _(default)_ an exception will be thrown when the {@link provider} isn't bound.
-     * @returns Either the {@link T | dependency} or `undefined` if {@link isOptional} is set to `true`.
-     */
-    get<T>(provider: ProviderToken<T>, isOptional?: boolean): T;
-    /**
-     * Can be used to retrieve many resolved `dependencies` from the module container at once.
-     *
-     * @param deps Either one or more {@link ProviderToken}.
-     * @returns Tuple containing the {@link D | dependencies}.
-     *
-     * @example
-     * ```ts
-     * // When ProviderTokens are supplied, TS auto-inference works as expected.
-     * // `car` will infer the `Car` type, `engine` the `Engine` type and `dashboard` the `Dashboard` type.
-     * const [car, engine, dashboard] = AppModule.getMany(
-     *   Car,
-     *   Engine,
-     *   { provider: Dashboard, isOptional: true }
-     * );
-     *
-     * // When auto-inference is not possible, you can manually cast the types.
-     * const [configService, userService] = AppModule.getMany<[typeof ConfigService, typeof UserService]>('CONFIG_SERVICE', UserService);
-     * // Now the `configService` is of type `ConfigService` and the `userService` is of type `UserService`.
-     * ```
-     */
-    getMany<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>(...deps: D | unknown[]): ProviderModuleGetManySignature<D>;
-    /**
-     * Adds an activation handler for the {@link provider}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#onactivation} for more details.
-     */
-    onActivationEvent<T>(provider: ProviderToken<T>, cb: BindingActivation<T>): void;
-    /**
-     * Adds a deactivation handler for the {@link provider}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#ondeactivation} for more details.
-     */
-    onDeactivationEvent<T>(provider: ProviderToken<T>, cb: BindingDeactivation<T>): void;
-    /**
-     * Casts the current module type to the {@link IProviderModuleNaked} type.
-     *
-     * **Internally used and for testing purposes!**
-     */
-    toNaked(): IProviderModuleNaked;
-    /** Returns the {@link IProviderModule.identifier} `symbol` description. */
-    toString(): string;
-}
-type ProviderModuleGetManySignature<Tokens extends (ProviderModuleGetManyParam<any> | ProviderToken)[]> = {
-    [K in keyof Tokens]: Tokens[K] extends ProviderModuleGetManyParam<infer U> ? U : Tokens[K] extends ProviderToken<infer T> ? T : Tokens[K] extends ProviderIdentifier<infer I> ? I : never;
-};
-type ProviderModuleGetManyParam<T> = {
-    /** The {@link ProviderToken}. */
-    provider: ProviderToken<T>;
-    /** When set to `false` _(default)_ an exception will be thrown when the {@link ProviderModuleGetManyParam.provider | provider} isn't bound. */
-    isOptional?: boolean;
-};
-
 interface ProviderModuleOptions {
     /** The module unique ID. */
-    identifier?: symbol;
+    identifier: symbol;
     /** The list of imported {@link IProviderModule | modules} that export the {@link Provider | providers} which are required in this module. */
     imports?: IProviderModule[];
     /** The {@link DependencyProvider | providers} that will be instantiated by the container and that may be shared at least across this module. */
@@ -469,8 +415,17 @@ interface ProviderModuleOptions {
 }
 interface ProviderModuleOptionsInternal {
     isAppModule?: boolean;
+    isDisposed?: boolean;
     /** Can be used to manually provide a {@link Container} instance. */
     container?: () => Container;
+    /** Can be used to override all the _imported_ providers _before_ the binding process. */
+    importedProvidersMap?: (
+    /** The current imported {@link DependencyProvider | provider} altered to use the module from where was imported for resolution. */
+    factorizedProvider: DependencyProvider<any>, 
+    /** The current imported {@link DependencyProvider | provider}. */
+    provider: DependencyProvider<any>, 
+    /** The {@link IProviderModule | module} from where the {@link DependencyProvider | provider} originated. */
+    module: IProviderModule) => DependencyProvider<any>;
 }
 type StaticExports = (ProviderToken | IProviderModule)[];
 type DynamicExports = (
@@ -479,6 +434,93 @@ importerModule: IProviderModule,
 /** The {@link ProviderModuleOptions.exports | exports} array of this module. */
 moduleExports: StaticExports) => StaticExports;
 
+interface IProviderModule {
+    /** The module unique ID. */
+    readonly identifier: symbol;
+    readonly isDisposed: boolean;
+    /**
+     * Can be used to retrieve a resolved `dependency` from the module container.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param isOptional When set to `false` _(default)_ an exception will be thrown when the {@link provider} isn't bound.
+     * @returns Either the {@link T | dependency} or `undefined` if {@link isOptional} is set to `true`.
+     */
+    get<T>(provider: ProviderToken<T>, isOptional?: boolean): T;
+    /**
+     * Can be used to retrieve many resolved `dependencies` from the module container at once.
+     *
+     * @param deps Either one or more {@link ProviderToken}.
+     * @returns Tuple containing the {@link D | dependencies}.
+     *
+     * @example
+     * ```ts
+     * // When ProviderTokens are supplied, TS auto-inference works as expected.
+     * // `car` will infer the `Car` type, `engine` the `Engine` type and `dashboard` the `Dashboard` type.
+     * const [car, engine, dashboard] = AppModule.getMany(
+     *   Car,
+     *   Engine,
+     *   { provider: Dashboard, isOptional: true }
+     * );
+     *
+     * // When auto-inference is not possible, you can manually cast the types.
+     * const [configService, userService] = AppModule.getMany<[typeof ConfigService, typeof UserService]>('CONFIG_SERVICE', UserService);
+     * // Now the `configService` is of type `ConfigService` and the `userService` is of type `UserService`.
+     * ```
+     */
+    getMany<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>(...deps: D | unknown[]): ProviderModuleGetManySignature<D>;
+    /**
+     * Adds an activation handler for the {@link provider}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#onactivation} for more details.
+     */
+    onActivationEvent<T>(provider: ProviderToken<T>, cb: BindingActivation<T>): void;
+    /**
+     * Adds a deactivation handler for the {@link provider}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#ondeactivation} for more details.
+     */
+    onDeactivationEvent<T>(provider: ProviderToken<T>, cb: BindingDeactivation<T>): void;
+    /**
+     * Casts the current module type to the {@link IProviderModuleNaked} type.
+     *
+     * **Internally used and for testing purposes!**
+     */
+    toNaked(): IProviderModuleNaked;
+    /**
+     * Can be used to create a new instance of the current {@link IProviderModule | module}.
+     *
+     * **Note:** _All the providers will be registered again within the new module!_
+     * _And also the new module will still refrain values by reference to its parent module because of_
+     * _JS limitation in deeply/truly cloning an instance._
+     *
+     * @param options See {@link CloneParams}.
+     */
+    clone(options?: CloneParams): IProviderModule;
+    /** Returns the {@link IProviderModule.identifier} `symbol` description. */
+    toString(): string;
+}
+type ProviderModuleGetManySignature<Tokens extends (ProviderModuleGetManyParam<any> | ProviderToken)[]> = {
+    [K in keyof Tokens]: Tokens[K] extends ProviderModuleGetManyParam<infer U> ? U : Tokens[K] extends ProviderToken<infer T> ? T : Tokens[K] extends ProviderIdentifier<infer I> ? I : never;
+};
+type ProviderModuleGetManyParam<T> = {
+    /** The {@link ProviderToken}. */
+    provider: ProviderToken<T>;
+    /** When set to `false` _(default)_ an exception will be thrown when the {@link ProviderModuleGetManyParam.provider | provider} isn't bound. */
+    isOptional?: boolean;
+};
+interface CloneParams {
+    /** Can be used to override all the providers _before_ the binding process. */
+    providersMap?: (
+    /** The current {@link DependencyProvider | provider}. */
+    provider: DependencyProvider<any>, 
+    /** The {@link IProviderModule | module} from where the {@link DependencyProvider | provider} originated. */
+    module: IProviderModule, 
+    /** Flag indicating if the {@link provider} has been imported from the {@link module}. */
+    isImported: boolean) => DependencyProvider<any>;
+    /** Can be used to override all the _imported_ providers _before_ the binding process. */
+    importedProvidersMap?: ProviderModuleOptionsInternal['importedProvidersMap'];
+}
+
 interface IAppModule extends IProviderModule {
     /** Must be invoked _(only once during the application lifecycle)_ in order to provide the {@link options} to the module. */
     register<AsNaked extends boolean = false>(options: AppModuleOptions): AsNaked extends false ? IAppModule : IAppModule & IProviderModuleNaked;
@@ -524,6 +566,7 @@ declare class XInjectionProviderModuleError extends Error {
     constructor(module: IProviderModule, message: string);
 }
 
+/** Exception which indicates an invokation of a disposed module.  */
 declare class XInjectionProviderModuleDisposedError extends XInjectionProviderModuleError {
     name: string;
     constructor(module: IProviderModule);
@@ -540,6 +583,12 @@ declare class XInjectionDynamicExportsOutOfRange extends XInjectionProviderModul
     constructor(module: IProviderModule);
 }
 
+/** Exception which indicates that a module has been initialized without an `identifier`.  */
+declare class XInjectionProviderModuleMissingIdentifierError extends XInjectionProviderModuleError {
+    name: string;
+    constructor(module: IProviderModule);
+}
+
 declare function injectionScopeToBindingScope(injectionScope: InjectionScope): BindingScope;
 declare function bindingScopeToInjectionScope(bindingScope: BindingScope): InjectionScope;
 
@@ -550,6 +599,7 @@ declare namespace ProviderTokenHelpers {
     function isProviderIdentifier<T = any>(value: any): value is ProviderIdentifier<T>;
     function toServiceIdentifier<T = any>(provider: ProviderToken<T>): ServiceIdentifier<T>;
     function toServiceIdentifiers(providers: ProviderToken[]): ServiceIdentifier<unknown>[];
+    function toDependencyProviderWithOptions<T extends DependencyProvider<any>>(original: T, override?: Partial<T>): T;
     /**
      * The priority order is as follows:
      * 1. From the `ProviderToken.scope`
@@ -574,6 +624,8 @@ declare function isPlainObject(o: any): o is object;
 
 declare function isClass(v: any): boolean;
 
+declare function isFunction(v: any): boolean;
+
 declare function isClassOrFunction(value: any): value is Function | Class<any>;
 
 /**
@@ -594,16 +646,19 @@ declare const GlobalContainer: Container;
  * import { ProviderModule } from '@adimm/x-injection';
  *
  * const EngineModule = new ProviderModule({
+ *   identifier: Symbol('EngineModule'),
  *   providers: [EngineService],
  *   exports: [EngineService]
  * });
  *
  * const DashboardModule = new ProviderModule({
+ *   identifier: Symbol('DashboardModule'),
  *   providers: [DashboardService],
  *   exports: [DashboardService]
  * });
  *
  * const CarModule = new ProviderModule({
+ *   identifier: Symbol('CarModule'),
  *   imports: [EngineModule, DashboardModule],
  *   providers: [CarService],
  *   exports: [CarService]
@@ -611,6 +666,7 @@ declare const GlobalContainer: Container;
  *
  * // Run-time class replacement:
  * const RedCarModule = new ProviderModule({
+ *   identifier: Symbol('RedCarModule'),
  *   imports: [CarModule],
  *   providers: [
  *     {
@@ -622,6 +678,7 @@ declare const GlobalContainer: Container;
  *
  * // Run-time factory example:
  * const BlackCarModule = new ProviderModule({
+ *   identifier: Symbol('BlackCarModule'),
  *   imports: [CarModule],
  *   providers: [
  *     {
@@ -639,17 +696,19 @@ declare const GlobalContainer: Container;
  */
 declare class ProviderModule implements IProviderModule {
     readonly identifier: symbol;
-    readonly isDisposed = false;
+    readonly isDisposed: boolean;
     protected readonly isAppModule: boolean;
     protected readonly container: Container;
     protected readonly defaultScope: IProviderModuleNaked['defaultScope'];
     protected readonly dynamicExports: IProviderModuleNaked['dynamicExports'];
     protected readonly onReady: IProviderModuleNaked['onReady'];
     protected readonly onDispose: IProviderModuleNaked['onDispose'];
+    protected readonly importedProvidersMap: IProviderModuleNaked['importedProvidersMap'];
     protected readonly moduleUtils: IProviderModuleNaked['moduleUtils'];
-    private readonly providers;
-    private readonly exports;
-    private readonly imports;
+    protected readonly imports: IProviderModuleNaked['imports'];
+    protected readonly providers: IProviderModuleNaked['providers'];
+    protected readonly importedProviders: IProviderModuleNaked['importedProviders'];
+    protected readonly exports: IProviderModuleNaked['exports'];
     private readonly registeredBindingSideEffects;
     constructor({ identifier, imports, providers, exports, defaultScope, dynamicExports, onReady, onDispose, ..._internalParams }: ProviderModuleOptions);
     get<T>(provider: ProviderToken<T>, isOptional?: boolean): T;
@@ -657,7 +716,9 @@ declare class ProviderModule implements IProviderModule {
     onActivationEvent<T>(provider: ProviderToken<T>, cb: BindingActivation<T>): void;
     onDeactivationEvent<T>(provider: ProviderToken<T>, cb: BindingDeactivation<T>): void;
     toNaked(): IProviderModuleNaked;
+    clone(options?: CloneParams): IProviderModule;
     toString(): string;
+    private setIdentifier;
     private prepareContainer;
     private injectImportedModules;
     private injectProviders;
@@ -677,7 +738,7 @@ declare class ProviderModule implements IProviderModule {
      *
      * See {@link IProviderModuleNaked._lazyInit}.
      */
-    protected _lazyInit({ imports, providers, exports, defaultScope, dynamicExports, onReady, onDispose, ..._internalParams }: LazyInitOptions): void;
+    protected _lazyInit({ imports, providers, exports, defaultScope, dynamicExports, onReady, onDispose, ..._internalParams }: LazyInitOptions): IProviderModule;
     /**
      * **Publicly visible when the instance is casted to {@link IProviderModuleNaked}.**
      *
@@ -838,4 +899,4 @@ declare class GlobalAppModule extends ProviderModule implements IAppModule {
  */
 declare const AppModule: GlobalAppModule;
 
-export { ANONYMOUS_MODULE_DEFAULT_ID, AppModule, type AppModuleOptions, type DependencyProvider, type DynamicExports, GLOBAL_APP_MODULE_ID, GlobalAppModule, GlobalContainer, type IAppModule, type IProviderModule, type IProviderModuleNaked, Inject, InjectFromBase, Injectable, InjectionScope, type LazyInitOptions, MultiInject, Named, type OnEvent, Optional, PostConstruct, PreDestroy, type ProviderClassToken, type ProviderFactoryToken, type ProviderIdentifier, ProviderModule, type ProviderModuleGetManyParam, type ProviderModuleGetManySignature, ProviderModuleHelpers, type ProviderModuleOptions, type ProviderModuleOptionsInternal, type ProviderOptions, type ProviderScopeOption, type ProviderToken, ProviderTokenHelpers, type ProviderValueToken, type StaticExports, Tagged, Unmanaged, XInjectionDynamicExportsOutOfRange, XInjectionError, XInjectionProviderModuleDisposedError, XInjectionProviderModuleError, bindingScopeToInjectionScope, injectionScopeToBindingScope, isClass, isClassOrFunction, isPlainObject };
+export { AppModule, type AppModuleOptions, type CloneParams, type DependencyProvider, type DynamicExports, GLOBAL_APP_MODULE_ID, GlobalAppModule, GlobalContainer, type IAppModule, type IProviderModule, type IProviderModuleNaked, Inject, InjectFromBase, Injectable, InjectionScope, type LazyInitOptions, MultiInject, Named, type OnEvent, Optional, PostConstruct, PreDestroy, type ProviderClassToken, type ProviderFactoryToken, type ProviderIdentifier, ProviderModule, type ProviderModuleGetManyParam, type ProviderModuleGetManySignature, ProviderModuleHelpers, type ProviderModuleOptions, type ProviderModuleOptionsInternal, type ProviderOptions, type ProviderScopeOption, type ProviderToken, ProviderTokenHelpers, type ProviderValueToken, type StaticExports, Tagged, Unmanaged, XInjectionDynamicExportsOutOfRange, XInjectionError, XInjectionProviderModuleDisposedError, XInjectionProviderModuleError, XInjectionProviderModuleMissingIdentifierError, bindingScopeToInjectionScope, injectionScopeToBindingScope, isClass, isClassOrFunction, isFunction, isPlainObject };