docs: Add troubleshooting section

blueprint.md

@@ -23,5 +23,6 @@
 {{ load:documentation/04-internal-modules.md }}
 {{ load:documentation/05-resources.md }}
 {{ load:documentation/07-discussions.md }}
+{{ load:documentation/12-troubleshooting.md }}
 {{ load:documentation/10-like-my-work.md }}
 {{ load:documentation/08-contribute.md }}

docs/README.md

@@ -88,6 +88,10 @@ decorators approach to increase the DX and full typings support for easier devel
 * [Resources](#resources)
 	* [Marketplace tutorial](#marketplace-tutorial)
 * [Discussions](#discussions)
+* [Troubleshooting](#troubleshooting)
+	* [Typings across libs](#typings-across-libs)
+		* [Problem](#problem)
+		* [Solution](#solution)
 * [Like my work? :heartbeat:](#like-my-work-heartbeat)
 * [Contribute](#contribute)
 
@@ -396,30 +400,6 @@ export class Product extends MedusaProduct {
 > The `override` parameter of the `@MedusaEntity` decorator allow to specify which entity
 > from the core must be overridden.
 
-To make your project aware of your customisation 
-at the medusa core level, you can use the [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html)
-approach.
-
-here is an example
-
-```ts
-// src/modules/your_modules/index.d.ts
-
-import { User as ExtendedUser } from '@modules/user/user.entity';
-import { default as ExtendedUserRepository } from '@modules/user/user.repository';
-
-declare module '@medusajs/medusa/dist/models/user' {
-  export declare class User extends ExtendedUser {}
-}
-
-declare module '@medusajs/medusa' {
-  export declare class UserRepository extends ExtendedUserRepository {}
-}
-
-```
-
-To see a live example, you can look at the starters, they include the module augmentation approach.
-
 ### @Repository
 
 This decorator gives you the ability to either create a new custom repository that will
@@ -933,7 +913,8 @@ export default class ProductSubscriber implements EntitySubscriberInterface<Prod
     }
 
     public async beforeInsert(event: InsertEvent<Product>): Promise<InsertEvent<Product>> {
-        return eventEmitter.emitAsync<InsertEvent<Product>>(OnMedusaEntityEvent.Before.InsertEvent(Product), {
+        const eventName = OnMedusaEntityEvent.Before.InsertEvent(User, UserService, 'attachStoreToUser');
+        await eventEmitter.emitAsync<InsertEvent<User>>(eventName, {
             event,
             transactionalEntityManager: event.manager,
         });
@@ -958,33 +939,6 @@ export default class ProductService extends MedusaProductService {
 }
 ```
 
-Here is how you can register it in medusa if your subscriber need to be scoped 
-- for example if the manager can be scoped like it is in a multi tenant application such as the one using the multi tenancy module).
-- if the service depends on scoped dependencies such as the logged in user.
-
-```typescript
-import { NextFunction, Response } from 'express';
-import {
-    MEDUSA_RESOLVER_KEYS,
-    MedusaAuthenticatedRequest,
-    MedusaMiddleware,
-    Middleware
-} from 'medusa-extender';
-import { Connection } from 'typeorm';
-import ProductSubscriber from './product.subscriber';
-
-@Middleware({ requireAuth: true, routes: [{ method: 'post', path: '/admin/products/' }] })
-export class AttachProductSubscribersMiddleware implements MedusaMiddleware {
-    public consume(req: MedusaAuthenticatedRequest, res: Response, next: NextFunction): void {
-        const { connection } = req.scope.resolve(MEDUSA_RESOLVER_KEYS.manager) as {
-            connection: Connection;
-        };
-        ProductSubscriber.attachTo(connection);
-        return next();
-    };
-}
-```
-
 And finally, we will add a new handler to listen to this particular event
 
 ```typescript
@@ -1254,6 +1208,59 @@ Here is the first tutorial using the medusa-extender package, [Open source ecomm
 
 If you are interesting to participate in any discussions you can follow that [links](https://github.com/adrien2p/medusa-extender/discussions)
 
+[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/cloudy.png)](#troubleshooting)
+
+# Troubleshooting
+
+In this section you will retrieve the information regarding problem that other user can encounter and how to tackle them.
+
+> NOTE: You are more than welcome to update or improve this section if you think that you have something that
+> can be useful for other users.
+> You can update the following file: documentation/12-troubleshooting.md
+
+
+[![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/cloudy.png)](#typings-across-libs)
+
+## Typings across libs
+
+### Problem
+
+When you are able to extends an object from an external lib (medusa here), typescript can't be aware of the fact that the object
+type has changed for the inner external lib as well.
+
+### Solution
+
+In that case, we have to use the approach providing by `declaration merging` and `module augmentation` (you can read more about
+it [here](https://www.typescriptlang.org/docs/handbook/declaration-merging.html))
+
+some example can be found in the [starter server](https://github.com/adrien2p/medusa-extender/blob/main/starters/server/src/modules/user/index.d.ts) as well
+as in the [starter module](https://github.com/adrien2p/medusa-extender/blob/main/starters/plugin-module/src/modules/user/index.d.ts)
+
+Case example: 
+
+you are extending an Entity that we will call `Foo`, the core typed everywhere using `Foo` which is of type `Foo`.
+in your project, you want to then extend a service related to `Foo`, the typings from the core can't be aware of the new 
+properties that you might have added to extend `Foo`.
+
+Therefore, when you want to consume a core method from medusa that return `Foo`
+it means that it return the original one, but only has the type, but in reality the returned result represent your extended `Foo`.
+In that case, we have to let typescript know that `Foo` has been extended and that the type must be merged everywhere it is used.
+
+this is what the following code will do with a user extension example:
+
+```ts
+import { default as ExtendedUserRepository } from './user.repository';
+
+declare module '@medusajs/medusa/dist/models/user' {
+    declare interface User {
+        store_id: string;
+    }
+}
+```
+
+As you can see, in order to tell typescript that the `user` as been extended, you have to specify which properties have been added.
+From there, typescript will be able to match and merge the types as you can see in that [example](https://github.com/adrien2p/medusa-extender/blob/main/starters/plugin-module/src/modules/user/user.service.ts)
+
 [![-----------------------------------------------------](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/cloudy.png)](#like-my-work-heartbeat)
 
 # Like my work? :heartbeat:

docs/classes/Medusa.Medusa-1.md

@@ -36,7 +36,7 @@ Load medusa and apply all components
 
 #### Defined in
 
-[src/Medusa.ts:39](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/Medusa.ts#L39)
+[src/Medusa.ts:39](https://github.com/adrien2p/medusa-extender/blob/9478406/src/Medusa.ts#L39)
 
 ## Properties
 
@@ -46,7 +46,7 @@ Load medusa and apply all components
 
 #### Defined in
 
-[src/Medusa.ts:32](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/Medusa.ts#L32)
+[src/Medusa.ts:32](https://github.com/adrien2p/medusa-extender/blob/9478406/src/Medusa.ts#L32)
 
 ___
 
@@ -56,7 +56,7 @@ ___
 
 #### Defined in
 
-[src/Medusa.ts:33](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/Medusa.ts#L33)
+[src/Medusa.ts:33](https://github.com/adrien2p/medusa-extender/blob/9478406/src/Medusa.ts#L33)
 
 ## Methods
 
@@ -76,4 +76,4 @@ ___
 
 #### Defined in
 
-[src/Medusa.ts:47](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/Medusa.ts#L47)
+[src/Medusa.ts:47](https://github.com/adrien2p/medusa-extender/blob/9478406/src/Medusa.ts#L47)

docs/classes/core_componentMap.ComponentMap.md

@@ -84,4 +84,4 @@ Map.get
 
 #### Defined in
 
-[src/core/componentMap.ts:4](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/componentMap.ts#L4)
+[src/core/componentMap.ts:4](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/componentMap.ts#L4)

docs/classes/core_event_emmiter.Internals.CustomEventEmmiter.md → docs/classes/core_event_emmiter.Internals.CustomEventEmitter.md

@@ -1,46 +1,46 @@
-[medusa-extender](../README.md) / [Exports](../modules.md) / [core/event-emmiter](../modules/core_event_emmiter.md) / [Internals](../modules/core_event_emmiter.Internals.md) / CustomEventEmmiter
+[medusa-extender](../README.md) / [Exports](../modules.md) / [core/event-emmiter](../modules/core_event_emmiter.md) / [Internals](../modules/core_event_emmiter.Internals.md) / CustomEventEmitter
 
-# Class: CustomEventEmmiter
+# Class: CustomEventEmitter
 
-[core/event-emmiter](../modules/core_event_emmiter.md).[Internals](../modules/core_event_emmiter.Internals.md).CustomEventEmmiter
+[core/event-emmiter](../modules/core_event_emmiter.md).[Internals](../modules/core_event_emmiter.Internals.md).CustomEventEmitter
 
 Extended event emitter to register methods that must be call when certain events are triggered and relay the handling to the API package
 
 ## Hierarchy
 
 - `EventEmitter`
 
-  ↳ **`CustomEventEmmiter`**
+  ↳ **`CustomEventEmitter`**
 
 ## Table of contents
 
 ### Constructors
 
-- [constructor](core_event_emmiter.Internals.CustomEventEmmiter.md#constructor)
+- [constructor](core_event_emmiter.Internals.CustomEventEmitter.md#constructor)
 
 ### Properties
 
-- [#listeners](core_event_emmiter.Internals.CustomEventEmmiter.md##listeners)
+- [#listeners](core_event_emmiter.Internals.CustomEventEmitter.md##listeners)
 
 ### Methods
 
-- [emitAsync](core_event_emmiter.Internals.CustomEventEmmiter.md#emitasync)
-- [register](core_event_emmiter.Internals.CustomEventEmmiter.md#register)
-- [registerListeners](core_event_emmiter.Internals.CustomEventEmmiter.md#registerlisteners)
+- [emitAsync](core_event_emmiter.Internals.CustomEventEmitter.md#emitasync)
+- [register](core_event_emmiter.Internals.CustomEventEmitter.md#register)
+- [registerListeners](core_event_emmiter.Internals.CustomEventEmitter.md#registerlisteners)
 
 ## Constructors
 
 ### constructor
 
-• **new CustomEventEmmiter**()
+• **new CustomEventEmitter**()
 
 #### Overrides
 
 EventEmitter.constructor
 
 #### Defined in
 
-[src/core/event-emmiter.ts:22](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/event-emmiter.ts#L22)
+[src/core/event-emmiter.ts:22](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/event-emmiter.ts#L22)
 
 ## Properties
 
@@ -50,7 +50,7 @@ EventEmitter.constructor
 
 #### Defined in
 
-[src/core/event-emmiter.ts:20](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/event-emmiter.ts#L20)
+[src/core/event-emmiter.ts:20](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/event-emmiter.ts#L20)
 
 ## Methods
 
@@ -79,7 +79,7 @@ Emit an asynchrone event entity based and wait for the result.
 
 #### Defined in
 
-[src/core/event-emmiter.ts:74](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/event-emmiter.ts#L74)
+[src/core/event-emmiter.ts:74](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/event-emmiter.ts#L74)
 
 ___
 
@@ -109,7 +109,7 @@ Register a new event handler.
 
 #### Defined in
 
-[src/core/event-emmiter.ts:32](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/event-emmiter.ts#L32)
+[src/core/event-emmiter.ts:32](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/event-emmiter.ts#L32)
 
 ___
 
@@ -132,4 +132,4 @@ Only unregister and register again non singleton based event listeners
 
 #### Defined in
 
-[src/core/event-emmiter.ts:45](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/event-emmiter.ts#L45)
+[src/core/event-emmiter.ts:45](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/event-emmiter.ts#L45)

docs/classes/core_logger.Logger.md

@@ -49,7 +49,7 @@ Internal logger to display information about the build.
 
 #### Defined in
 
-[src/core/logger.ts:20](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L20)
+[src/core/logger.ts:20](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L20)
 
 ## Properties
 
@@ -59,7 +59,7 @@ Internal logger to display information about the build.
 
 #### Defined in
 
-[src/core/logger.ts:10](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L10)
+[src/core/logger.ts:10](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L10)
 
 ___
 
@@ -69,7 +69,7 @@ ___
 
 #### Defined in
 
-[src/core/logger.ts:9](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L9)
+[src/core/logger.ts:9](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L9)
 
 ___
 
@@ -79,7 +79,7 @@ ___
 
 #### Defined in
 
-[src/core/logger.ts:8](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L8)
+[src/core/logger.ts:8](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L8)
 
 ## Accessors
 
@@ -93,7 +93,7 @@ ___
 
 #### Defined in
 
-[src/core/logger.ts:16](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L16)
+[src/core/logger.ts:16](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L16)
 
 ___
 
@@ -107,7 +107,7 @@ ___
 
 #### Defined in
 
-[src/core/logger.ts:12](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L12)
+[src/core/logger.ts:12](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L12)
 
 ## Methods
 
@@ -131,7 +131,7 @@ Build logs taking in count the level color
 
 #### Defined in
 
-[src/core/logger.ts:89](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L89)
+[src/core/logger.ts:89](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L89)
 
 ___
 
@@ -154,7 +154,7 @@ Display error logs in red immediately
 
 #### Defined in
 
-[src/core/logger.ts:66](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L66)
+[src/core/logger.ts:66](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L66)
 
 ___
 
@@ -170,7 +170,7 @@ display all queues logs and then reset the queue.
 
 #### Defined in
 
-[src/core/logger.ts:73](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L73)
+[src/core/logger.ts:73](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L73)
 
 ___
 
@@ -193,7 +193,7 @@ Display log immediately.
 
 #### Defined in
 
-[src/core/logger.ts:48](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L48)
+[src/core/logger.ts:48](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L48)
 
 ___
 
@@ -216,7 +216,7 @@ Push new logs to queue and then show them later on.
 
 #### Defined in
 
-[src/core/logger.ts:34](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L34)
+[src/core/logger.ts:34](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L34)
 
 ___
 
@@ -239,7 +239,7 @@ Display warning immediately.
 
 #### Defined in
 
-[src/core/logger.ts:57](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L57)
+[src/core/logger.ts:57](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L57)
 
 ___
 
@@ -260,4 +260,4 @@ ___
 
 #### Defined in
 
-[src/core/logger.ts:25](https://github.com/adrien2p/medusa-extender/blob/ad78501/src/core/logger.ts#L25)
+[src/core/logger.ts:25](https://github.com/adrien2p/medusa-extender/blob/9478406/src/core/logger.ts#L25)