@adimm/x-injection 0.5.1 → 0.6.0

package/README.md

@@ -1,14 +1,15 @@
 <h1 align="center">
-xInjection&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injection" target="__blank" alt="Release Version"><img src="https://img.shields.io/npm/v/@adimm/x-injection?color=0476bc&label="></a>
-<img src="https://flat.badgen.net/npm/license/@adimm/x-injection" alt="License">
+xInjection&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injection" target="__blank" alt="Release Version"><img src="https://badgen.net/npm/v/@adimm/x-injection"></a>
+<img src="https://badgen.net/npm/license/@adimm/x-injection" alt="License">
+<a href="https://app.codecov.io/gh/AdiMarianMutu/x-injection" target="__blank" alt="Release Version"><img src="https://badgen.net/codecov/c/github/AdiMarianMutu/x-injection"></a>
 </h1>
 
 <p align="center">
 <a href="https://github.com/AdiMarianMutu/x-injection/actions/workflows/ci.yml?query=branch%3Amain" target="__blank"><img src="https://github.com/AdiMarianMutu/x-injection/actions/workflows/ci.yml/badge.svg?branch=main"></a>
 <a href="https://github.com/AdiMarianMutu/x-injection/actions/workflows/publish.yml" target="__blank"><img src="https://github.com/AdiMarianMutu/x-injection/actions/workflows/publish.yml/badge.svg"></a>
 <br>
-<img src="https://flat.badgen.net/bundlephobia/minzip/@adimm/x-injection">
-<a href="https://www.npmjs.com/package/@adimm/x-injection" target="__blank" alt="Monthly Downloads"><img src="https://flat.badgen.net/npm/dm/@adimm/x-injection"></a>
+<img src="https://badgen.net/bundlephobia/minzip/@adimm/x-injection">
+<a href="https://www.npmjs.com/package/@adimm/x-injection" target="__blank" alt="Monthly Downloads"><img src="https://badgen.net/npm/dm/@adimm/x-injection"></a>
 </p>
 
 ## Table of Contents
@@ -21,10 +22,15 @@ xInjection&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injection" targe
 - [Getting Started](#getting-started)
   - [Bootstrapping the AppModule](#bootstrapping-the-appmodule)
   - [Registering Global Providers](#registering-global-providers)
+  - [Registering Global Modules](#registering-global-modules)
   - [Injection Scope](#injection-scope)
+    - [Singleton](#singleton)
+    - [Transient](#transient)
+    - [Request](#request)
 - [Custom Provider Modules](#custom-provider-modules)
   - [Dynamic Exports](#dynamic-exports)
 - [Advanced Usage](#advanced-usage)
+- [Unit Tests](#unit-tests)
 - [Documentation](#documentation)
 - [ReactJS Implementation](#reactjs-implementation)
 - [Contributing](#contributing)
@@ -106,6 +112,29 @@ AppModule.register({
 
 Now, `LoggerService` and `ConfigService` can be injected anywhere in your app, including inside all `ProviderModules`.
 
+### Registering Global Modules
+
+You can also import entire modules into the `AppModule` like so:
+
+```ts
+const ConfigModule = new ProviderModule({
+  identifier: Symbol('ConfigModule'),
+  markAsGlobal: true,
+  providers: [
+    { provide: 'SECRET_TOKEN', useValue: '123' },
+    { provide: 'SECRET_TOKEN_2', useValue: 123 },
+  ],
+});
+
+AppModule.register({
+  imports: [ConfigModule],
+});
+```
+
+> **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!_
+>
+> **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!_
+
 ### Injection Scope
 
 There are mainly 3 first-class ways to set the [InjectionScope](https://adimarianmutu.github.io/x-injection/enums/InjectionScope.html) of a provider, and each one has an order priority.
@@ -134,6 +163,54 @@ The below list shows them in order of priority _(highest to lowest)_, meaning th
 
 > **Note:** _Imported modules/providers retain their original `InjectionScope`!_
 
+#### Singleton
+
+The [Singleton](https://adimarianmutu.github.io/x-injection/enums/InjectionScope.html#singleton) injection scope means that once a dependency has been resolved from within a module will be cached and further resolutions will use the value from the cache.
+
+Example:
+
+```ts
+expect(MyModule.get(MyProvider)).toBe(MyModule.get(MyProvider));
+// true
+```
+
+#### Transient
+
+The [Singleton](https://adimarianmutu.github.io/x-injection/enums/InjectionScope.html#transient) injection scope means that a _new_ instance of the dependency will be used whenever a resolution occurs.
+
+Example:
+
+```ts
+expect(MyModule.get(MyProvider)).toBe(MyModule.get(MyProvider));
+// false
+```
+
+#### Request
+
+The [Request](https://adimarianmutu.github.io/x-injection/enums/InjectionScope.html#request) injection scope means that the _same_ instance will be used when a resolution happens in the _same_ request scope.
+
+Example:
+
+```ts
+class Book {}
+
+class Box {
+  constructor(
+    private readonly book0: Book,
+    private readonly book1: Book
+  ) {}
+}
+
+const box0 = MyModule.get(Box);
+const box1 = MyModule.get(Box);
+
+expect(box0.book0).toBe(box0.book1);
+// true
+
+expect(box0.book0).toBe(box1.book0);
+// false
+```
+
 ## Custom Provider Modules
 
 You can define custom modules to encapsulate related providers and manage their scope:
@@ -304,6 +381,48 @@ const globalContainer = GlobalContainer || AppModule.toNaked().container;
 
 For advanced scenarios, `IProviderModuleNaked` exposes additional methods (prefixed with `__`) that wrap InversifyJS APIs, supporting native `xInjection` provider tokens and more.
 
+## Unit Tests
+
+It is very easy to create mock modules so you can use them in your unit tests.
+
+```ts
+class ApiService {
+  constructor(private readonly userService: UserService) {}
+
+  async sendRequest<T>(location: LocationParams): Promise<T> {
+    // Pseudo Implementation
+    return this.sendToLocation(user, location);
+  }
+
+  private async sendToLocation(user: User, location: any): Promise<any> {}
+}
+
+const ApiModule = new ProviderModule({
+  identifier: Symbol('ApiModule'),
+  providers: [UserService, ApiService],
+});
+
+const ApiModuleMocked = new ProviderModule({
+  identifier: Symbol('ApiModule_MOCK'),
+  providers: [
+    {
+      provide: UserService,
+      useClass: UserService_Mock,
+    },
+    {
+      provide: ApiService,
+      useValue: {
+        sendRequest: async (location) => {
+          console.log(location);
+        },
+      },
+    },
+  ],
+});
+```
+
+Now what you have to do is just to provide the `ApiModuleMocked` instead of the `ApiModule` 😎
+
 ## Documentation
 
 Comprehensive, auto-generated documentation is available at: