@adimm/x-injection 0.8.0 → 1.1.6

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { BindingActivation, BindingDeactivation, BindingConstraints, Container, BindingScope, BindToFluentSyntax, GetOptions, IsBoundOptions, injectFromBase, MetadataName, MetadataTag, ServiceIdentifier } from 'inversify';
-import { Class, Except } from 'type-fest';
+import { BindingActivation, BindingDeactivation, BindingConstraints, Container, BindToFluentSyntax, GetOptions, IsBoundOptions, BindingScope, injectFromBase, MetadataName, MetadataTag, ServiceIdentifier } from 'inversify';
+import { Class, RequireAtLeastOne, Except } from 'type-fest';
 
 /** The identifier of the `GlobalAppModule`. */
 declare const GLOBAL_APP_MODULE_ID = "GlobalAppModule";
@@ -95,254 +95,6 @@ interface ProviderScopeOption {
     scope?: InjectionScope;
 }
 
-/**
- * Class containing an internal set of `utils`.
- *
- * Each {@link IProviderModuleNaked.moduleUtils | ProviderModule} instance has its own {@link ProviderModuleUtils} property instance.
- */
-declare class ProviderModuleUtils {
-    /** The low-level InversifyJS {@link Container} owned by {@link ProviderModuleUtils.module | module}. */
-    get container(): Container;
-    /** The parent {@link IProviderModule | ProviderModule} of `this` instance. */
-    readonly module: IProviderModule;
-    readonly moduleNaked: IProviderModuleNaked;
-    private readonly appModule;
-    constructor(module: IProviderModule, internalOptions: ProviderModuleOptionsInternal);
-    /**
-     * Low-level method which can be used to manually register _(bind)_ a new {@link provider} into the {@link ProviderModuleUtils.module | module} container.
-     *
-     * **Note:** _You shouldn't directly use this to register providers as they will not appear_
-     * _into the module's `imports` and `exports` arrays! Therefore leading to unexpected bugs and confusion!_
-     *
-     * @param provider The {@link ProviderToken | provider} to register.
-     * @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: DependencyProvider<T>, defaultScope: InjectionScope): boolean;
-    private checkIfShouldBeAddedToTheGlobalRegister;
-    private bindSelfTokenToContainer;
-    private bindClassTokenToContainer;
-    private bindValueTokenToContainer;
-    private bindFactoryTokenToContainer;
-    /** Sets the {@link InjectionScope} of a bound {@link provider}. */
-    private setBindingScope;
-    /** Sets the `when` clause of a bound {@link provider}. */
-    private setWhenBinding;
-    /** Sets the `activation` and `deactivation` events of a bound {@link provider}. */
-    private setBindingOnEvent;
-}
-
-/** Can be used to publicly expose internal properties and methods of an {@link IProviderModule} instance. */
-interface IProviderModuleNaked extends IProviderModule {
-    /** It'll be true when the current module is the global `AppModule`. */
-    readonly isAppModule: boolean;
-    /** The low-level `InversifyJS` {@link https://inversify.io/docs/api/container/ | container} instance. */
-    readonly container: Container;
-    /** The default injection scope of this module. */
-    readonly defaultScope: {
-        /** Scope from `xInjection` {@link InjectionScope} enum. */
-        native: InjectionScope;
-        /** 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 | (() => 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'];
-    readonly registeredSideEffects: RegisteredSideEffects;
-    /** It'll _completely_ re-init the `module` with the provided {@link LazyInitOptions | options}. */
-    _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. */
-    _getProviders(): DependencyProvider[];
-    /** Can be used to get the list of all the exportable modules and providers of this module. */
-    _getExportableModulesAndProviders(): StaticExports;
-    /**
-     * Can be used to execute the provided {@link cb | callback} whenever a _new_ {@link https://inversify.io/docs/fundamentals/binding/ | binding}
-     * is registered for the {@link provider}.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param cb The `callback` to be invoked.
-     */
-    _onBind<T>(provider: ProviderToken<T>, cb: () => Promise<void> | void): void;
-    /**
-     * Can be used to execute the provided {@link cb | callback} whenever the
-     * {@link IProviderModule.get | get} method is invoked.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param once When set to `true` it'll invoke the provided {@link cb | callback} only once.
-     * @param cb The `callback` to be invoked.
-     */
-    _onGet<T>(provider: ProviderToken<T>, once: boolean, cb: () => Promise<void> | void): void;
-    /**
-     * Can be used to execute the provided {@link cb | callback} whenever an existing {@link https://inversify.io/docs/fundamentals/binding/ | binding}
-     * is re-registered for the {@link provider}.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param cb The `callback` to be invoked.
-     */
-    _onRebind<T>(provider: ProviderToken<T>, cb: () => Promise<void> | void): void;
-    /**
-     * Can be used to execute the provided {@link cb | callback} whenever a {@link provider} is `unbound`.
-     *
-     * **Note:** _All the {@link _onBind}, {@link _onGet}, {@link _onRebind} and {@link _onUnbind} registered callbacks will be removed_
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param cb The `callback` to be invoked.
-     */
-    _onUnbind<T>(provider: ProviderToken<T>, cb: () => Promise<void> | void): void;
-    /**
-     * Internal method which can be used to completely overwrite the module {@link container}
-     * with the one provided.
-     *
-     * @param cb Callback which when invoked must return an instance of the {@link Container}.
-     */
-    _overwriteContainer(cb: () => Container): void;
-    /**
-     * Binds a {@link ProviderToken | provider}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#bind | Container.bind} for more details.
-     */
-    __bind<T>(provider: ProviderToken<T>): BindToFluentSyntax<T>;
-    /**
-     * Resolves a dependency by its runtime identifier.
-     * The runtime identifier must be associated with only one binding and the binding must be synchronously resolved,
-     * otherwise an error is thrown.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param options The {@link GetOptions}.
-     * @returns Either the {@link T | dependency} or `undefined` if {@link GetOptions.optional} is set to `true`.
-     *
-     * See {@link https://inversify.io/docs/api/container/#get | Container.get} for more details.
-     */
-    __get<T>(provider: ProviderToken<T>, options?: GetOptions): T;
-    /**
-     * Resolves a dependency by its runtime identifier.
-     * The runtime identifier must be associated with only one binding,
-     * otherwise an error is thrown.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @param options The {@link GetOptions}.
-     * @returns Either the {@link T | dependency} or `undefined` if {@link GetOptions.optional} is set to `true`.
-     *
-     * See {@link https://inversify.io/docs/api/container/#getasync | Container.getAsync} for more details.
-     */
-    __getAsync<T>(provider: ProviderToken<T>, options?: GetOptions): Promise<T>;
-    /** See {@link https://inversify.io/docs/api/container/#getall | Container.getAll} for more details. */
-    __getAll<T>(provider: ProviderToken<T>, options?: GetOptions): T[];
-    /** See {@link https://inversify.io/docs/api/container/#getallasync | Container.getAllAsync} for more details. */
-    __getAllAsync<T>(provider: ProviderToken<T>, options?: GetOptions): Promise<T[]>;
-    /**
-     * Can be used to check if there are registered bindings for the {@link provider | provider}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#isbound | Container.isBound} for more details.
-     */
-    __isBound(provider: ProviderToken, options?: IsBoundOptions): boolean;
-    /**
-     * Can be useed to check if there are registered bindings for the {@link provider | provider} only in the current container.
-     *
-     * See {@link https://inversify.io/docs/api/container/#iscurrentbound | Container.isCurrentBound} for more details.
-     */
-    __isCurrentBound(provider: ProviderToken, options?: IsBoundOptions): boolean;
-    /**
-     * Save the state of the container to be later restored with the restore method.
-     *
-     * See {@link https://inversify.io/docs/api/container/#snapshot | Container.snapshot} for more details.
-     */
-    __takeSnapshot(): void;
-    /**
-     * Restore container state to last snapshot.
-     *
-     * See {@link https://inversify.io/docs/api/container/#restore | Container.restore} for more details.
-     */
-    __restoreSnapshot(): void;
-    /**
-     * Convenience method that unbinds a {@link ProviderToken | provider} and then creates a new binding for it.
-     * This is equivalent to calling await `container.unbind` followed by `container.bind`, but in a single method.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @returns A {@link BindToFluentSyntax | binding builder} to continue configuring the new binding.
-     *
-     * See {@link https://inversify.io/docs/api/container/#rebind | Container.rebind} for more details.
-     */
-    __rebind<T>(provider: ProviderToken<T>): Promise<BindToFluentSyntax<T>>;
-    /**
-     * Synchronous version of {@link __rebindProvider}. Unbinds a {@link ProviderToken | provider} synchronously and then creates a new binding for it.
-     * Will throw an error if the unbind operation would be asynchronous.
-     *
-     * @param provider The {@link ProviderToken}.
-     * @returns A {@link BindToFluentSyntax | binding builder} to continue configuring the new binding.
-     *
-     * See {@link https://inversify.io/docs/api/container/#rebindsync | Container.rebindSync} for more details.
-     */
-    __rebindSync<T>(provider: ProviderToken<T>): BindToFluentSyntax<T>;
-    /**
-     * Removes **all** the associated bindings with the {@link provider} from the container.
-     *
-     * This will result in the {@link https://inversify.io/docs/fundamentals/lifecycle/deactivation/ | deactivation process}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#unbind | Container.unbind} for more details.
-     */
-    __unbind(provider: ProviderToken): Promise<void>;
-    /**
-     * Removes **all** the associated bindings with the {@link provider} from the container synchronously.
-     * This method works like {@link __unbind} but does not return a Promise.
-     * If the unbinding operation would be asynchronous (e.g. due to deactivation handlers),
-     * it will throw an error. Use this method when you know the operation won't involve async deactivations.
-     *
-     * This will result in the {@link https://inversify.io/docs/fundamentals/lifecycle/deactivation/ | deactivation process}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#unbindsync | Container.unbindSync} for more details.
-     */
-    __unbindSync(provider: ProviderToken): void;
-    /**
-     * Remove all bindings bound in this container.
-     *
-     * This will result in the {@link https://inversify.io/docs/fundamentals/lifecycle/deactivation/ | deactivation process}.
-     *
-     * See {@link https://inversify.io/docs/api/container/#unbindall | Container.unbindAll} for more details.
-     */
-    __unbindAll(): Promise<void>;
-}
-type LazyInitOptions = Except<ProviderModuleOptions & ProviderModuleOptionsInternal, 'identifier' | 'isAppModule'>;
-type RegisteredSideEffects = Map<ProviderToken, {
-    onBindEffects: OnBindEffects[];
-    onGetEffects: OnGetEffects[];
-    onRebindEffects: OnRebindEffects[];
-    onUnbindEffects: OnUnbindEffects[];
-}>;
-type OnBindEffects = () => Promise<void> | void;
-type OnGetEffects = {
-    once: boolean;
-    invoked: boolean;
-    cb: () => Promise<void> | void;
-};
-type OnRebindEffects = () => Promise<void> | void;
-type OnUnbindEffects = {
-    registerModule?: symbol;
-    cb: () => Promise<void> | void;
-};
-
 /**
  * The low-level App Container.
  *
@@ -356,6 +108,8 @@ declare const GlobalContainer: Container;
  *
  * _See {@link ProviderModuleOptions | ProviderModuleOptions}_.
  *
+ * **Note:** _Check also the {@link IProviderModuleDefinition}._
+ *
  * @example
  * ```ts
  * const EngineModule = new ProviderModule({
@@ -408,63 +162,40 @@ declare const GlobalContainer: Container;
  * ```
  */
 declare class ProviderModule implements IProviderModule {
-    readonly identifier: symbol;
-    readonly isMarkedAsGlobal: boolean;
-    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'];
-    protected readonly imports: IProviderModuleNaked['imports'];
-    protected readonly providers: IProviderModuleNaked['providers'];
-    protected readonly importedProviders: IProviderModuleNaked['importedProviders'];
-    protected readonly exports: IProviderModuleNaked['exports'];
-    protected readonly registeredSideEffects: IProviderModuleNaked['registeredSideEffects'];
-    constructor({ identifier, imports, providers, exports, defaultScope, markAsGlobal, dynamicExports, onReady, onDispose, ..._internalParams }: ProviderModuleOptions);
+    isDisposed: boolean;
+    readonly identifier: ModuleIdentifier;
+    isMarkedAsGlobal: boolean;
+    protected isAppModule: boolean;
+    protected container: Container;
+    protected defaultScope: IProviderModuleNaked['defaultScope'];
+    protected onReady: IProviderModuleNaked['onReady'];
+    protected onDispose: IProviderModuleNaked['onDispose'];
+    protected moduleUtils: IProviderModuleNaked['moduleUtils'];
+    protected imports: IProviderModuleNaked['imports'];
+    protected providers: IProviderModuleNaked['providers'];
+    protected exports: IProviderModuleNaked['exports'];
+    protected registeredSideEffects: IProviderModuleNaked['registeredSideEffects'];
+    constructor(options: ProviderModuleOptions | IProviderModuleDefinition);
     get<T>(provider: ProviderToken<T>, isOptional?: boolean): T;
     getMany<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>(...deps: D | unknown[]): ProviderModuleGetManySignature<D>;
+    lazyImport(...modules: ProviderModuleOrDefinition[]): void;
     toNaked(): IProviderModuleNaked;
-    clone(options?: Partial<ProviderModuleOptions>): IProviderModule;
     dispose(): Promise<void>;
     toString(): string;
     private setIdentifier;
     private prepareContainer;
     private injectImportedModules;
     private injectProviders;
-    private onUnbindInternal;
-    private registerBindingSideEffect;
-    private invokeRegisteredBindingSideEffects;
-    private removeRegisteredBindingSideEffects;
-    private removeOnUnbindEffectsFromImportedModule;
+    private registerSideEffect;
+    private invokeRegisteredSideEffects;
+    private removeRegisteredSideEffects;
     private shouldThrowIfDisposed;
     /**
      * **Publicly visible when the instance is casted to {@link IProviderModuleNaked}.**
      *
-     * See {@link IProviderModuleNaked._lazyInit}.
-     */
-    protected _lazyInit({ markAsGlobal, imports, providers, exports, defaultScope, dynamicExports, onReady, onDispose, ..._internalParams }: LazyInitOptions): IProviderModule;
-    /**
-     * **Publicly visible when the instance is casted to {@link IProviderModuleNaked}.**
-     *
-     * See {@link IProviderModuleNaked._getImportedModules}.
-     */
-    protected _getImportedModules(): (IProviderModuleNaked | (() => IProviderModuleNaked))[];
-    /**
-     * **Publicly visible when the instance is casted to {@link IProviderModuleNaked}.**
-     *
-     * See {@link IProviderModuleNaked._getProviders}.
-     */
-    protected _getProviders(): DependencyProvider[];
-    /**
-     * **Publicly visible when the instance is casted to {@link IProviderModuleNaked}.**
-     *
-     * See {@link IProviderModuleNaked._getExportableModulesAndProviders}.
+     * See {@link IProviderModuleNaked._internalInit}.
      */
-    protected _getExportableModulesAndProviders(): StaticExports;
+    protected _internalInit(options: InternalInitOptions | IProviderModuleDefinition): IProviderModule;
     /**
      * **Publicly visible when the instance is casted to {@link IProviderModuleNaked}.**
      *
@@ -587,6 +318,7 @@ declare class ProviderModule implements IProviderModule {
  * **You shouldn't initialize a new instance of this class, please use the {@link AppModule} instance!**
  */
 declare class GlobalAppModule extends ProviderModule implements IAppModule {
+    _strict: AppModuleOptions['_strict'];
     private nakedModule;
     private isLoaded;
     constructor();
@@ -612,27 +344,68 @@ declare class GlobalAppModule extends ProviderModule implements IAppModule {
  */
 declare const AppModule: GlobalAppModule;
 
-interface ProviderModuleOptions {
-    /** The module unique ID. */
-    identifier: symbol;
-    /** The list of imported {@link IProviderModule | modules} that export the {@link Provider | providers} which are required in this module. */
-    imports?: (IProviderModule | (() => IProviderModule))[];
-    /** The {@link DependencyProvider | providers} that will be instantiated by the container and that may be shared at least across this module. */
-    providers?: DependencyProvider[];
-    /**
-     * The subset of {@link ProviderToken | providers} or {@link IProviderModule | modules} that
-     * are provided by this module and should be available in other modules which import this module.
-     *
-     * _Check also the {@link dynamicExports} property._
-     */
-    exports?: StaticExports;
-    /**
-     * The default {@link InjectionScope} to be used when a {@link ProviderToken} does not have a defined `scope`.
-     *
-     * Defaults to {@link InjectionScope.Singleton}.
-     */
-    defaultScope?: InjectionScope;
-    /**
+/**
+ * Can be used when you _don't_ want to initialize a `ProviderModule` eagerly as each `ProviderModule` has its own _(InversifyJS)_ container
+ * initialized as soon as you do `new ProviderModule({...})`.
+ *
+ * The {@link ProviderModuleDefinition} allows you to just _define_ the `ProviderModule` options so you can _import_ it later into different modules.
+ *
+ * You can always edit a property of the definition after instantiation by doing:
+ *
+ * ```ts
+ * const GarageModuleDefinition = new ProviderModuleDefinition({ identifier: 'GarageModuleDefinition' });
+ *
+ * // Later in your code
+ *
+ * GarageModuleDefinition.imports = [...GarageModuleDefinition.imports, PorscheModule, FerrariModuleDefinition];
+ *
+ * // ...
+ *
+ * const GarageModule = new ProviderModule(GarageModuleDefinition);
+ *
+ * // or
+ *
+ * ExistingModule.lazyImport(GarageModuleDefinition);
+ * ```
+ *
+ * **Note:** _This means that you can't expect to be able to inject dependencies from a {@link ProviderModuleDefinition}_
+ * _as how you would do with an instance of a `ProviderModule`._
+ */
+declare class ProviderModuleDefinition implements IProviderModuleDefinition {
+    identifier: IProviderModuleDefinition['identifier'];
+    imports: IProviderModuleDefinition['imports'];
+    providers: IProviderModuleDefinition['providers'];
+    exports: IProviderModuleDefinition['exports'];
+    defaultScope: IProviderModuleDefinition['defaultScope'];
+    markAsGlobal: IProviderModuleDefinition['markAsGlobal'];
+    onReady: IProviderModuleDefinition['onReady'];
+    onDispose: IProviderModuleDefinition['onDispose'];
+    constructor(moduleOptions: ProviderModuleOptions);
+    getDefinition(): ProviderModuleOptions;
+    toString(): string;
+}
+
+interface ProviderModuleOptions {
+    /** The module unique `ID`. */
+    identifier: symbol | string;
+    /** Import additional {@link IProviderModule | modules} into _this_ module. */
+    imports?: ProviderModuleOrDefinition[];
+    /** The {@link DependencyProvider | providers} that will be instantiated by the container and that may be shared at least across _this_ module. */
+    providers?: DependencyProvider[];
+    /**
+     * The subset of {@link ProviderToken | providers} or {@link IProviderModule | modules} that
+     * are provided by _this_ module and should be available in other modules which import _this_ module.
+     *
+     * **Note:** _Supports lazy exports, see {@link LazyExport}._
+     */
+    exports?: ExportsList;
+    /**
+     * The default {@link InjectionScope} to be used when a {@link ProviderToken} does not have a defined `scope`.
+     *
+     * Defaults to {@link InjectionScope.Singleton}.
+     */
+    defaultScope?: InjectionScope;
+    /**
      * This option is only a _marker_, per se it doesn't do anything
      * apart from marking this module as `global`.
      * When a module is marked as `global`, it means that it is expected to be _imported_ into the `AppModule`.
@@ -644,46 +417,6 @@ interface ProviderModuleOptions {
      * Defaults to `false`.
      */
     markAsGlobal?: boolean;
-    /**
-     * When provided, can be used to control which providers from the {@link ProviderModuleOptions.exports | exports}
-     * array should actually be exported into the importing module.
-     *
-     * **Note:** _Static {@link ProviderModuleOptions.exports | exports} should always be preferred as their static nature implies predictibility._
-     * _This is for advanced use cases only, and most probably you may never need to use a dynamic export!_
-     *
-     * @example
-     * ```ts
-     * {
-     *   exports: [ConfigModule, UserModule, PaymentService, ReviewService],
-     *   dynamicExports: (importerModule, moduleExports) => {
-     *     const shouldExportOnlyTheServices = true;
-     *
-     *     if (shouldExportOnlyTheServices === false) return moduleExports;
-     *
-     *     return moduleExports.flatMap((ex) => {
-     *       // With `flatMap` we can map and filter out elements
-     *       // from the sequence at the same time
-     *       // by returning an empty array.
-     *       return ex instanceof ProviderModule ? [] : ex;
-     *     });
-     *   }
-     * }
-     *
-     * // Or
-     *
-     * {
-     *   exports: [ConfigModule, UserModule, PaymentService, ReviewService],
-     *   dynamicExports: (importerModule, moduleExports) => {
-     *     // We export all the providers only when the importer module is not the `BULLIED_MODULE`.
-     *     if (importerModule.toNaked().name !== 'BULLIED_MODULE') return moduleExports;
-     *
-     *     return [ConfigModule];
-     *   }
-     * }
-     *
-     * ```
-     */
-    dynamicExports?: DynamicExports;
     /**
      * Callback which will be invoked once the module container has been initialized
      * and the providers resolved.
@@ -694,13 +427,11 @@ interface ProviderModuleOptions {
      */
     onReady?: (module: IProviderModule) => Promise<void>;
     /**
-     * Callback which will be invoked whenever the internal module dispose method is invoked.
-     *
-     * **The method will be invoked right _before_ the clean-up process.**
+     * Callback which will be invoked when the module dispose method is invoked.
      *
-     * @param module The instance of the {@link IProviderModule | module}.
+     * @returns See {@link OnDisposeOptions}.
      */
-    onDispose?: (module: IProviderModule) => Promise<void>;
+    onDispose?: () => OnDisposeOptions;
 }
 interface ProviderModuleOptionsInternal {
     isAppModule?: boolean;
@@ -709,27 +440,272 @@ interface ProviderModuleOptionsInternal {
     appModule?: () => GlobalAppModule;
     /** 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 = (
-/** The {@link IProviderModule} which is importing this module. */
-importerModule: IProviderModule, 
-/** The {@link ProviderModuleOptions.exports | exports} array of this module. */
-moduleExports: StaticExports) => StaticExports;
+type ExportsList = (StaticExport | LazyExport)[];
+type StaticExport = ProviderToken | ProviderModuleOrDefinition;
+type LazyExport = (
+/** The {@link IProviderModule | module} which is importing _this_ module. */
+importerModule: IProviderModule) => StaticExport | void;
+type OnDisposeOptions = RequireAtLeastOne<{
+    /**
+     * It'll be invoked _before_ the dispose process starts.
+     *
+     * @param module The {@link IProviderModule | module} instance.
+     */
+    before: (module: IProviderModule) => void | Promise<void>;
+    /**
+     * It'll be invoked _after_ the dispose process ended.
+     *
+     * **Note:** _At this point the internal container has been destroyed and it'll be `null` when trying to access it._
+     *
+     * @param module The {@link IProviderModule | module} instance.
+     */
+    after: (module: IProviderModule) => void | Promise<void>;
+}>;
+
+interface IProviderModuleDefinition extends ProviderModuleOptions {
+    /** Returns the {@link ProviderModuleOptions | definition}. */
+    getDefinition(): ProviderModuleOptions;
+    /** Returns the {@link ProviderModuleOptions.identifier | identifier}. */
+    toString(): string;
+}
+
+/**
+ * Class containing an internal set of `utils`.
+ *
+ * Each {@link IProviderModuleNaked.moduleUtils | ProviderModule} instance has its own {@link ProviderModuleUtils} property instance.
+ */
+declare class ProviderModuleUtils {
+    /** The low-level InversifyJS {@link Container} owned by {@link ProviderModuleUtils.module | module}. */
+    get container(): Container;
+    /** The parent {@link IProviderModule | ProviderModule} of `this` instance. */
+    readonly module: IProviderModule;
+    readonly moduleNaked: IProviderModuleNaked;
+    private readonly appModule;
+    constructor(module: IProviderModule, internalOptions: ProviderModuleOptionsInternal);
+    /**
+     * Low-level method which can be used to manually register _(bind)_ a new {@link provider} into the {@link ProviderModuleUtils.module | module} container.
+     *
+     * **Note:** _You shouldn't directly use this to register providers as they will not appear_
+     * _into the module's `imports` and `exports` arrays! Therefore leading to unexpected bugs and confusion!_
+     *
+     * @param provider The {@link ProviderToken | provider} to register.
+     * @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: DependencyProvider<T>, defaultScope: InjectionScope): boolean;
+    private checkIfShouldBeAddedToTheGlobalRegister;
+    private bindSelfTokenToContainer;
+    private bindClassTokenToContainer;
+    private bindValueTokenToContainer;
+    private bindFactoryTokenToContainer;
+    /** Sets the {@link InjectionScope} of a bound {@link provider}. */
+    private setBindingScope;
+    /** Sets the `when` clause of a bound {@link provider}. */
+    private setWhenBinding;
+    /** Sets the `activation` and `deactivation` events of a bound {@link provider}. */
+    private setBindingOnEvent;
+}
+
+/** Can be used to publicly expose internal properties and methods of an {@link IProviderModule} instance. */
+interface IProviderModuleNaked extends IProviderModule {
+    /** It'll be true when the current module is the global `AppModule`. */
+    readonly isAppModule: boolean;
+    /** The low-level `InversifyJS` {@link https://inversify.io/docs/api/container/ | container} instance. */
+    readonly container: Container;
+    /** The default injection scope of this module. */
+    readonly defaultScope: {
+        /** Scope from `xInjection` {@link InjectionScope} enum. */
+        native: InjectionScope;
+        /** 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[];
+    /** What is exported into this module. */
+    readonly imports: ProviderModuleOrDefinition[];
+    /** What is exported from this module. */
+    readonly exports: ExportsList;
+    /** 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'];
+    readonly registeredSideEffects: RegisteredSideEffects;
+    /** It'll _completely_ re-init the `module` with the provided {@link InternalInitOptions | options}. */
+    _internalInit(options: InternalInitOptions): IProviderModule;
+    /**
+     * Can be used to execute the provided {@link cb | callback} whenever a _new_ {@link https://inversify.io/docs/fundamentals/binding/ | binding}
+     * is registered for the {@link provider}.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param cb The `callback` to be invoked.
+     */
+    _onBind<T>(provider: ProviderToken<T>, cb: () => Promise<void> | void): void;
+    /**
+     * Can be used to execute the provided {@link cb | callback} whenever the
+     * {@link IProviderModule.get | get} method is invoked.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param once When set to `true` it'll invoke the provided {@link cb | callback} only once.
+     * @param cb The `callback` to be invoked.
+     */
+    _onGet<T>(provider: ProviderToken<T>, once: boolean, cb: () => Promise<void> | void): void;
+    /**
+     * Can be used to execute the provided {@link cb | callback} whenever an existing {@link https://inversify.io/docs/fundamentals/binding/ | binding}
+     * is re-registered for the {@link provider}.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param cb The `callback` to be invoked.
+     */
+    _onRebind<T>(provider: ProviderToken<T>, cb: () => Promise<void> | void): void;
+    /**
+     * Can be used to execute the provided {@link cb | callback} whenever a {@link provider} is `unbound`.
+     *
+     * **Note:** _All the {@link _onBind}, {@link _onGet}, {@link _onRebind} and {@link _onUnbind} registered callbacks will be removed_
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param cb The `callback` to be invoked.
+     */
+    _onUnbind<T>(provider: ProviderToken<T>, cb: () => Promise<void> | void): void;
+    /**
+     * Internal method which can be used to completely overwrite the module {@link container}
+     * with the one provided.
+     *
+     * @param cb Callback which when invoked must return an instance of the {@link Container}.
+     */
+    _overwriteContainer(cb: () => Container): void;
+    /**
+     * Binds a {@link ProviderToken | provider}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#bind | Container.bind} for more details.
+     */
+    __bind<T>(provider: ProviderToken<T>): BindToFluentSyntax<T>;
+    /**
+     * Resolves a dependency by its runtime identifier.
+     * The runtime identifier must be associated with only one binding and the binding must be synchronously resolved,
+     * otherwise an error is thrown.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param options The {@link GetOptions}.
+     * @returns Either the {@link T | dependency} or `undefined` if {@link GetOptions.optional} is set to `true`.
+     *
+     * See {@link https://inversify.io/docs/api/container/#get | Container.get} for more details.
+     */
+    __get<T>(provider: ProviderToken<T>, options?: GetOptions): T;
+    /**
+     * Resolves a dependency by its runtime identifier.
+     * The runtime identifier must be associated with only one binding,
+     * otherwise an error is thrown.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @param options The {@link GetOptions}.
+     * @returns Either the {@link T | dependency} or `undefined` if {@link GetOptions.optional} is set to `true`.
+     *
+     * See {@link https://inversify.io/docs/api/container/#getasync | Container.getAsync} for more details.
+     */
+    __getAsync<T>(provider: ProviderToken<T>, options?: GetOptions): Promise<T>;
+    /** See {@link https://inversify.io/docs/api/container/#getall | Container.getAll} for more details. */
+    __getAll<T>(provider: ProviderToken<T>, options?: GetOptions): T[];
+    /** See {@link https://inversify.io/docs/api/container/#getallasync | Container.getAllAsync} for more details. */
+    __getAllAsync<T>(provider: ProviderToken<T>, options?: GetOptions): Promise<T[]>;
+    /**
+     * Can be used to check if there are registered bindings for the {@link provider | provider}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#isbound | Container.isBound} for more details.
+     */
+    __isBound(provider: ProviderToken, options?: IsBoundOptions): boolean;
+    /**
+     * Can be useed to check if there are registered bindings for the {@link provider | provider} only in the current container.
+     *
+     * See {@link https://inversify.io/docs/api/container/#iscurrentbound | Container.isCurrentBound} for more details.
+     */
+    __isCurrentBound(provider: ProviderToken, options?: IsBoundOptions): boolean;
+    /**
+     * Save the state of the container to be later restored with the restore method.
+     *
+     * See {@link https://inversify.io/docs/api/container/#snapshot | Container.snapshot} for more details.
+     */
+    __takeSnapshot(): void;
+    /**
+     * Restore container state to last snapshot.
+     *
+     * See {@link https://inversify.io/docs/api/container/#restore | Container.restore} for more details.
+     */
+    __restoreSnapshot(): void;
+    /**
+     * Convenience method that unbinds a {@link ProviderToken | provider} and then creates a new binding for it.
+     * This is equivalent to calling await `container.unbind` followed by `container.bind`, but in a single method.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @returns A {@link BindToFluentSyntax | binding builder} to continue configuring the new binding.
+     *
+     * See {@link https://inversify.io/docs/api/container/#rebind | Container.rebind} for more details.
+     */
+    __rebind<T>(provider: ProviderToken<T>): Promise<BindToFluentSyntax<T>>;
+    /**
+     * Synchronous version of {@link __rebindProvider}. Unbinds a {@link ProviderToken | provider} synchronously and then creates a new binding for it.
+     * Will throw an error if the unbind operation would be asynchronous.
+     *
+     * @param provider The {@link ProviderToken}.
+     * @returns A {@link BindToFluentSyntax | binding builder} to continue configuring the new binding.
+     *
+     * See {@link https://inversify.io/docs/api/container/#rebindsync | Container.rebindSync} for more details.
+     */
+    __rebindSync<T>(provider: ProviderToken<T>): BindToFluentSyntax<T>;
+    /**
+     * Removes **all** the associated bindings with the {@link provider} from the container.
+     *
+     * This will result in the {@link https://inversify.io/docs/fundamentals/lifecycle/deactivation/ | deactivation process}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#unbind | Container.unbind} for more details.
+     */
+    __unbind(provider: ProviderToken): Promise<void>;
+    /**
+     * Removes **all** the associated bindings with the {@link provider} from the container synchronously.
+     * This method works like {@link __unbind} but does not return a Promise.
+     * If the unbinding operation would be asynchronous (e.g. due to deactivation handlers),
+     * it will throw an error. Use this method when you know the operation won't involve async deactivations.
+     *
+     * This will result in the {@link https://inversify.io/docs/fundamentals/lifecycle/deactivation/ | deactivation process}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#unbindsync | Container.unbindSync} for more details.
+     */
+    __unbindSync(provider: ProviderToken): void;
+    /**
+     * Remove all bindings bound in this container.
+     *
+     * This will result in the {@link https://inversify.io/docs/fundamentals/lifecycle/deactivation/ | deactivation process}.
+     *
+     * See {@link https://inversify.io/docs/api/container/#unbindall | Container.unbindAll} for more details.
+     */
+    __unbindAll(): Promise<void>;
+}
+type InternalInitOptions = Except<ProviderModuleOptions & ProviderModuleOptionsInternal, 'identifier' | 'isAppModule'>;
+type RegisteredSideEffects = Map<ProviderToken, {
+    onBindEffects: OnBindEffects[];
+    onGetEffects: OnGetEffects[];
+    onRebindEffects: OnRebindEffects[];
+    onUnbindEffects: OnUnbindEffects[];
+}>;
+type OnBindEffects = () => Promise<void> | void;
+type OnGetEffects = {
+    once: boolean;
+    invoked: boolean;
+    cb: () => Promise<void> | void;
+};
+type OnRebindEffects = () => Promise<void> | void;
+type OnUnbindEffects = {
+    registerModuleId?: ModuleIdentifier;
+    cb: () => Promise<void> | void;
+};
 
 interface IProviderModule {
     /** The module unique ID. */
-    readonly identifier: symbol;
+    readonly identifier: ModuleIdentifier;
     /** See {@link ProviderModuleOptions.markAsGlobal}. */
-    readonly isMarkedAsGlobal: boolean;
+    readonly isMarkedAsGlobal: ProviderModuleOptions['markAsGlobal'];
     readonly isDisposed: boolean;
     /**
      * Can be used to retrieve a resolved `dependency` from the module container.
@@ -762,30 +738,28 @@ interface IProviderModule {
      */
     getMany<D extends (ProviderModuleGetManyParam<any> | ProviderToken)[]>(...deps: D | unknown[]): ProviderModuleGetManySignature<D>;
     /**
-     * Casts the current module type to the {@link IProviderModuleNaked} type.
+     * Can be used to _lazily_ import one or more {@link IProviderModule | modules} into _this_ module.
      *
-     * **Internally used and for testing purposes!**
+     * @param module The `module` to be imported.
      */
-    toNaked(): IProviderModuleNaked;
+    lazyImport(...module: ProviderModuleOrDefinition[]): void;
     /**
-     * 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._
+     * Casts the current module type to the {@link IProviderModuleNaked} type.
      *
-     * @param options Apply a new set of {@link ProviderModuleOptions | options}.
+     * **Internally used and for testing purposes!**
      */
-    clone(options?: Partial<ProviderModuleOptions>): IProviderModule;
+    toNaked(): IProviderModuleNaked;
     /**
      * Removes all the bindings from the {@link IProviderModuleNaked.container | container}.
      *
-     * **Note:** The module can be fully re-initialized by invoking the {@link _lazyInit} method.
+     * **Note:** The module can be fully re-initialized by invoking the {@link _internalInit} method.
      */
     dispose(): Promise<void>;
-    /** Returns the {@link IProviderModule.identifier} `symbol` description. */
+    /** Returns the {@link IProviderModule.identifier}. */
     toString(): string;
 }
+type ModuleIdentifier = symbol | string;
+type ProviderModuleOrDefinition = IProviderModule | IProviderModuleDefinition;
 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;
 };
@@ -797,11 +771,25 @@ type ProviderModuleGetManyParam<T> = {
 };
 
 interface IAppModule extends Except<IProviderModule, 'isMarkedAsGlobal'> {
+    readonly _strict: AppModuleOptions['_strict'];
     /** 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;
     toNaked(): IAppModule & IProviderModuleNaked;
 }
-type AppModuleOptions = Except<LazyInitOptions, 'exports' | 'dynamicExports'>;
+interface AppModuleOptions extends Except<InternalInitOptions, 'appModule' | 'markAsGlobal' | 'exports' | 'isDisposed'> {
+    /**
+     * When set to `true` it'll enforce an opinionated set of rules
+     * which _can help_ in avoiding common pitfalls which may otherwise produce
+     * undesired side-effects or edge-case bugs.
+     *
+     * **Note:** _Do not open an `issue` if a bug or edge-case is caused by having the `strict` property disabled!_
+     *
+     * - `markAsGlobal`: Will not be enforced anymore.
+     *
+     * Defaults to `true`.
+     */
+    _strict?: boolean;
+}
 
 /** See {@link https://inversify.io/docs/api/decorator/#inject} for more details. */
 declare function Inject(provider: ProviderToken): MethodDecorator & ParameterDecorator & PropertyDecorator;
@@ -881,7 +869,13 @@ declare namespace ProviderTokenHelpers {
 
 declare namespace ProviderModuleHelpers {
     function buildInternalConstructorParams(params: Partial<ProviderModuleOptions & ProviderModuleOptionsInternal>): ProviderModuleOptions;
-    function isDynamicExport(exporter: StaticExports | DynamicExports): exporter is DynamicExports;
+    function getOptionsOrModuleDefinitionOptions(optionsOrDefinition: ProviderModuleOptions | IProviderModuleDefinition): {
+        options: ProviderModuleOptions;
+        internalOptions: ProviderModuleOptionsInternal;
+    };
+    function isModuleDefinition(value: any): value is IProviderModuleDefinition;
+    function isLazyExport(exp: any): exp is LazyExport;
+    function tryStaticOrLazyExportToStaticExport(module: IProviderModule, exp: StaticExport | LazyExport): StaticExport | void;
 }
 
 declare function isPlainObject(o: any): o is object;
@@ -892,4 +886,4 @@ declare function isFunction(v: any): boolean;
 
 declare function isClassOrFunction(value: any): value is Function | Class<any>;
 
-export { AppModule, type AppModuleOptions, type DependencyProvider, type DynamicExports, GLOBAL_APP_MODULE_ID, GlobalAppModule, GlobalContainer, type IAppModule, type IProviderModule, type IProviderModuleNaked, Inject, InjectFromBase, Injectable, InjectionError, InjectionProviderModuleDisposedError, InjectionProviderModuleError, InjectionProviderModuleGlobalMarkError, InjectionProviderModuleMissingIdentifierError, InjectionScope, type LazyInitOptions, MultiInject, Named, type OnEvent, Optional, 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, bindingScopeToInjectionScope, injectionScopeToBindingScope, isClass, isClassOrFunction, isFunction, isPlainObject };
+export { AppModule, type AppModuleOptions, type DependencyProvider, type ExportsList, GLOBAL_APP_MODULE_ID, GlobalAppModule, GlobalContainer, type IAppModule, type IProviderModule, type IProviderModuleDefinition, type IProviderModuleNaked, Inject, InjectFromBase, Injectable, InjectionError, InjectionProviderModuleDisposedError, InjectionProviderModuleError, InjectionProviderModuleGlobalMarkError, InjectionProviderModuleMissingIdentifierError, InjectionScope, type InternalInitOptions, MultiInject, Named, type OnEvent, Optional, type ProviderClassToken, type ProviderFactoryToken, type ProviderIdentifier, ProviderModule, ProviderModuleDefinition, type ProviderModuleGetManyParam, type ProviderModuleGetManySignature, ProviderModuleHelpers, type ProviderModuleOptions, type ProviderModuleOptionsInternal, type ProviderModuleOrDefinition, type ProviderOptions, type ProviderScopeOption, type ProviderToken, ProviderTokenHelpers, type ProviderValueToken, Tagged, Unmanaged, bindingScopeToInjectionScope, injectionScopeToBindingScope, isClass, isClassOrFunction, isFunction, isPlainObject };