feat: interceptor support (#631)

Author: attilaorosz

README.md

@@ -487,13 +487,13 @@ You can enable scoped controllers by providing a `scopedContainerGetter` functio
 
 You will get a new instance for each event in the controller.
 
-The `scopedContainerGetter` function receives a parameter which contains the socket, socket.io instance, event type, event name, namespace parameters and the message arguments if they are applicable.
+The `scopedContainerGetter` function receives the `SocketEventContext`.
 
 The `scopedContainerDisposer` function receives the container instance you created with `scopedContainerGetter` after the socket action is finished. Use this function to dispose the container if needed.
 
 ```typescript
 import 'reflect-metadata';
-import { SocketControllers, ScopedContainerGetterParams } from 'socket-controllers';
+import { SocketControllers, SocketEventContext } from 'socket-controllers';
 import { Container, ContainerInstance, Token } from "typedi";
 
 const myDiToken = new Token();
@@ -502,7 +502,7 @@ const myDiToken = new Token();
 const server = new SocketControllers({
    port: 3000,
    container: Container,
-   scopedContainerGetter: (args: ScopedContainerGetterParams) => {
+   scopedContainerGetter: (args: SocketEventContext) => {
       const container = Container.of(YOUR_REQUEST_CONTEXT);
       container.set(myDiToken, 'MY_VALUE');
       return container;
@@ -515,6 +515,56 @@ const server = new SocketControllers({
 });
 ```
 
+## Interceptors
+
+Interceptors allow you to wrap your event handlers in higher order functions.
+With interceptors you can add logging or modify the incoming or outgoing data for event handlers.
+
+```typescript
+import {
+   SocketController,
+   OnMessage,
+   EmitOnSuccess,
+   EmitOnFail,
+   SkipEmitOnEmptyResult,
+   UseInterceptor,
+   MessageBody
+} from 'socket-controllers';
+
+const interceptor: InterceptorInterface = {
+   use: (ctx: SocketEventContext, next: () => any) => {
+     ctx.messageArgs[0] = 'modified message from controller - ' + ctx.messageArgs[0];
+     const resp = next();
+     return 'modified response from controller - ' + resp; // modified response from controller - modified response from method - reponse
+   },
+};
+
+@Service()
+class Interceptor implements InterceptorInterface {
+   async use(ctx: SocketEventContext, next: () => any) {
+     ctx.messageArgs[0] = 'modified message from method - ' + ctx.messageArgs[0];
+     const resp = await next();
+     return 'modified response from method - ' + resp; // modified response from method - reponse
+   }
+}
+
+@SocketController()
+@UseInterceptor(interceptor)
+export class MessageController {
+   @OnMessage('get')
+   @EmitOnSuccess('get_success')
+   @SkipEmitOnEmptyResult()
+   @UseInterceptor(Interceptor)
+   get(@MessageBody() message: string): Promise<Message[]> {
+     console.log(message); // modified message from controller - modified message from method - original message
+     return 'response';
+   }
+}
+```
+
+Interceptors are executed in order of definition, starting with the controller interceptors.
+
+
 ## Decorators Reference
 
 | Signature                              | Description                                                                                                                                                                                                                                                                |

src/SocketControllers.ts

@@ -18,8 +18,10 @@ import { TransformOptions } from './types/TransformOptions';
 import { defaultTransformOptions } from './types/constants/defaultTransformOptions';
 import { ActionTransformOptions } from './types/ActionTransformOptions';
 import { instanceToPlain, plainToInstance } from 'class-transformer';
-import { ScopedContainerGetterParams } from './types/ScopedContainerGetterParams';
 import { MiddlewareInterface } from './types/MiddlewareInterface';
+import { InterceptorInterface } from './types/InterceptorInterface';
+import { chainExecute } from './util/chain-execute';
+import { SocketEventContext } from './types/SocketEventContext';
 
 export class SocketControllers {
   public container: { get<T>(someClass: { new (...args: any[]): T } | Function): T };
@@ -201,18 +203,44 @@ export class SocketControllers {
     data?: any[],
     ack?: Function | null
   ) {
-    const parameters = this.resolveParameters(socket, controller.metadata, action.parameters || [], data, ack);
+    const eventContext = this.resolveEventContext(
+      socket,
+      action.type,
+      eventName,
+      data,
+      controller.metadata.namespace,
+      ack
+    );
 
     let container = this.container;
     if (this.options.scopedContainerGetter) {
-      container = this.options.scopedContainerGetter(
-        this.collectScopedContainerParams(socket, action.type, eventName, data, controller.metadata.namespace)
-      );
+      container = this.options.scopedContainerGetter(eventContext);
     }
 
     try {
       const controllerInstance: any = container.get(controller.target);
-      const actionResult = controllerInstance[action.methodName](...parameters);
+
+      const actions = [
+        ...(action.interceptors || []).map(interceptor => {
+          return (
+            ((interceptor as any) instanceof Function
+              ? container.get(interceptor)
+              : interceptor) as InterceptorInterface
+          ).use.bind(interceptor);
+        }),
+        (context: SocketEventContext) => {
+          const parameters = this.resolveParameters(
+            socket,
+            controller.metadata,
+            action.parameters || [],
+            context.messageArgs,
+            ack
+          );
+          return controllerInstance[action.methodName](...parameters);
+        },
+      ];
+
+      const actionResult = chainExecute(eventContext, actions);
       const result = await Promise.resolve(actionResult);
       this.handleActionResult(socket, action, result, ResultType.EMIT_ON_SUCCESS);
     } catch (error: any) {
@@ -347,20 +375,22 @@ export class SocketControllers {
     return value;
   }
 
-  private collectScopedContainerParams(
+  private resolveEventContext(
     socket: Socket,
     eventType: SocketEventType,
     eventName?: string,
     messageBody?: any[],
-    namespace?: string | RegExp
-  ): ScopedContainerGetterParams {
+    namespace?: string | RegExp,
+    ack?: Function | null
+  ): SocketEventContext {
     return {
       eventType,
       eventName,
       socket,
       socketIo: this.io,
       nspParams: this.extractNamespaceParameters(socket, namespace),
       messageArgs: messageBody,
+      ack,
     };
   }
 

src/decorators/UseInterceptor.ts

@@ -0,0 +1,20 @@
+import { addInterceptorToActionMetadata } from '../util/add-interceptor-to-action-metadata';
+import { getMetadata } from '../util/get-metadata';
+import { ControllerMetadata } from '../types/ControllerMetadata';
+
+export function UseInterceptor(...interceptors: any[]): Function {
+  return function (object: Function | Object, methodName?: string) {
+    for (const interceptor of interceptors) {
+      if (object instanceof Function) {
+        // Class interceptor
+        const existingMetadata: ControllerMetadata = getMetadata(object);
+        for (const key of Object.keys(existingMetadata?.actions || {})) {
+          addInterceptorToActionMetadata(object, key, interceptor as Function);
+        }
+      } else {
+        // Method interceptor
+        addInterceptorToActionMetadata(object.constructor, methodName as string, interceptor as Function);
+      }
+    }
+  };
+}

src/index.ts

@@ -18,8 +18,10 @@ export * from './decorators/SocketRequest';
 export * from './decorators/SocketRooms';
 
 export * from './types/MiddlewareInterface';
+export * from './types/InterceptorInterface';
 export * from './types/TransformOptions';
 export * from './types/SocketControllersOptions';
 export * from './types/enums/SocketEventType';
+export * from './types/SocketEventContext';
 
 export * from './SocketControllers';

src/types/ActionMetadata.ts

@@ -8,4 +8,5 @@ export interface ActionMetadata {
   options: any;
   parameters: ParameterMetadata[];
   results: ResultMetadata[];
+  interceptors: Function[];
 }

src/types/InterceptorInterface.ts

@@ -0,0 +1,5 @@
+import { SocketEventContext } from './SocketEventContext';
+
+export interface InterceptorInterface {
+  use(context: SocketEventContext, next: () => any): any;
+}

src/types/SocketControllersOptions.ts

@@ -1,11 +1,11 @@
 import { Server } from 'socket.io';
 import { TransformOptions } from './TransformOptions';
-import { ScopedContainerGetterParams } from './ScopedContainerGetterParams';
+import { SocketEventContext } from './SocketEventContext';
 
 export interface SocketControllersOptions {
   container: { get<T>(someClass: { new (...args: any[]): T } | Function): T };
 
-  scopedContainerGetter?: (params: ScopedContainerGetterParams) => {
+  scopedContainerGetter?: (context: SocketEventContext) => {
     get<T>(someClass: { new (...args: any[]): T } | Function): T;
   };
 

src/types/ScopedContainerGetterParams.ts renamed to src/types/SocketEventContext.ts

@@ -1,11 +1,12 @@
 import { SocketEventType } from './enums/SocketEventType';
 import { Server, Socket } from 'socket.io';
 
-export interface ScopedContainerGetterParams {
+export interface SocketEventContext {
   socketIo: Server;
   socket: Socket;
   eventType: SocketEventType;
   eventName?: string;
   messageArgs?: any[];
   nspParams?: Record<string, string>;
+  ack?: Function | null;
 }

src/util/add-interceptor-to-action-metadata.ts

@@ -0,0 +1,21 @@
+import { SOCKET_CONTROLLER_META_KEY } from '../types/SocketControllerMetaKey';
+import { getMetadata } from './get-metadata';
+import { ControllerMetadata } from '../types/ControllerMetadata';
+
+export const addInterceptorToActionMetadata = (target: Function, methodName: string, interceptor: Function) => {
+  const existingMetadata = getMetadata<any, ControllerMetadata>(target);
+  (Reflect as any).defineMetadata(
+    SOCKET_CONTROLLER_META_KEY,
+    {
+      ...existingMetadata,
+      actions: {
+        ...existingMetadata?.actions,
+        [methodName]: {
+          ...existingMetadata?.actions?.[methodName],
+          interceptors: [interceptor, ...(existingMetadata?.actions?.[methodName]?.interceptors || [])],
+        },
+      },
+    },
+    target
+  );
+};

src/util/chain-execute.ts

@@ -0,0 +1,11 @@
+export function chainExecute(context: any, chain: Function[]) {
+  function next() {
+    const middleware: Function = chain.shift() as Function;
+
+    if (middleware && typeof middleware === 'function') {
+      return middleware(context, next);
+    }
+  }
+
+  return next();
+}