@tsed/socketio 8.0.1 → 8.0.2

package/src/decorators/reason.ts

@@ -0,0 +1,30 @@
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+import {SocketFilter} from "./socketFilter.js";
+
+/**
+ * Inject the disconnection reason into the decorated parameter.
+ *
+ * This decorator is used in conjunction with the `$onDisconnect` event handler to handle disconnection reasons in SocketIO services.
+ * It allows you to access the reason for the disconnection in your method implementation. For details please refer to the [Socket.io documentation](https://socket.io/docs/v4/server-api/#event-disconnect).
+ *
+ * @example
+ * ```typescript
+ * @SocketService("/nsp")
+ * export class MyWS {
+ *   public async $onDisconnect(
+ *     @Reason reason: string = ''
+ *   ) {
+ *      // your implementation
+ *   }
+ * }
+ * ```
+ *
+ * @experimental This decorator is experimental and may change or be removed in future versions.
+ * @param target
+ * @param {string} propertyKey
+ * @param {number} index
+ * @decorator
+ */
+export function Reason(target: unknown, propertyKey: string, index: number) {
+  return SocketFilter(SocketFilters.REASON)(target, propertyKey, index);
+}

package/src/decorators/socket.spec.ts

@@ -0,0 +1,26 @@
+import {Store} from "@tsed/core";
+
+import {Socket} from "../index.js";
+
+describe("Socket", () => {
+  it("should set metadata", () => {
+    class Test {}
+
+    Socket(Test, "test", 0);
+
+    const store = Store.from(Test);
+
+    expect(store.get("socketIO")).toEqual({
+      handlers: {
+        test: {
+          parameters: {
+            "0": {
+              filter: "socket",
+              mapIndex: undefined
+            }
+          }
+        }
+      }
+    });
+  });
+});

package/src/decorators/socket.ts

@@ -0,0 +1,32 @@
+import {Socket as SocketType} from "socket.io";
+
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+import {SocketFilter} from "./socketFilter.js";
+
+export type Socket = SocketType;
+
+/**
+ * Inject the Socket instance in the decorated parameter.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @SocketService("/nsp")
+ * export class MyWS {
+ *
+ *   @Input("event")
+ *   myMethod(@Socket socket) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * @experimental
+ * @param target
+ * @param {string} propertyKey
+ * @param {number} index
+ * @decorator
+ */
+export function Socket(target: any, propertyKey: string, index: number): any {
+  return SocketFilter(SocketFilters.SOCKET)(target, propertyKey, index);
+}

package/src/decorators/socketErr.spec.ts

@@ -0,0 +1,25 @@
+import {Store} from "@tsed/core";
+
+import {SocketErr} from "../index.js";
+
+describe("@SocketErr", () => {
+  it("should set metadata", () => {
+    class Test {}
+
+    SocketErr(Test, "test", 0);
+    const store = Store.from(Test);
+
+    expect(store.get("socketIO")).toEqual({
+      handlers: {
+        test: {
+          parameters: {
+            "0": {
+              filter: "error",
+              mapIndex: undefined
+            }
+          }
+        }
+      }
+    });
+  });
+});

package/src/decorators/socketErr.ts

@@ -0,0 +1,26 @@
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+import {SocketFilter} from "./socketFilter.js";
+
+/**
+ * Inject the error in the parameters
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @SocketMiddlewareError()
+ * export class MyMiddleware {
+ *
+ *   myMethod(@SocketErr err: any, @Args() arguments: any[]) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * @decorator
+ * @param target
+ * @param propertyKey
+ * @param index
+ */
+export function SocketErr(target: any, propertyKey: string, index: number): any {
+  return SocketFilter(SocketFilters.ERR)(target, propertyKey, index);
+}

package/src/decorators/socketEventName.spec.ts

@@ -0,0 +1,25 @@
+import {Store} from "@tsed/core";
+
+import {SocketEventName} from "../index.js";
+
+describe("@SocketEventName", () => {
+  it("should set metadata", () => {
+    class Test {}
+
+    SocketEventName(Test, "test", 0);
+    const store = Store.from(Test);
+
+    expect(store.get("socketIO")).toEqual({
+      handlers: {
+        test: {
+          parameters: {
+            "0": {
+              filter: "eventName",
+              mapIndex: undefined
+            }
+          }
+        }
+      }
+    });
+  });
+});

package/src/decorators/socketEventName.ts

@@ -0,0 +1,26 @@
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+import {SocketFilter} from "./socketFilter.js";
+
+/**
+ * Inject the Socket instance in the decorated parameter.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @SocketMiddleware("/nsp")
+ * export class MyMiddleware {
+ *   use(@SocketEventName eventName: string) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * @experimental
+ * @param target
+ * @param {string} propertyKey
+ * @param {number} index
+ * @decorator
+ */
+export function SocketEventName(target: any, propertyKey: string, index: number): any {
+  return SocketFilter(SocketFilters.EVENT_NAME)(target, propertyKey, index);
+}

package/src/decorators/socketFilter.ts

@@ -0,0 +1,27 @@
+import {Store} from "@tsed/core";
+
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+
+/**
+ *
+ * @param {SocketFilters} filter
+ * @param {number} mapIndex
+ * @returns {(target: any, propertyKey: string, index: number) => Store}
+ * @decorator
+ */
+export function SocketFilter(filter: SocketFilters, mapIndex?: number) {
+  return (target: any, propertyKey: string, index: number) => {
+    Store.from(target).merge("socketIO", {
+      handlers: {
+        [propertyKey]: {
+          parameters: {
+            [index]: {
+              filter,
+              mapIndex
+            }
+          }
+        }
+      }
+    });
+  };
+}

package/src/decorators/socketMiddleware.spec.ts

@@ -0,0 +1,21 @@
+import {Store} from "@tsed/core";
+
+import {SocketMiddleware, SocketProviderTypes} from "../index.js";
+
+describe("@SocketMiddleware", () => {
+  it("should register the middleware", () => {
+    @SocketMiddleware()
+    class Test {
+      use() {}
+    }
+
+    expect(Store.from(Test).get("socketIO")).toEqual({
+      type: SocketProviderTypes.MIDDLEWARE,
+      handlers: {
+        use: {
+          methodClassName: "use"
+        }
+      }
+    });
+  });
+});

package/src/decorators/socketMiddleware.ts

@@ -0,0 +1,72 @@
+import {Store, Type} from "@tsed/core";
+import {Middleware} from "@tsed/platform-middlewares";
+
+import {SocketProviderTypes} from "../interfaces/SocketProviderTypes.js";
+
+/**
+ * Declare a new SocketMiddleware.
+ *
+ * ### 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 = this.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 {Function}
+ * @decorator
+ * @experimental
+ */
+export function SocketMiddleware(): Function {
+  return (target: Type<any>) => {
+    Store.from(target).merge("socketIO", {
+      type: SocketProviderTypes.MIDDLEWARE,
+      handlers: {
+        use: {
+          methodClassName: "use"
+        }
+      }
+    });
+
+    return Middleware()(target);
+  };
+}

package/src/decorators/socketMiddlewareError.spec.ts

@@ -0,0 +1,22 @@
+import {Store} from "@tsed/core";
+
+import {SocketMiddlewareError, SocketProviderTypes} from "../index.js";
+
+describe("@SocketMiddlewareError", () => {
+  it("should register the metadata and middleware", () => {
+    @SocketMiddlewareError()
+    class Test {
+      use() {}
+    }
+
+    expect(Store.from(Test).get("socketIO")).toEqual({
+      type: SocketProviderTypes.MIDDLEWARE,
+      error: true,
+      handlers: {
+        use: {
+          methodClassName: "use"
+        }
+      }
+    });
+  });
+});

package/src/decorators/socketMiddlewareError.ts

@@ -0,0 +1,70 @@
+import {Store, Type} from "@tsed/core";
+import {Middleware} from "@tsed/platform-middlewares";
+
+import {SocketProviderTypes} from "../interfaces/SocketProviderTypes.js";
+
+/**
+ * Declare a new SocketMiddlewareError.
+ *
+ * ### 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(@SocketEventName, @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 {Function}
+ * @decorator
+ * @experimental
+ */
+export function SocketMiddlewareError(): Function {
+  return (target: Type<any>) => {
+    Store.from(target).merge("socketIO", {
+      type: SocketProviderTypes.MIDDLEWARE,
+      error: true,
+
+      handlers: {
+        use: {
+          methodClassName: "use"
+        }
+      }
+    });
+
+    return Middleware()(target);
+  };
+}

package/src/decorators/socketNsp.spec.ts

@@ -0,0 +1,26 @@
+import {Store} from "@tsed/core";
+
+import {SocketNsp} from "../index.js";
+
+describe("SocketNsp", () => {
+  it("should set metadata", () => {
+    class Test {}
+
+    SocketNsp(Test, "test", 0);
+
+    const store = Store.from(Test);
+
+    expect(store.get("socketIO")).toEqual({
+      handlers: {
+        test: {
+          parameters: {
+            "0": {
+              filter: "socket_nsp",
+              mapIndex: undefined
+            }
+          }
+        }
+      }
+    });
+  });
+});

package/src/decorators/socketNsp.ts

@@ -0,0 +1,32 @@
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+import {Namespace} from "./nsp.js";
+import {SocketFilter} from "./socketFilter.js";
+
+export type SocketNsp = Namespace;
+
+/**
+ * Inject the [SocketIO.Namespace](https://socket.io/docs/rooms-and-namespaces/#namespaces) instance in the decorated parameter.
+ * This namespace may differ from the default namespace when using dynamic namespaces.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @SocketService(/nsp-.+/)
+ * export class MyWS {
+ *
+ *   @Input("event")
+ *   myMethod(@SocketNsp nsp: SocketNsp) {
+ *
+ *   }
+ * }
+ * ```
+ *
+ * @experimental
+ * @param target
+ * @param {string} propertyKey
+ * @param {number} index
+ * @decorator
+ */
+export function SocketNsp(target: any, propertyKey: string, index: number): any {
+  return SocketFilter(SocketFilters.SOCKET_NSP)(target, propertyKey, index);
+}

package/src/decorators/socketReturns.ts

@@ -0,0 +1,25 @@
+import {Store} from "@tsed/core";
+
+import {SocketReturnsTypes} from "../interfaces/SocketReturnsTypes.js";
+
+/**
+ *
+ * @param {string} eventName
+ * @param {SocketReturnsTypes} type
+ * @returns {(target: any, propertyKey: string, descriptor: PropertyDescriptor) => void}
+ * @decorator
+ */
+export function SocketReturns(eventName: string, type: SocketReturnsTypes) {
+  return (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
+    Store.from(target).merge("socketIO", {
+      handlers: {
+        [propertyKey]: {
+          returns: {
+            eventName,
+            type
+          }
+        }
+      }
+    });
+  };
+}

package/src/decorators/socketService.spec.ts

@@ -0,0 +1,44 @@
+import {Store} from "@tsed/core";
+
+import {SocketService} from "./socketService.js";
+
+describe("SocketService", () => {
+  describe("case 1", () => {
+    class Test {}
+    it("should set metadata", () => {
+      SocketService("/namespace")(Test);
+      const store = Store.from(Test);
+
+      expect(store.get("socketIO")).toEqual({
+        namespace: "/namespace",
+        type: "service"
+      });
+    });
+  });
+  describe("case 2", () => {
+    class Test {}
+    it("should set metadata", () => {
+      SocketService()(Test);
+      const store = Store.from(Test);
+
+      expect(store.get("socketIO")).toEqual({
+        namespace: "/",
+        type: "service"
+      });
+    });
+  });
+  describe("case 3", () => {
+    class Test {}
+    it("should set metadata", () => {
+      const regexp = new RegExp(/test/);
+
+      SocketService(regexp)(Test);
+      const store = Store.from(Test);
+
+      expect(store.get("socketIO")).toEqual({
+        namespace: regexp,
+        type: "service"
+      });
+    });
+  });
+});

package/src/decorators/socketService.ts

@@ -0,0 +1,24 @@
+import {StoreMerge, useDecorators} from "@tsed/core";
+import {Injectable} from "@tsed/di";
+
+import {PROVIDER_TYPE_SOCKET_SERVICE} from "../constants/constants.js";
+import {SocketProviderTypes} from "../interfaces/SocketProviderTypes.js";
+
+/**
+ * The decorators `@SocketService()` declare a new socket service (and service) can be injected in other service or controller on there `constructor`.
+ * All services annotated with `@SocketService()` are constructed one time.
+ *
+ * > `@SocketService()` use the `reflect-metadata` to collect and inject service on controllers or other services.
+ *
+ * @param namespace
+ * @returns {Function}
+ * @decorator
+ */
+export function SocketService(namespace: string | RegExp = "/") {
+  return useDecorators(
+    StoreMerge("socketIO", {namespace, type: SocketProviderTypes.SERVICE}),
+    Injectable({
+      type: PROVIDER_TYPE_SOCKET_SERVICE
+    })
+  );
+}

package/src/decorators/socketSession.spec.ts

@@ -0,0 +1,47 @@
+import {Store} from "@tsed/core";
+
+import {RawSocketSession, SocketFilters, SocketSession} from "../index.js";
+
+describe("SocketSession", () => {
+  it("should set metadata", () => {
+    class Test {}
+
+    SocketSession(Test, "test", 0);
+    const store = Store.from(Test);
+
+    expect(store.get("socketIO")).toEqual({
+      handlers: {
+        test: {
+          parameters: {
+            "0": {
+              filter: SocketFilters.SESSION,
+              mapIndex: undefined
+            }
+          }
+        }
+      }
+    });
+  });
+});
+
+describe("RawSocketSession", () => {
+  it("should set metadata", () => {
+    class Test {}
+
+    RawSocketSession(Test, "test", 0);
+    const store = Store.from(Test);
+
+    expect(store.get("socketIO")).toEqual({
+      handlers: {
+        test: {
+          parameters: {
+            "0": {
+              filter: SocketFilters.RAW_SESSION,
+              mapIndex: undefined
+            }
+          }
+        }
+      }
+    });
+  });
+});

package/src/decorators/socketSession.ts

@@ -0,0 +1,53 @@
+import {SocketFilters} from "../interfaces/SocketFilters.js";
+import {SocketFilter} from "./socketFilter.js";
+
+export type SocketSession = Map<string, any>;
+
+/**
+ * Inject the socket session data in the decorated parameter.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @SocketService("/nsp")
+ * export class MyWS {
+ *
+ *   @Input("event")
+ *   myMethod(@SocketSession session: SocketSession) {
+ *     console.log(session);
+ *   }
+ * }
+ * ```
+ *
+ * @param target
+ * @param {string} propertyKey
+ * @param {number} index
+ * @decorator
+ */
+export function SocketSession(target: any, propertyKey: string, index: number) {
+  return SocketFilter(SocketFilters.SESSION)(target, propertyKey, index);
+}
+
+/**
+ * Inject the raw `socket.data` in the decorated parameter.
+ *
+ * @example
+ * ```typescript
+ * @SocketService("/nsp")
+ * export class MyWS {
+ *
+ *   @Input("event")
+ *   myMethod(@RawSocketSession session: Record<string, unknown>) {
+ *     console.log(session);
+ *   }
+ * }
+ * ```
+ *
+ * @param target
+ * @param {string} propertyKey
+ * @param {number} index
+ * @constructor
+ */
+export function RawSocketSession(target: any, propertyKey: string, index: number) {
+  return SocketFilter(SocketFilters.RAW_SESSION)(target, propertyKey, index);
+}