@adimm/x-injection 2.0.3 → 2.1.0

package/README.md

@@ -41,6 +41,7 @@ xInjection&nbsp;<a href="https://www.npmjs.com/package/@adimm/x-injection" targe
 - [Blueprints](#blueprints-1)
   - [Import Behavior](#import-behavior)
   - [isGlobal](#isglobal)
+  - [Definitions](#definitions)
 - [Advanced Usage](#advanced-usage)
   - [Events](#events)
   - [Middlewares](#middlewares)
@@ -309,7 +310,7 @@ 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 RainModuleDef = new ProviderModuleDef({
-     identifier: 'RainModule',
+     id: 'RainModule',
      defaultScope: InjectionScope.Transient,
    });
    ```
@@ -408,6 +409,7 @@ A [ProviderToken](https://adimarianmutu.github.io/x-injection/types/ProviderToke
   const THEY_MAY_KNOW_PROVIDER = { provide: CONSTANT_SECRET_PROVIDER, useValue: 'Maybe they know?' };
 
   // As you can see we now have 2 different ProviderTokens which use the same `provide` key.
+  // This means that resolving the `CONSTANT_SECRET_PROVIDER` will return an array of strings.
   ```
 
 - [ProviderFactoryToken](https://adimarianmutu.github.io/x-injection/types/ProviderFactoryToken.html)
@@ -475,6 +477,45 @@ MyModule.update.addProvider(PizzaService, true);
 MyModule.update.addProvider({ provide: HumanService, useClass: FemaleService });
 ```
 
+Now you may probably ask yourself `If we import with the 'addImport' method a new module into an already imported module, will we have access to the providers of that newly imported module?`
+
+The ansuwer is `yes`, we do have access thanks to the _dynamic_ nature of the `ProviderModule` class. Meaning that doing the following will work as expected:
+
+```ts
+const InnerModule = ProviderModule.create({
+  id: 'InnerModule',
+  providers: [FirstService],
+  exports: [FirstService],
+});
+
+const OuterModule = ProviderModule.create({
+  id: 'OuterModule',
+  imports: [InnerModule],
+});
+
+const UnknownModule = ProviderModule.create({
+  id: 'UnknownModule',
+  providers: [SecondService],
+  exports: [SecondService],
+});
+
+InnerModule.update.addImport(UnknownModule, true); // Don't forget to provide `true` to the `addToExports` optional parameter!
+
+const secondService = OuterModule.get(SecondService);
+```
+
+The `OuterModule` has now access to the `UnknownModule` exports because it has been _dynamically_ imported _(later at run-time)_ into the `InnerModule` _(which has been imported into `OuterModule` during the `bootstrap` phase)_
+
+Basically what happens is that when a `module` is imported, it takes care of _notify_ the `host` module if its _definiton_ changed.
+
+> [!WARNING]
+>
+> This is a very powerful feature which comes in with some costs, _most of the time negligible_, but if you have an app which has thousand and thousand of `modules` doing this type of _dynamic_ behavior, you may incur in some performance issues which will require proper design to keep under control.
+>
+> _Most of the times the best solution is to leverage the nature of `blueprints`._
+
+---
+
 Sometimes you may actually want to _lazy_ import a `module` from a _file_, this can be done very easily with `xInjection`:
 
 ```ts
@@ -490,25 +531,21 @@ Sometimes you may actually want to _lazy_ import a `module` from a _file_, this
 >
 > This design pattern is _extremely_ powerful and useful when you may have a lot of `modules` initializing during the app bootstrap process as you can defer their initialization, or even never load them if the user never needs those specific `modules` _(this is mostly applicable on the client-side rather than the server-side)_
 
-Keep reading to understand how you can defer initialization of the modules _both_ `client-side` and `server-side`.
+Keep reading to understand how you can defer initialization of the `modules` by using `blueprints`.
 
 ## Blueprints
 
 The [ProviderModuleBlueprint](https://adimarianmutu.github.io/x-injection/classes/ProviderModuleBlueprint.html) `class` main purpose is to encapsulate the `definitions` of a `Module`, when you do `ProviderModule.blueprint({...})` you are _not_ actually creating an instance of the `ProviderModule` class, but an instance of the `ProviderModuleBlueprint` class.
 
-Before diving into some examples, let's first clarify some important aspects about the behavior of the `blueprint` class.
+> To better understand the above concept; imagine the `blueprint` as being a _dormant_ _(static)_ `module` which is not fully awake _(dynamic)_ till it is actually _imported_ into a `module`.
 
 ### Import Behavior
 
 Whenever you _import_ a `blueprint` into a `module`, it'll automatically be "transformed" to a `ProviderModule` instance by the engine, this step is crucial as a `blueprint` per se does not contain a _container_, just its _definitions_.
 
-This has a "gotcha", because the conversion happens internally, you'll "not" be able to get a reference to that imported module, not directly at least _(I may change this in a future patch)_, this means that if you don't have the reference of the `ProviderModule`, you can't remove it from the _imported_ module _(if you'll ever need to remove it)_.
-
 > [!NOTE]
 >
-> There's currently an workaround for this, you can `subscribe` to the `Import` event and get from there the `ProviderModule` instance, just make sure to check the `id` of the module via `module.toString()` when doing so.
-
-It is also important, to understand the _injection_ `scope` of an imported `blueprint`; we previously learned that when we import a `blueprint` into a `module` it automatically creates an instance of the `ProviderModule` from it, this means that all the `singleton` providers of the `blueprint` definition are now _scoped singleton_, where _scoped_ means _singleton in relation to their imported module_.
+> Therefore it is important to understand the _injection_ `scope` of an imported `blueprint`; we previously learned that when we import a `blueprint` into a `module` it automatically creates an instance of the `ProviderModule` from it, this means that all the `singleton` providers of the `blueprint` definition are now _scoped singleton_, where _scoped_ means _singleton in relation to their imported module_.
 
 ### isGlobal
 
@@ -522,7 +559,7 @@ Now you can decide when to import it into the `AppModule` by doing `AppModule.ad
 
 ---
 
-I highly recommend to take advantage of the `blueprints` nature in order to plan-ahead your `modules` and import them wherever you have to import only when needed;
+I highly recommend to take advantage of the `blueprints` nature in order to plan-ahead your `modules`;
 
 Why?
 
@@ -530,6 +567,31 @@ Why?
 - To reuse module _definitions across_ different parts of your application while maintaining isolated instances. _(when possible/applicable)_
 - To _compose modules flexibly_, allowing you to adjust module dependencies dynamically before instantiation.
 
+### Definitions
+
+After you have provided the _initial_ `definitons` of a `blueprint`, you can always modify them with the [updateDefinition](https://adimarianmutu.github.io/x-injection/classes/ProviderModuleBlueprint.html#updatedefinition) `method`.
+
+> [!NOTE]
+>
+> Updating the `definitions` of a `blueprint` after has been _imported_ into a `module` will **_not_** propagate those changes to the `module` where it has been imported.
+
+---
+
+This means that we can actually _leverage_ the `blueprints` nature to _defer_ the actual initialization of a `module` by doing so:
+
+```ts
+const UserModuleBp = ProviderModule.blueprint({
+  id: 'UserModule',
+  ...
+});
+
+// Later in your code
+
+const UserModule = ProviderModule.create(UserModuleBp);
+```
+
+The `UserModule` will be created only when _necessary_ and it'll use the same exact definitons which are available into the `UserModuleBp` at the time of the `create` invokation.
+
 ## Advanced Usage
 
 > [!WARNING]
@@ -746,7 +808,7 @@ const ApiModuleBp = new ProviderModule.blueprint({
 
 // Clone returns a `deep` clone and wraps all the `methods` to break their reference!
 const ApiModuleBpMocked = ApiModuleBp.clone().updateDefinition({
-  identifier: 'ApiModuleMocked',
+  id: 'ApiModuleMocked',
   providers: [
     {
       provide: UserService,

package/dist/index.cjs

@@ -17,11 +17,11 @@ var e, t = Object.defineProperty, i = Object.getOwnPropertyDescriptor, o = Objec
     InjectFromBase: () => N,
     Injectable: () => q,
     InjectionError: () => I,
-    InjectionProviderModuleDisposedError: () => P,
+    InjectionProviderModuleDisposedError: () => w,
     InjectionProviderModuleError: () => b,
     InjectionProviderModuleMissingIdentifierError: () => x,
     InjectionProviderModuleMissingProviderError: () => E,
-    InjectionProviderModuleUnknownProviderError: () => w,
+    InjectionProviderModuleUnknownProviderError: () => P,
     InjectionScope: () => u,
     MiddlewareType: () => a,
     MultiInject: () => U,
@@ -194,7 +194,7 @@ var g, I = class e extends Error {
         } catch {}
         super(`{ProviderModule.${i}} => ${t}`);
     }
-}, w = class e extends b {
+}, P = class e extends b {
     static {
         n(this, "InjectionProviderModuleUnknownProviderError");
     }
@@ -202,7 +202,7 @@ var g, I = class e extends Error {
     constructor(e, t) {
         super(e, `The [${h.providerTokenToString(t)}] provider is of an unknown type!`);
     }
-}, P = class e extends b {
+}, w = class e extends b {
     static {
         n(this, "InjectionProviderModuleDisposedError");
     }
@@ -270,7 +270,7 @@ var g, I = class e extends Error {
                 return t.useFactory(...i);
             }))), "bind")
         } ], {bind: o} = i.find((({providerTypeMatches: t}) => t(e))) ?? {};
-        if (!o) throw new w(this.providerModule, e);
+        if (!o) throw new P(this.providerModule, e);
         const r = h.isProviderIdentifier(e);
         let s = o();
         if (h.isValueToken(e) || r || (s = this.setBindingScope(e, s)), r) return;
@@ -388,7 +388,7 @@ var g, I = class e extends Error {
         return this.providerModule.moduleContainer;
     }
     get subscribe() {
-        if (null === this.event$) throw new P(this.providerModule);
+        if (null === this.event$) throw new w(this.providerModule);
         return this.event$.subscribe.bind(this.event$);
     }
     moduleDef;
@@ -444,22 +444,24 @@ var g, I = class e extends Error {
         this.addProvider(i, t);
     }
     removeImport(e) {
-        if (!this.moduleDef.imports.has(e)) return !1;
-        if (!1 === this.providerModule.middlewaresManager.applyMiddlewares(a.BeforeRemoveImport, e)) return !1;
-        this.unsubscribeFromImportedModuleEvents(e);
-        return this.providerModule.importedModuleContainers.get(e).dispose(), this.providerModule.importedModuleContainers.delete(e), 
-        this.moduleDef.imports.delete(e), this.emitEventSafely({
+        const t = g.isModule(e) ? e : this.getImportedModuleById(e);
+        if (!t) return !1;
+        if (!1 === this.providerModule.middlewaresManager.applyMiddlewares(a.BeforeRemoveImport, t)) return !1;
+        this.unsubscribeFromImportedModuleEvents(t);
+        return this.providerModule.importedModuleContainers.get(t).dispose(), this.providerModule.importedModuleContainers.delete(t), 
+        this.moduleDef.imports.delete(t), this.emitEventSafely({
             type: p.ImportRemoved,
-            change: e
-        }), this.removeFromExports(e), !0;
+            change: t
+        }), this.removeFromExports(t), !0;
     }
     removeProvider(e) {
-        if (!this.moduleDef.providers.has(e)) return !1;
-        return !1 !== this.providerModule.middlewaresManager.applyMiddlewares(a.BeforeRemoveProvider, e) && (this.moduleDef.providers.delete(e), 
-        this.moduleContainer.container.unbindSync(h.toProviderIdentifier(e)), this.emitEventSafely({
+        const t = h.isProviderIdentifier(e) ? this.getProviderByIdentifier(e) : e;
+        if (!t) return !1;
+        return !1 !== this.providerModule.middlewaresManager.applyMiddlewares(a.BeforeRemoveProvider, t) && (this.moduleDef.providers.delete(t), 
+        this.moduleContainer.container.unbindSync(h.toProviderIdentifier(t)), this.emitEventSafely({
             type: p.ProviderRemoved,
-            change: e
-        }), this.removeFromExports(e), !0);
+            change: t
+        }), this.removeFromExports(t), !0);
     }
     removeFromExports(e) {
         if (!this.moduleDef.exports.has(e)) return !1;
@@ -475,6 +477,12 @@ var g, I = class e extends Error {
             change: e
         }), !0);
     }
+    getImportedModuleById(e) {
+        return this.moduleDef.imports.values().find((t => t.id === e));
+    }
+    getProviderByIdentifier(e) {
+        return this.moduleDef.providers.values().find((t => h.toProviderIdentifier(t) === e));
+    }
     emitEventSafely(e) {
         if (!this.emittingModules.has(this.providerModule)) try {
             this.emittingModules.add(this.providerModule), this.event$.emit(e);
@@ -535,7 +543,7 @@ var g, I = class e extends Error {
         i ? i.push(t) : this.middlewaresMap.set(e, [ t ]);
     }
     applyMiddlewares(e, ...t) {
-        if (null === this.middlewaresMap) throw new P(this.providerModule);
+        if (null === this.middlewaresMap) throw new w(this.providerModule);
         const i = this.middlewaresMap.get(e);
         switch (e) {
           case a.BeforeAddImport:
@@ -709,7 +717,7 @@ var g, I = class e extends Error {
         if (!this.options.id || 0 === this.options.id.toString().trim().length) throw new x(this);
     }
     throwIfDisposed() {
-        if (this.isDisposed) throw new P(this);
+        if (this.isDisposed) throw new w(this);
     }
 };