feat: add ack support (#620)

Author: xiamu33

README.md

@@ -169,6 +169,25 @@ export class MessageController {
 }
 ```
 
+#### `@MessageAck()` decorator
+
+To get received message ack use `@MessageAck()` decorator:
+
+```typescript
+import { SocketController, OnMessage, MessageAck, MessageBody } from 'socket-controllers';
+
+@SocketController()
+export class MessageController {
+  @OnMessage('save')
+  save(@MessageBody() message: any, @MessageAck() ack: Function) {
+    console.log('received message: ', message);
+    ack('callback message');
+  }
+}
+```
+
+> note: ack must be the last parameter in `emit`, otherwise it will be `null`
+
 #### `@SocketQueryParam()` decorator
 
 To get received query parameter use `@SocketQueryParam()` decorator.

src/SocketControllers.ts

@@ -181,13 +181,14 @@ export class SocketControllers {
     for (const messageAction of messageActions) {
       socket.on(messageAction.options.name, (...args: any[]) => {
         const messages: any[] = args.slice(0, -1);
-        const ack: any = args[args.length - 1];
+        let ack: Function | null = args[args.length - 1];
 
         if (!(ack instanceof Function)) {
           messages.push(ack);
+          ack = null;
         }
 
-        void this.executeAction(socket, controller, messageAction, messageAction.options.name as string, messages);
+        void this.executeAction(socket, controller, messageAction, messageAction.options.name as string, messages, ack);
       });
     }
   }
@@ -197,9 +198,10 @@ export class SocketControllers {
     controller: HandlerMetadata<ControllerMetadata>,
     action: ActionMetadata,
     eventName?: string,
-    data?: any[]
+    data?: any[],
+    ack?: Function | null
   ) {
-    const parameters = this.resolveParameters(socket, controller.metadata, action.parameters || [], data);
+    const parameters = this.resolveParameters(socket, controller.metadata, action.parameters || [], data, ack);
 
     let container = this.container;
     if (this.options.scopedContainerGetter) {
@@ -263,12 +265,13 @@ export class SocketControllers {
     socket: Socket,
     controllerMetadata: ControllerMetadata,
     parameterMetadatas: ParameterMetadata[],
-    data?: any[]
+    data?: any[],
+    ack?: Function | null
   ) {
     const parameters = [];
 
     for (const metadata of parameterMetadatas) {
-      const parameterValue = this.resolveParameter(socket, controllerMetadata, metadata, data) as never;
+      const parameterValue = this.resolveParameter(socket, controllerMetadata, metadata, data, ack) as never;
       parameters[metadata.index] = this.transformActionValue(
         parameterValue,
         metadata.reflectedType as never,
@@ -280,7 +283,13 @@ export class SocketControllers {
     return parameters;
   }
 
-  private resolveParameter(socket: Socket, controller: ControllerMetadata, parameter: ParameterMetadata, data?: any[]) {
+  private resolveParameter(
+    socket: Socket,
+    controller: ControllerMetadata,
+    parameter: ParameterMetadata,
+    data?: any[],
+    ack?: Function | null
+  ) {
     switch (parameter.type) {
       case ParameterType.CONNECTED_SOCKET:
         return socket;
@@ -292,6 +301,8 @@ export class SocketControllers {
         return socket.rooms;
       case ParameterType.MESSAGE_BODY:
         return data?.[(parameter.options.index as number) || 0];
+      case ParameterType.MESSAGE_ACK:
+        return ack;
       case ParameterType.SOCKET_QUERY_PARAM:
         return socket.handshake.query[parameter.options.name as string];
       case ParameterType.SOCKET_REQUEST:

src/decorators/MessageAck.ts

@@ -0,0 +1,14 @@
+import { addParameterToActionMetadata } from '../util/add-parameter-to-action-metadata';
+import { ParameterType } from '../types/enums/ParameterType';
+
+export function MessageAck() {
+  return function (object: Object, methodName: string, index: number) {
+    const format = (Reflect as any).getMetadata('design:paramtypes', object, methodName)[index];
+    addParameterToActionMetadata(object.constructor, methodName, {
+      index,
+      reflectedType: format,
+      type: ParameterType.MESSAGE_ACK,
+      options: {},
+    });
+  };
+}

src/index.ts

@@ -2,6 +2,7 @@ export * from './decorators/ConnectedSocket';
 export * from './decorators/EmitOnFail';
 export * from './decorators/EmitOnSuccess';
 export * from './decorators/MessageBody';
+export * from './decorators/MessageAck';
 export * from './decorators/Middleware';
 export * from './decorators/NspParam';
 export * from './decorators/NspParams';

src/types/enums/ParameterType.ts

@@ -2,6 +2,7 @@ export enum ParameterType {
   CUSTOM,
   CONNECTED_SOCKET,
   MESSAGE_BODY,
+  MESSAGE_ACK,
   SOCKET_QUERY_PARAM,
   SOCKET_IO,
   SOCKET_ID,

test/functional/socket-message-ack.spec.ts

@@ -0,0 +1,121 @@
+import { createServer, Server as HttpServer } from 'http';
+import { Server } from 'socket.io';
+import { io, Socket } from 'socket.io-client';
+import { SocketControllers } from '../../src/SocketControllers';
+import { Container, Service } from 'typedi';
+import { SocketController } from '../../src/decorators/SocketController';
+import { OnConnect } from '../../src/decorators/OnConnect';
+import { ConnectedSocket } from '../../src/decorators/ConnectedSocket';
+import { waitForEvent } from '../utilities/waitForEvent';
+import { MessageAck, MessageBody, OnMessage, SocketId } from '../../src';
+
+describe('MessageAck', () => {
+  const PORT = 8080;
+  const PATH_FOR_CLIENT = `ws://localhost:${PORT}`;
+
+  let httpServer: HttpServer;
+  let wsApp: Server;
+  let wsClient: Socket;
+  let testResult;
+  let testAckResult;
+  let socketControllers: SocketControllers;
+
+  beforeEach(done => {
+    httpServer = createServer();
+    wsApp = new Server(httpServer, {
+      cors: {
+        origin: '*',
+      },
+    });
+    httpServer.listen(PORT, () => {
+      done();
+    });
+  });
+
+  afterEach(() => {
+    testResult = undefined;
+    testAckResult = undefined;
+
+    Container.reset();
+    wsClient.close();
+    wsClient = null;
+    socketControllers = null;
+    return new Promise(resolve => {
+      if (wsApp)
+        return wsApp.close(() => {
+          resolve(null);
+        });
+      resolve(null);
+    });
+  });
+
+  it('Event ack is retrieved correctly', async () => {
+    @SocketController('/string')
+    @Service()
+    class TestController {
+      @OnConnect()
+      connected(@ConnectedSocket() socket: Socket, @SocketId() socketId: string) {
+        testResult = socketId;
+        socket.emit('connected');
+      }
+
+      @OnMessage('test')
+      test(@MessageBody() data: any, @ConnectedSocket() socket: Socket, @MessageAck() ack: Function) {
+        testResult = data;
+        testAckResult = ack;
+        socket.emit('return');
+      }
+
+      @OnMessage('test2')
+      test2(
+        @MessageAck() ack: Function,
+        @MessageBody({ index: 1 }) data1: any,
+        @MessageBody({ index: 0 }) data0: any,
+        @ConnectedSocket() socket: Socket
+      ) {
+        testResult = { data1, data0 };
+        ack?.('test ack2');
+        socket.emit('return2');
+      }
+
+      @OnMessage('test3')
+      test3(
+        @ConnectedSocket() socket: Socket,
+        @MessageAck() ack: Function,
+        @MessageBody({ index: 1 }) data1: any,
+        @MessageBody({ index: 0 }) data0: any
+      ) {
+        testResult = { data1, data0 };
+        testAckResult = ack;
+        socket.emit('return3');
+      }
+    }
+
+    socketControllers = new SocketControllers({
+      io: wsApp,
+      container: Container,
+      controllers: [TestController],
+    });
+    wsClient = io(PATH_FOR_CLIENT + '/string', { reconnection: false, timeout: 5000, forceNew: true });
+
+    await waitForEvent(wsClient, 'connected');
+
+    const ack = (ack: any) => (testAckResult = ack);
+
+    wsClient.emit('test', 'test data');
+    await waitForEvent(wsClient, 'return');
+    expect(testResult).toEqual('test data');
+    expect(testAckResult).toBeNull();
+
+    wsClient.emit('test2', 'test data 0', 'test data 1', 'test data 2', ack);
+    await waitForEvent(wsClient, 'return2');
+    expect(testResult).toEqual({ data0: 'test data 0', data1: 'test data 1' });
+    expect(testAckResult).toEqual('test ack2');
+
+    // ack should be the last parameter
+    wsClient.emit('test3', 'test data 0', 'test data 1', ack, 'test data 2');
+    await waitForEvent(wsClient, 'return3');
+    expect(testResult).toEqual({ data0: 'test data 0', data1: 'test data 1' });
+    expect(testAckResult).toBeNull();
+  });
+});