@tsed/socketio 8.0.0 → 8.0.2

package/src/decorators/socketUseAfter.spec.ts

@@ -0,0 +1,38 @@
+import {Store} from "@tsed/core";
+
+import {SocketUseAfter} from "../index.js";
+
+describe("@SocketUseAfter", () => {
+  describe("when the decorator is used on a class", () => {
+    beforeAll(() => {});
+
+    it("should store metadata", () => {
+      class Test {}
+
+      const middleware: any = () => {};
+      SocketUseAfter(middleware)(Test);
+
+      expect(Store.from(Test).get("socketIO")).toEqual({
+        useAfter: [middleware]
+      });
+    });
+  });
+
+  describe("when the decorator is used on a method", () => {
+    it("should store metadata", () => {
+      class Test {}
+
+      const middleware: any = () => {};
+
+      SocketUseAfter(middleware)(Test, "test", {});
+
+      expect(Store.from(Test).get("socketIO")).toEqual({
+        handlers: {
+          test: {
+            useAfter: [middleware]
+          }
+        }
+      });
+    });
+  });
+});

package/src/decorators/socketUseAfter.ts

@@ -0,0 +1,69 @@
+import {Store, Type} from "@tsed/core";
+
+/**
+ * Attach a Socket Middleware to a method or a class.
+ *
+ * ### Example
+ *
+ * A middleware can be also used on a `SocketService` either on a class or on a method.
+ *
+ * Here an example of a middleware:
+ *
+ * ```typescript
+ * import {SocketMiddlewareError, SocketErr, Socket, Args} from "@tsed/socketio";
+ *
+ * @SocketMiddlewareError()
+ * export class ErrorHandlerSocketMiddleware {
+ *    async use(@SocketErr() err: any, @Socket socket: SocketIO.Socket) {
+ *        console.error(err);
+ *        socket.emit("error", {message: "An error has occured"})
+ *    }
+ * }
+ * ```
+ *
+ * Then:
+ *
+ * ```typescript
+ * import {SocketService, SocketUseAfter, SocketUseBefore, Emit, Input, Args} from "@tsed/socketio";
+ * import {ErrorHandlerSocketMiddleware} from "../middlewares.js";
+ * import {User} from "../models/User.js";
+ *
+ * @SocketService("/my-namespace")
+ * @SocketUseAfter(ErrorHandlerSocketMiddleware) // global version
+ * export class MySocketService {
+ *
+ *    @Input("eventName")
+ *    @Emit("responseEventName") // or Broadcast or BroadcastOthers
+ *    @SocketUseAfter(ErrorHandlerSocketMiddleware)
+ *    async myMethod(@Args(0) userName: User) {
+ *
+ *        console.log(user);
+ *        throw new Error("Error");
+ *
+ *        return user;
+ *    }
+ * }
+ * ```
+ *
+ * @returns {(target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void}
+ * @decorator
+ * @experimental
+ * @param middlewares
+ */
+export function SocketUseAfter(...middlewares: Type<any>[]) {
+  return (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => {
+    if (propertyKey) {
+      Store.from(target).merge("socketIO", {
+        handlers: {
+          [propertyKey]: {
+            useAfter: middlewares
+          }
+        }
+      });
+    } else {
+      Store.from(target).merge("socketIO", {
+        useAfter: middlewares
+      });
+    }
+  };
+}

package/src/decorators/socketUseBefore.spec.ts

@@ -0,0 +1,34 @@
+import {Store} from "@tsed/core";
+
+import {SocketUseBefore} from "../index.js";
+
+describe("@SocketUseBefore", () => {
+  describe("when the decorator is used on a class", () => {
+    it("should store metadata", () => {
+      class Test {}
+      const middleware: any = () => {};
+      SocketUseBefore(middleware)(Test);
+
+      expect(Store.from(Test).get("socketIO")).toEqual({
+        useBefore: [middleware]
+      });
+    });
+  });
+
+  describe("when the decorator is used on a method", () => {
+    it("should store metadata", () => {
+      class Test {}
+      const middleware: any = () => {};
+
+      SocketUseBefore(middleware)(Test, "test", {});
+
+      expect(Store.from(Test).get("socketIO")).toEqual({
+        handlers: {
+          test: {
+            useBefore: [middleware]
+          }
+        }
+      });
+    });
+  });
+});

package/src/decorators/socketUseBefore.ts

@@ -0,0 +1,73 @@
+import {Store, Type} from "@tsed/core";
+
+/**
+ * Attach a Socket Middleware to a method or a class.
+ *
+ * ### Example
+ *
+ * A middleware can be also used on a `SocketService` either on a class or on a method.
+ *
+ * Here an example of a middleware:
+ *
+ * ```typescript
+ * @SocketMiddleware()
+ * export class UserConverterSocketMiddleware {
+ *     constructor(private converterService: ConverterService) {
+ *     }
+ *     async use(@Args() args: any[]) {
+ *
+ *         let [user] = args;
+ *         // update Arguments
+ *         user = ConverterService.deserialize(user, User);
+ *
+ *         return [user];
+ *     }
+ * }
+ * ```
+ * > The user instance will be forwarded to the next middleware and to your decorated method.
+ *
+ * Then:
+ *
+ * ```typescript
+ * import {SocketService, SocketUseAfter, SocketUseBefore, Emit, Input, Args} from "@tsed/socketio";
+ * import {UserConverterSocketMiddleware} from "../middlewares.js";
+ * import {User} from "../models/User.js";
+ *
+ * @SocketService("/my-namespace")
+ * @SocketUseBefore(UserConverterSocketMiddleware) // global version
+ * export class MySocketService {
+ *
+ *    @Input("eventName")
+ *    @Emit("responseEventName") // or Broadcast or BroadcastOthers
+ *    @SocketUseBefore(UserConverterSocketMiddleware)
+ *    async myMethod(@Args(0) user: User) {
+ *
+ *        console.log(user);
+ *
+ *        return user;
+ *    }
+ * }
+ * ```
+ *
+ * @returns {(target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => void}
+ * @decorator
+ * @experimental
+ * @param middlewares
+ */
+export function SocketUseBefore(...middlewares: Type<any>[]) {
+  return (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => {
+    if (propertyKey) {
+      Store.from(target).merge("socketIO", {
+        handlers: {
+          [propertyKey]: {
+            useBefore: middlewares
+          }
+        }
+      });
+    } else {
+      Store.from(target).merge("socketIO", {
+        useBefore: middlewares
+      });
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./class/SocketHandlersBuilder.js";
+export * from "./class/SocketProviderMetadata.js";
+export * from "./class/SocketSessionData.js";
+export * from "./constants/constants.js";
+export * from "./decorators/args.js";
+export * from "./decorators/broadcast.js";
+export * from "./decorators/broadcastOthers.js";
+export * from "./decorators/emit.js";
+export * from "./decorators/input.js";
+export * from "./decorators/inputAndBroadcast.js";
+export * from "./decorators/inputAndBroadcastOthers.js";
+export * from "./decorators/inputAndEmit.js";
+export * from "./decorators/io.js";
+export * from "./decorators/nsp.js";
+export * from "./decorators/reason.js";
+export * from "./decorators/socket.js";
+export * from "./decorators/socketErr.js";
+export * from "./decorators/socketEventName.js";
+export * from "./decorators/socketFilter.js";
+export * from "./decorators/socketMiddleware.js";
+export * from "./decorators/socketMiddlewareError.js";
+export * from "./decorators/socketNsp.js";
+export * from "./decorators/socketReturns.js";
+export * from "./decorators/socketService.js";
+export * from "./decorators/socketSession.js";
+export * from "./decorators/socketUseAfter.js";
+export * from "./decorators/socketUseBefore.js";
+export * from "./interfaces/interfaces.js";
+export * from "./interfaces/OnNamespaceInit.js";
+export * from "./interfaces/SocketFilters.js";
+export * from "./interfaces/SocketHandlerMetadata.js";
+export * from "./interfaces/SocketInjectableNsp.js";
+export * from "./interfaces/SocketParamMetadata.js";
+export * from "./interfaces/SocketProviderTypes.js";
+export * from "./interfaces/SocketReturnsTypes.js";
+export * from "./services/SocketIOServer.js";
+export * from "./services/SocketIOService.js";
+export * from "./SocketIOModule.js";

package/src/interfaces/OnNamespaceInit.ts

@@ -0,0 +1,8 @@
+import {Namespace} from "socket.io";
+
+/**
+ *
+ */
+export interface OnNamespaceInit {
+  $onNamespaceInit(nsp: Namespace): void;
+}

package/src/interfaces/SocketFilters.ts

@@ -0,0 +1,14 @@
+/**
+ * @ignore
+ */
+export enum SocketFilters {
+  ARGS = "args",
+  SOCKET = "socket",
+  EVENT_NAME = "eventName",
+  NSP = "nsp",
+  SESSION = "session",
+  RAW_SESSION = "raw_session",
+  ERR = "error",
+  SOCKET_NSP = "socket_nsp",
+  REASON = "reason"
+}

package/src/interfaces/SocketHandlerMetadata.ts

@@ -0,0 +1,17 @@
+import {SocketParamMetadata} from "./SocketParamMetadata.js";
+import {SocketReturnsTypes} from "./SocketReturnsTypes.js";
+
+/**
+ *
+ */
+export interface SocketHandlerMetadata {
+  eventName?: string;
+  methodClassName: string;
+  useBefore?: any[];
+  useAfter?: any[];
+  parameters?: {[key: number]: SocketParamMetadata};
+  returns?: {
+    type: SocketReturnsTypes;
+    eventName: string;
+  };
+}

package/src/interfaces/SocketInjectableNsp.ts

@@ -0,0 +1,4 @@
+export interface SocketInjectableNsp {
+  propertyKey: string;
+  nsp?: string | RegExp;
+}

package/src/interfaces/SocketParamMetadata.ts

@@ -0,0 +1,9 @@
+import {MetadataTypes} from "@tsed/core";
+
+import {SocketFilters} from "./SocketFilters.js";
+
+export interface SocketParamMetadata extends Partial<MetadataTypes> {
+  filter: SocketFilters;
+  mapIndex?: number;
+  useMapper?: boolean;
+}

package/src/interfaces/SocketProviderTypes.ts

@@ -0,0 +1,7 @@
+/**
+ *
+ */
+export enum SocketProviderTypes {
+  SERVICE = "service",
+  MIDDLEWARE = "middleware"
+}

package/src/interfaces/SocketReturnsTypes.ts

@@ -0,0 +1,8 @@
+/**
+ * @ignore
+ */
+export enum SocketReturnsTypes {
+  BROADCAST = "broadcast",
+  BROADCAST_OTHERS = "broadcastOthers",
+  EMIT = "emit"
+}

package/src/interfaces/interfaces.ts

@@ -0,0 +1,9 @@
+import SocketIO from "socket.io";
+
+declare global {
+  namespace TsED {
+    interface Configuration {
+      socketIO: Partial<SocketIO.ServerOptions>;
+    }
+  }
+}

package/src/services/SocketIOServer.spec.ts

@@ -0,0 +1,33 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {Server, SocketIOServer} from "./SocketIOServer.js";
+
+describe("SocketIOServer", () => {
+  describe("when there is configuration", () => {
+    beforeEach(() =>
+      PlatformTest.create({
+        socketIO: {
+          path: "/api/ws"
+        }
+      })
+    );
+    afterEach(PlatformTest.reset);
+
+    it("should inject the SocketIO server", () => {
+      const server = PlatformTest.get<SocketIOServer>(SocketIOServer);
+
+      expect(server).toBeInstanceOf(Server);
+    });
+  });
+
+  describe("when there is no configuration", () => {
+    beforeEach(() => PlatformTest.create({}));
+    afterEach(PlatformTest.reset);
+
+    it("should inject the SocketIO server", () => {
+      const server = PlatformTest.get<SocketIOServer>(SocketIOServer);
+
+      expect(server).toBeInstanceOf(Server);
+    });
+  });
+});

package/src/services/SocketIOServer.ts

@@ -0,0 +1,15 @@
+import {constant, injectable} from "@tsed/di";
+import {Server, type ServerOptions} from "socket.io";
+
+export type SocketIOServer = Server;
+
+// tslint:disable-next-line: variable-name
+export const SocketIOServer = Server;
+
+injectable(Server).factory(() => {
+  const socketIO = constant<Partial<ServerOptions>>("socketIO");
+
+  return new Server(socketIO);
+});
+
+export {Server};

package/src/services/SocketIOService.spec.ts

@@ -0,0 +1,54 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {SocketIOService} from "../index.js";
+import {Server} from "./SocketIOServer.js";
+
+async function createServiceFixture() {
+  const namespace = {
+    on: vi.fn()
+  };
+  const ioStub = {
+    of: vi.fn().mockReturnValue(namespace)
+  };
+  const instance = {
+    onConnection: vi.fn(),
+    onDisconnect: vi.fn()
+  };
+
+  const socket = {
+    on: vi.fn()
+  };
+
+  const service = await PlatformTest.invoke(SocketIOService, [
+    {
+      token: Server,
+      use: ioStub
+    }
+  ]);
+  const reason = "transport error";
+
+  return {namespace, ioStub, service, instance, socket, reason};
+}
+
+describe("SocketIOService", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+
+  describe("getNsp", () => {
+    it.each([{input: "/"}, {input: /test/}])("should call io.of with $input and create namespace", async ({input}) => {
+      const {service, namespace, ioStub, socket, instance, reason} = await createServiceFixture();
+
+      const nspConf = service.getNsp(input);
+      nspConf.instances.push(instance);
+
+      namespace.on.mock.calls[0][1](socket);
+      socket.on.mock.calls[0][1](reason);
+
+      expect(ioStub.of).toHaveBeenCalledWith(input);
+      expect(namespace.on).toHaveBeenCalledWith("connection", expect.any(Function));
+      expect(instance.onConnection).toHaveBeenCalledWith(socket, namespace);
+      expect(socket.on).toHaveBeenCalledWith("disconnect", expect.any(Function));
+      expect(instance.onDisconnect).toHaveBeenCalledWith(socket, namespace, reason);
+    });
+  });
+});

package/src/services/SocketIOService.ts

@@ -0,0 +1,69 @@
+import {InjectorService, Provider, Service} from "@tsed/di";
+import * as SocketIO from "socket.io"; // tslint:disable-line: no-unused-variable
+
+import {SocketHandlersBuilder} from "../class/SocketHandlersBuilder.js";
+import {SocketProviderMetadata} from "../class/SocketProviderMetadata.js";
+import {IO} from "../decorators/io.js";
+
+/**
+ *
+ */
+@Service()
+export class SocketIOService {
+  /**
+   *
+   * @type {Map<any, any>}
+   */
+  private namespaces: Map<string | RegExp, {nsp: SocketIO.Namespace; instances: any}> = new Map();
+
+  constructor(
+    private injector: InjectorService,
+    @IO private io: SocketIO.Server
+  ) {}
+
+  /**
+   *
+   * @param {string} namespace
+   * @returns {SocketIO.Namespace}
+   */
+  public getNsp(namespace: string | RegExp = "/"): {nsp: SocketIO.Namespace; instances: any[]} {
+    if (!this.namespaces.has(namespace)) {
+      const conf = {nsp: this.io.of(namespace), instances: []};
+
+      this.namespaces.set(namespace, conf);
+
+      conf.nsp.on("connection", (socket) => {
+        conf.instances.forEach((builder: SocketHandlersBuilder) => {
+          builder.onConnection(socket, conf.nsp);
+        });
+
+        socket.on("disconnect", (reason: string) => {
+          conf.instances.forEach((builder: SocketHandlersBuilder) => {
+            builder.onDisconnect(socket, conf.nsp, reason);
+          });
+        });
+      });
+    }
+
+    return this.namespaces.get(namespace)!;
+  }
+
+  /**
+   *
+   * @param {Provider<any>} provider
+   */
+  public addSocketProvider(provider: Provider<any>) {
+    const wsConfig: SocketProviderMetadata = new SocketProviderMetadata(provider.store.get("socketIO"));
+
+    const nspConfig = this.getNsp(wsConfig.namespace);
+    const nsps = new Map();
+
+    this.namespaces.forEach((value, nsp) => {
+      nsps.set(nsp, value.nsp);
+    });
+
+    const builder = new SocketHandlersBuilder(provider, this.injector).build(nsps);
+
+    nspConfig.instances.push(builder);
+  }
+}