Fet() Continue readme update

adrien2p · Jan 24, 2022 · 44ce1e0 · 44ce1e0
1 parent 682c80d
commit 44ce1e0
Show file tree

Hide file tree

Showing 33 changed files with 373 additions and 198 deletions.
diff --git a/README.md b/README.md
@@ -54,6 +54,8 @@ this is not a problem. Here is how you do that.
 In your project, create a file such as `main.ts`, then copy paste de code bellow.
 
 ````typescript
+// main.ts
+
 import express = require('express');
 import { Medusa } from 'medusa-extender';
 import { resolve } from 'path';
@@ -95,6 +97,93 @@ The code above allows you to manually launch the medusa engine and will load all
 with that in mind, you can organise your code as you want, the scanner will take care of recursively looking for those
 directories.
 
+## Medusa module
+
+This module is the main module that wee have seen above and that allow us to load
+medusa under the hood. But, it also allows you to add custom middleware that you
+would want to be used either before or after the authentication occured.
+
+<details>
+<summary>Click to see the middleware example</summary>
+
+<section>
+
+In this example, the middleware will be applied after the authentication flow.
+When the endpoint `POST /admin/users/` will be hit, a new `UserSubscriber` will be attach
+to the entity and the previous one will be removed, in order to refresh the injected cradle and get all scoped elements available in the services
+that will listen for the event that occured on the user entity.
+
+```typescript
+import { Express, NextFunction, Response } from 'express';
+import {
+    MedusaAuthenticatedRequest,
+    MedusaMiddleware,
+    MedusaResolverKeys,
+    MedusaRouteOptions,
+    MedusaUtils,
+} from 'medusa-extender';
+import { Connection } from 'typeorm';
+import Utils from '@core/utils';
+import UserSubscriber from '@modules/user/subscribers/user.subscriber';
+
+export default class AttachUserSubscribersMiddleware
+	implements MedusaMiddleware<typeof AttachUserSubscribersMiddleware>
+{
+    public static isPostAuth = true;
+    public static isHandledByMedusa = true;
+
+    public static get routesOptions(): MedusaRouteOptions {
+        return {
+            path: '/admin/users/',
+            method: 'post',
+        };
+    }
+
+    public consume(options: { app: Express }): (req: MedusaAuthenticatedRequest | Request, res: Response, next: NextFunction) => void | Promise<void> {
+        const routeOptions = AttachUserSubscribersMiddleware.routesOptions;
+        options.app.use((req: MedusaAuthenticatedRequest, res: Response, next: NextFunction): void => {
+            if (Utils.isExpectedRoute([routeOptions], req)) {
+                const { connection } = req.scope.resolve(MedusaResolverKeys.manager) as { connection: Connection };
+                MedusaUtils.attachOrReplaceEntitySubscriber(connection, UserSubscriber);
+            }
+            return next();
+        });
+
+        return (req: MedusaAuthenticatedRequest | Request, res: Response, next: NextFunction) => next();
+    }
+}
+```
+
+</section>
+</details>
+
+Then, to load the middlewares you have to update a bit you `main.ts` file like this
+
+```typescript
+// main.ts
+
+import express = require('express');
+import { Medusa } from 'medusa-extender';
+import { resolve } from 'path';
+import AttachUserSubscribersMiddleware from '@modules/user/middlewares/attachUserSubscribers.middleware';
+import config = require('./medusa-config');
+
+async function bootstrap() {
+    const expressInstance = express();
+
+    const rootDir = resolve(__dirname);
+    await new Medusa(rootDir, expressInstance)
+        .consume(AttachUserSubscribersMiddleware)
+        .load();
+
+    expressInstance.listen(config.serverConfig.port, () => {
+        console.log('The server is started');
+    });
+}
+
+bootstrap();
+```
+
 ## Entities
 
 there is two possibilities, you want either to create a new entity or to override an 

diff --git a/docs/README.md b/docs/README.md
@@ -56,6 +56,8 @@ this is not a problem. Here is how you do that.
 In your project, create a file such as `main.ts`, then copy paste de code bellow.
 
 ````typescript
+// main.ts
+
 import express = require('express');
 import { Medusa } from 'medusa-extender';
 import { resolve } from 'path';
@@ -97,6 +99,93 @@ The code above allows you to manually launch the medusa engine and will load all
 with that in mind, you can organise your code as you want, the scanner will take care of recursively looking for those
 directories.
 
+## Medusa module
+
+This module is the main module that wee have seen above and that allow us to load
+medusa under the hood. But, it also allows you to add custom middleware that you
+would want to be used either before or after the authentication occured.
+
+<details>
+<summary>Click to see the middleware example</summary>
+
+<section>
+
+In this example, the middleware will be applied after the authentication flow.
+When the endpoint `POST /admin/users/` will be hit, a new `UserSubscriber` will be attach
+to the entity and the previous one will be removed, in order to refresh the injected cradle and get all scoped elements available in the services
+that will listen for the event that occured on the user entity.
+
+```typescript
+import { Express, NextFunction, Response } from 'express';
+import {
+    MedusaAuthenticatedRequest,
+    MedusaMiddleware,
+    MedusaResolverKeys,
+    MedusaRouteOptions,
+    MedusaUtils,
+} from 'medusa-extender';
+import { Connection } from 'typeorm';
+import Utils from '@core/utils';
+import UserSubscriber from '@modules/user/subscribers/user.subscriber';
+
+export default class AttachUserSubscribersMiddleware
+	implements MedusaMiddleware<typeof AttachUserSubscribersMiddleware>
+{
+    public static isPostAuth = true;
+    public static isHandledByMedusa = true;
+
+    public static get routesOptions(): MedusaRouteOptions {
+        return {
+            path: '/admin/users/',
+            method: 'post',
+        };
+    }
+
+    public consume(options: { app: Express }): (req: MedusaAuthenticatedRequest | Request, res: Response, next: NextFunction) => void | Promise<void> {
+        const routeOptions = AttachUserSubscribersMiddleware.routesOptions;
+        options.app.use((req: MedusaAuthenticatedRequest, res: Response, next: NextFunction): void => {
+            if (Utils.isExpectedRoute([routeOptions], req)) {
+                const { connection } = req.scope.resolve(MedusaResolverKeys.manager) as { connection: Connection };
+                MedusaUtils.attachOrReplaceEntitySubscriber(connection, UserSubscriber);
+            }
+            return next();
+        });
+
+        return (req: MedusaAuthenticatedRequest | Request, res: Response, next: NextFunction) => next();
+    }
+}
+```
+
+</section>
+</details>
+
+Then, to load the middlewares you have to update a bit you `main.ts` file like this
+
+```typescript
+// main.ts
+
+import express = require('express');
+import { Medusa } from 'medusa-extender';
+import { resolve } from 'path';
+import AttachUserSubscribersMiddleware from '@modules/user/middlewares/attachUserSubscribers.middleware';
+import config = require('./medusa-config');
+
+async function bootstrap() {
+    const expressInstance = express();
+
+    const rootDir = resolve(__dirname);
+    await new Medusa(rootDir, expressInstance)
+        .consume(AttachUserSubscribersMiddleware)
+        .load();
+
+    expressInstance.listen(config.serverConfig.port, () => {
+        console.log('The server is started');
+    });
+}
+
+bootstrap();
+```
+
 ## Entities
 
 there is two possibilities, you want either to create a new entity or to override an 
@@ -137,8 +226,8 @@ import { Entity } from 'typeorm';
 
 @Entity()
 class User extends MedusaUser implements MedusaEntity<User, typeof MedusaUser> {
-	static overriddenType = MedusaUser;
-	static isHandledByMedusa = true;
+    static overriddenType = MedusaUser;
+    static isHandledByMedusa = true;
 }
 ```
 

diff --git a/docs/classes/decorators_onMedusaEvent_decorator.OnMedusaEvent.md b/docs/classes/decorators_onMedusaEvent_decorator.OnMedusaEvent.md
@@ -45,7 +45,7 @@
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:10](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L10)
+[src/decorators/onMedusaEvent.decorator.ts:10](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L10)
 
 ## Properties
 
@@ -55,7 +55,7 @@
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:8](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L8)
+[src/decorators/onMedusaEvent.decorator.ts:8](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L8)
 
 ___
 
@@ -65,7 +65,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:7](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L7)
+[src/decorators/onMedusaEvent.decorator.ts:7](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L7)
 
 ## Accessors
 
@@ -79,7 +79,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:18](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L18)
+[src/decorators/onMedusaEvent.decorator.ts:18](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L18)
 
 ___
 
@@ -93,7 +93,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:14](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L14)
+[src/decorators/onMedusaEvent.decorator.ts:14](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L14)
 
 ## Methods
 
@@ -120,7 +120,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:38](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L38)
+[src/decorators/onMedusaEvent.decorator.ts:38](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L38)
 
 ___
 
@@ -146,7 +146,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:26](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L26)
+[src/decorators/onMedusaEvent.decorator.ts:26](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L26)
 
 ___
 
@@ -173,7 +173,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:52](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L52)
+[src/decorators/onMedusaEvent.decorator.ts:52](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L52)
 
 ___
 
@@ -199,7 +199,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:34](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L34)
+[src/decorators/onMedusaEvent.decorator.ts:34](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L34)
 
 ___
 
@@ -226,7 +226,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:45](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L45)
+[src/decorators/onMedusaEvent.decorator.ts:45](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L45)
 
 ___
 
@@ -252,7 +252,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:30](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L30)
+[src/decorators/onMedusaEvent.decorator.ts:30](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L30)
 
 ___
 
@@ -280,7 +280,7 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:59](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L59)
+[src/decorators/onMedusaEvent.decorator.ts:59](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L59)
 
 ___
 
@@ -300,4 +300,4 @@ ___
 
 #### Defined in
 
-[src/decorators/onMedusaEvent.decorator.ts:22](https://github.com/adrien2p/medusa-extender/blob/c135947/src/decorators/onMedusaEvent.decorator.ts#L22)
+[src/decorators/onMedusaEvent.decorator.ts:22](https://github.com/adrien2p/medusa-extender/blob/682c80d/src/decorators/onMedusaEvent.decorator.ts#L22)