@adimm/x-injection 1.1.6 → 1.2.0

package/README.md

@@ -31,7 +31,6 @@ xInjection&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injection" targe
   - [ProviderModuleDefinition](#providermoduledefinition)
     - [Feed to `new ProviderModule`](#feed-to-new-providermodule)
     - [Feed to `lazyImport`](#feed-to-lazyimport)
-    - [Why not just use the `ProviderModuleOptions` interface?](#why-not-just-use-the-providermoduleoptions-interface)
   - [Lazy `imports` and `exports`](#lazy-imports-and-exports)
     - [Imports](#imports)
     - [Exports](#exports)
@@ -39,9 +38,12 @@ xInjection&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injection" targe
   - [ProviderModuleNaked Interface](#providermodulenaked-interface)
   - [Strict Mode](#strict-mode)
     - [Why you should not turn it off:](#why-you-should-not-turn-it-off)
-      - [MarkAsGlobal](#markasglobal)
+      - [isGlobal](#isglobal)
 - [Unit Tests](#unit-tests)
 - [Documentation](#documentation)
+- [Conventions](#conventions)
+  - [ProviderModule](#providermodule)
+  - [ProviderModuleDefinition](#providermoduledefinition-1)
 - [ReactJS Implementation](#reactjs-implementation)
 - [Contributing](#contributing)
 
@@ -98,7 +100,13 @@ import { AppModule } from '@adimm/x-injection';
 AppModule.register({});
 ```
 
-> **Note:** You must call `AppModule.register()` even if you have no global providers. Passing an empty object `{}` is valid.
+> [!WARNING]
+>
+> _You must invoke `AppModule.register()` even if you have no global providers. Passing an empty object `{}` to the method is valid._
+
+> [!NOTE]
+>
+> _You can import additional modules (later at run-time) into the `AppModule` by using the [lazyImport](https://adimarianmutu.github.io/x-injection/interfaces/IAppModule.html#lazyimport-1) `method`._
 
 ### Registering Global Providers
 
@@ -130,21 +138,61 @@ You can also import entire modules into the `AppModule` like so:
 const SECRET_TOKEN_PROVIDER = { provide: 'SECRET_TOKEN', useValue: '123' };
 const SECRET_TOKEN_2_PROVIDER = { provide: 'SECRET_TOKEN_2', useValue: 123 };
 
-const ConfigModule = new ProviderModule({
-  identifier: Symbol('ConfigModule'),
-  markAsGlobal: true,
+const ConfigModuleDef = new ProviderModuleDefinition({
+  identifier: 'ConfigModule',
+  isGlobal: true,
   providers: [SECRET_TOKEN_PROVIDER, SECRET_TOKEN_2_PROVIDER],
   exports: [SECRET_TOKEN_PROVIDER, SECRET_TOKEN_2_PROVIDER],
 });
 
 AppModule.register({
-  imports: [ConfigModule],
+  imports: [ConfigModuleDef],
+});
+```
+
+> [!WARNING]
+>
+> _Importing a module marked as global into a scoped module will automatically import it into the `AppModule` rather than the scoped module itself!_
+
+This means that you can also do the following:
+
+```ts
+const FancyModuleDefinition = new ProviderModuleDefinition({
+  identifier: 'FancyModule',
+  isGlobal: true,
+  providers: [FancyService],
+  exports: [FancyService],
+});
+
+const ScopedModule = new ProviderModule({
+  identifier: 'ScopedModule',
+  // This `ScopedModule` will automatically "forward" the global `FancyModuleDefinition`
+  // exports to the `AppModule`.
+  imports: [FancyModuleDefinition],
 });
+
+AppModule.get(FancyService);
+// returns the global instance of the `FancyService` class
 ```
 
-> **Note:** _All modules which are imported into the `AppModule` must have the [markAsGlobal](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#markasglobal) option set to `true`, otherwise the [InjectionProviderModuleGlobalMarkError](https://adimarianmutu.github.io/x-injection/classes/InjectionProviderModuleGlobalMarkError.html) exception will be thrown!_
+The above can also be written as:
+
+```ts
+const FancyModuleDefinition = new ProviderModuleDefinition({
+  identifier: 'FancyModule',
+  isGlobal: true,
+  providers: [FancyService],
+  exports: [FancyService],
+});
+
+AppModule.lazyImport(FancyModuleDefinition);
+```
+
+> [!NOTE]
+>
+> _All modules which are imported into the `AppModule` must have the [isGlobal](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#isGlobal) option set to `true`, otherwise the [InjectionProviderModuleGlobalMarkError](https://adimarianmutu.github.io/x-injection/classes/InjectionProviderModuleGlobalMarkError.html) exception will be thrown!_
 >
-> **Note2:** _An [InjectionProviderModuleGlobalMarkError](https://adimarianmutu.github.io/x-injection/classes/InjectionProviderModuleGlobalMarkError.html) exception will be thrown also when importing into the `AppModule` a module which does **not** have the [markAsGlobal](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#markasglobal) flag option!_
+> _An [InjectionProviderModuleGlobalMarkError](https://adimarianmutu.github.io/x-injection/classes/InjectionProviderModuleGlobalMarkError.html) exception will be thrown also when importing into the `AppModule` a module which does **not** have the [isGlobal](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#isGlobal) flag option!_
 
 ### Injection Scope
 
@@ -166,13 +214,15 @@ The below list shows them in order of priority _(highest to lowest)_, meaning th
    ```
 3. By providing the [defaultScope](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#defaultscope) property when initializing a `ProviderModule`:
    ```ts
-   const RainModule = new ProviderModule({
-     identifier: Symbol('RainModule'),
+   const RainModuleDef = new ProviderModuleDef({
+     identifier: 'RainModule',
      defaultScope: InjectionScope.Transient,
    });
    ```
 
-> **Note:** _Imported modules/providers retain their original `InjectionScope`!_
+> [!NOTE]
+>
+> _Imported modules/providers retain their original `InjectionScope`!_
 
 #### Singleton
 
@@ -251,9 +301,8 @@ export class SessionService {
   // Implementation...
 }
 
-export const DatabaseModule = new ProviderModule({
-  identifier: Symbol('DatabaseModule'),
-  // or:  identifier: 'DatabaseModule',
+export const DatabaseModuleDef = new ProviderModuleDefinitionDef({
+  identifier: 'DatabaseModule',
   providers: [DatabaseService],
   exports: [DatabaseService],
   onReady: async (module) => {
@@ -261,15 +310,26 @@ export const DatabaseModule = new ProviderModule({
 
     // Additional initialization...
   },
-  onDispose: async (module) => {
-    const databaseService = module.get(DatabaseService);
+  onDispose: () => {
+    return {
+      before: async (module) => {
+        // It is invoked right before the dispose process begins.
+        // This means that the `module` container is still available to be used.
+
+        const databaseService = module.get(DatabaseService);
 
-    databaseService.closeConnection();
+        databaseService.closeConnection();
+      },
+      after: async (module) => {
+        // It is invoked right after the dispose process ended.
+        // This means that the `module` container is not available anymore.
+      },
+    };
   },
 });
 
-export const SessionModule = new ProviderModule({
-  identifier: Symbol('SessionModule'),
+export const SessionModuleDef = new ProviderModuleDefinition({
+  identifier: 'SessionModule',
   defaultScope: InjectionScope.Request,
   providers: [SessionService],
   exports: [SessionService],
@@ -280,11 +340,13 @@ Register these modules in your `AppModule`:
 
 ```ts
 AppModule.register({
-  imports: [DatabaseModule, SessionModule],
+  imports: [DatabaseModuleDef, SessionModuleDef],
 });
 ```
 
-> **Note:** The `AppModule.register` method can be invoked only _once_! _(You may re-invoke it only after the module has been disposed)_ Preferably during your application bootstrapping process.
+> [!WARNING]
+>
+> The `AppModule.register` method can be invoked only _once_, preferably during your application bootstrapping process. _(you may re-invoke it only after the module has been disposed)_
 
 From now on, the `AppModule` container has the references of the `DatabaseService` and the `SessionService`.
 
@@ -328,13 +390,9 @@ const GarageModule = new ProviderModule(GarageModuleDefinition);
 ExistingModule.lazyImport(GarageModuleDefinition);
 ```
 
-> **Note:** _Providing it to the `lazyImport` method will automatically instantiate a new `ProviderModule` on-the-fly!_
-
-#### Why not just use the `ProviderModuleOptions` interface?
-
-That's a very good question! It means that you understood that the `ProviderModuleDefinition` is actually a `class` wrapper of the `ProviderModuleOptions`.
-
-Theoretically you _can_ use a _plain_ `object` having the `ProviderModuleOptions` interface, however, the `ProviderModuleOptions` interface purpose is solely to _expose/shape_ the options with which a module can be instantiated, while the `ProviderModuleDefinition` purpose is to _define_ the actual `ProviderModule` _blueprint_.
+> [!NOTE]
+>
+> _Providing it to the `lazyImport` method will automatically instantiate a new `ProviderModule` on-the-fly!_
 
 ### Lazy `imports` and `exports`
 
@@ -363,15 +421,15 @@ GarageModule.lazyImport(LamborghiniModule, BugattiModule, ...);
 You can lazily `export` a `provider` or `module` by providing a `callback` _(it can also be an `async` callback)_ as shown below:
 
 ```ts
-const SecureBankBranchModule = new ProviderModule({
+const SecureBankBranchModuleDef = new ProviderModuleDef({
   identifier: 'SecureBankBranchModule',
   providers: [BankBranchService],
   exports: [BankBranchService],
 });
 
-const BankModule = new ProviderModule({
+const BankModuleDef = new ProviderModuleDef({
   identifier: 'BankModule',
-  imports: [SecureBankBranchModule],
+  imports: [SecureBankBranchModuleDef],
   exports: [..., (importerModule) => {
     // When the module having the identifier `UnknownBankModule` imports the `BankModule`
     // it'll not be able to also import the `SecureBankBranchModule` as we are not returning it here.
@@ -411,13 +469,15 @@ By default the `AppModule` runs in "strict mode", a built-in mode which enforces
 
 When invoking the [AppModule.register](https://adimarianmutu.github.io/x-injection/interfaces/IAppModule.html#register-1) `method` you can set the [\_strict](https://adimarianmutu.github.io/x-injection/interfaces/AppModuleOptions.html#_strict) property to `false` in order to permanentely disable those set of built-in rules.
 
-> **Note:** _Do not open an `issue` if a bug or edge-case is caused by having the `strict` property disabled!_
+> [!WARNING]
+>
+> _Do not open an `issue` if a bug or edge-case is caused by having the `strict` property disabled!_
 
 #### Why you should not turn it off:
 
-##### MarkAsGlobal
+##### isGlobal
 
-The [markAsGlobal](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#markasglobal) flag property is used to make sure that `modules` which should be registered directly into the `AppModule` are indeed provided to the the `imports` array of the `AppModule` and the the other way around, if a `module` is imported into the `AppModule` without having the `markAsGlobal` flag property set, it'll throw an error.
+When using the [isGlobal](https://adimarianmutu.github.io/x-injection/interfaces/ProviderModuleOptions.html#isGlobal) property if a `module` is imported into the `AppModule` without having the `isGlobal` flag property set, it'll throw an error.
 
 This may look redundant, but it may save you _(and your team)_ some hours of debugging in understanding why some `providers` are able to make their way into other `modules`. As those `providers` are now acting as _global_ `providers`.
 
@@ -439,7 +499,7 @@ const AnotherScopedModule = new ProviderModule({
 
 const GlobalModule = new ProviderModule({
   identifier: 'GlobalModule',
-  markAsGlobal: true,
+  isGlobal: true,
   imports: [AnotherScopedModule],
 });
 
@@ -450,7 +510,7 @@ AppModule.register({
 
 At first glance you may not spot/understand the issue there, but because the `GlobalModule` _(which is then imported into the `AppModule`)_ is _directly_ importing the `AnotherScopedModule`, it means that _all_ the `providers` of the `AnotherScopedModule` and `ScopedModule` _(because `AnotherScopedModule` also imports `ScopedModule`)_ will become accessible through your entire app!
 
-Disabling `strict` mode removes this safeguard, allowing any module to be imported into the `AppModule` regardless of `markAsGlobal`, increasing risk of bugs by exposing yourself to the above example.
+Disabling `strict` mode removes this safeguard, allowing any module to be imported into the `AppModule` regardless of `isGlobal`, increasing risk of bugs by exposing yourself to the above example.
 
 ## Unit Tests
 
@@ -468,13 +528,13 @@ class ApiService {
   private async sendToLocation(user: User, location: any): Promise<any> {}
 }
 
-const ApiModule = new ProviderModule({
-  identifier: Symbol('ApiModule'),
+const ApiModuleDefinition = new ProviderModuleDefinition({
+  identifier: 'ApiModule',
   providers: [UserService, ApiService],
 });
 
-const ApiModuleMocked = new ProviderModule({
-  identifier: Symbol('ApiModule_MOCK'),
+const ApiModuleDefinitionMocked = ApiModule.clone({
+  identifier: 'ApiModuleMocked',
   providers: [
     {
       provide: UserService,
@@ -492,7 +552,7 @@ const ApiModuleMocked = new ProviderModule({
 });
 ```
 
-Now what you have to do is just to provide the `ApiModuleMocked` instead of the `ApiModule` 😎
+Now what you have to do is just to provide the `ApiModuleDefinitionMocked` instead of the `ApiModuleDefinition` 😎
 
 ## Documentation
 
@@ -500,6 +560,34 @@ Comprehensive, auto-generated documentation is available at:
 
 👉 [https://adimarianmutu.github.io/x-injection/index.html](https://adimarianmutu.github.io/x-injection/index.html)
 
+## Conventions
+
+To create a stable experience across different projects, the following _conventions_ should be followed.
+
+### ProviderModule
+
+When instantiating a new `ProviderModule` class you should append `Module` to the `variable` name and its `identifier`:
+
+```ts
+const DatabaseModule = new ProviderModule({
+  identifier: 'DatabaseModule',
+});
+```
+
+### ProviderModuleDefinition
+
+When instantiating a new `ProviderModuleDefinition` class you should append `ModuleDef` to the `variable` name:
+
+> [!NOTE]
+>
+> _Do not append `Def` to the `identifier` as that will be inherit by the actual `ProviderModule`!_
+
+```ts
+const DatabaseModuleDef = new ProviderModuleDefinition({
+  identifier: 'DatabaseModule', // No `Def` here!
+});
+```
+
 ## ReactJS Implementation
 
 You want to use it within a [ReactJS](https://react.dev/) project? Don't worry, the library does already have an official implementation for React ⚛️
@@ -514,4 +602,6 @@ Please ensure your contributions adhere to the project's code style. See the rep
 
 ---
 
-> For questions, feature requests, or bug reports, feel free to open an [issue](https://github.com/AdiMarianMutu/x-injection/issues) on GitHub!
+> [!NOTE]
+>
+> **For questions, feature requests, or bug reports, feel free to open an [issue](https://github.com/AdiMarianMutu/x-injection/issues) on GitHub.**