Feat: Room service (#15)

* Room service draft.

* Ref: extracting common params.

* Ref: emission makers accept whole config.

* Issue 952: exposing HandlingFeatures.

* Ren: rooms -> withRooms.

* Feat: getRooms().

* getRooms() test.

* Tests for makeRoomService().

Author: RobinTail

src/action.spec.ts

@@ -31,6 +31,8 @@ describe("Action", () => {
     const emitMock = vi.fn();
     const broadcastMock = vi.fn();
     const isConnectedMock = vi.fn();
+    const withRoomsMock = vi.fn();
+    const getRoomsMock = vi.fn();
 
     test("should handle simple action", async () => {
       await simpleAction.execute({
@@ -39,12 +41,16 @@ describe("Action", () => {
         params: ["some"],
         emit: emitMock,
         broadcast: broadcastMock,
+        withRooms: withRoomsMock,
+        getRooms: getRoomsMock,
         isConnected: isConnectedMock,
         socketId: "ID",
       });
       expect(loggerMock.error).not.toHaveBeenCalled();
       expect(simpleHandler).toHaveBeenLastCalledWith({
         broadcast: broadcastMock,
+        withRooms: withRoomsMock,
+        getRooms: getRoomsMock,
         emit: emitMock,
         input: ["some"],
         isConnected: isConnectedMock,
@@ -61,12 +67,16 @@ describe("Action", () => {
         params: ["some", ackMock],
         emit: emitMock,
         broadcast: broadcastMock,
+        withRooms: withRoomsMock,
+        getRooms: getRoomsMock,
         isConnected: isConnectedMock,
         socketId: "ID",
       });
       expect(loggerMock.error).not.toHaveBeenCalled();
       expect(ackHandler).toHaveBeenLastCalledWith({
         broadcast: broadcastMock,
+        withRooms: withRoomsMock,
+        getRooms: getRoomsMock,
         emit: emitMock,
         input: ["some"],
         isConnected: isConnectedMock,
@@ -83,6 +93,8 @@ describe("Action", () => {
         params: [], // too short
         emit: emitMock,
         broadcast: broadcastMock,
+        withRooms: withRoomsMock,
+        getRooms: getRoomsMock,
         isConnected: isConnectedMock,
         socketId: "ID",
       });

src/action.ts

@@ -2,32 +2,36 @@ import { init, last } from "ramda";
 import type { Socket } from "socket.io";
 import { z } from "zod";
 import { AckActionDef, SimpleActionDef } from "./actions-factory";
-import { Broadcaster, EmissionMap, Emitter } from "./emission";
+import { Broadcaster, EmissionMap, Emitter, RoomService } from "./emission";
 import { AbstractLogger } from "./logger";
 
 export interface SocketFeatures {
   isConnected: () => boolean;
   socketId: Socket["id"];
+  getRooms: () => string[];
+}
+
+export interface HandlingFeatures<E extends EmissionMap> {
+  logger: AbstractLogger;
+  emit: Emitter<E>;
+  broadcast: Broadcaster<E>;
+  withRooms: RoomService<E>;
 }
 
 export type Handler<IN, OUT, E extends EmissionMap> = (
   params: {
     input: IN;
-    logger: AbstractLogger;
-    emit: Emitter<E>;
-    broadcast: Broadcaster<E>;
-  } & SocketFeatures,
+  } & SocketFeatures &
+    HandlingFeatures<E>,
 ) => Promise<OUT>;
 
 export abstract class AbstractAction {
   public abstract execute(
     params: {
       event: string;
       params: unknown[];
-      logger: AbstractLogger;
-      emit: Emitter<EmissionMap>;
-      broadcast: Broadcaster<EmissionMap>;
-    } & SocketFeatures,
+    } & SocketFeatures &
+      HandlingFeatures<EmissionMap>,
   ): Promise<void>;
 }
 
@@ -80,30 +84,20 @@ export class Action<
     event,
     params,
     logger,
-    emit,
-    broadcast,
     ...rest
   }: {
     event: string;
     params: unknown[];
-    logger: AbstractLogger;
-    emit: Emitter<EmissionMap>;
-    broadcast: Broadcaster<EmissionMap>;
-  } & SocketFeatures): Promise<void> {
+  } & SocketFeatures &
+    HandlingFeatures<EmissionMap>): Promise<void> {
     try {
       const input = this.#parseInput(params);
       logger.debug(
         `parsed input (${this.#outputSchema ? "excl." : "no"} ack)`,
         input,
       );
       const ack = this.#parseAckCb(params);
-      const output = await this.#handler({
-        input,
-        logger,
-        emit,
-        broadcast,
-        ...rest,
-      });
+      const output = await this.#handler({ input, logger, ...rest });
       const response = this.#parseOutput(output);
       if (ack && response) {
         logger.debug("parsed output", response);

src/attach.spec.ts

@@ -9,6 +9,7 @@ describe("Attach", () => {
     const socketMock = {
       id: "ID",
       connected: false,
+      rooms: new Set(["room1", "room2"]),
       on: vi.fn(),
       onAny: vi.fn(),
     };
@@ -66,6 +67,8 @@ describe("Attach", () => {
       await call[1]([123, 456]);
       expect(actionsMock.test.execute).toHaveBeenLastCalledWith({
         broadcast: expect.any(Function),
+        withRooms: expect.any(Function),
+        getRooms: expect.any(Function),
         emit: expect.any(Function),
         event: "test",
         isConnected: expect.any(Function),
@@ -74,6 +77,12 @@ describe("Attach", () => {
         socketId: "ID",
       });
 
+      // getRooms:
+      expect(actionsMock.test.execute.mock.lastCall[0].getRooms()).toEqual([
+        "room1",
+        "room2",
+      ]);
+
       // isConnected:
       expect(
         actionsMock.test.execute.mock.lastCall[0].isConnected(),

src/attach.ts

@@ -1,18 +1,25 @@
 import http from "node:http";
 import type { Server } from "socket.io";
-import { ActionMap, Handler, SocketFeatures } from "./action";
+import { ActionMap, Handler, HandlingFeatures, SocketFeatures } from "./action";
 import { SocketsConfig } from "./config";
-import { EmissionMap, makeBroadcaster, makeEmitter } from "./emission";
+import {
+  EmissionMap,
+  makeBroadcaster,
+  makeEmitter,
+  makeRoomService,
+} from "./emission";
 
 export const attachSockets = <E extends EmissionMap>({
   io,
   actions,
   target,
-  config: { emission, timeout, logger },
-  onConnection = ({ socketId }) => logger.debug("User connected", socketId),
-  onDisconnect = ({ socketId }) => logger.debug("User disconnected", socketId),
+  config,
+  onConnection = ({ socketId }) =>
+    config.logger.debug("User connected", socketId),
+  onDisconnect = ({ socketId }) =>
+    config.logger.debug("User disconnected", socketId),
   onAnyEvent = ({ input: [event], socketId }) =>
-    logger.debug(`${event} from ${socketId}`),
+    config.logger.debug(`${event} from ${socketId}`),
 }: {
   /**
    * @desc The Socket.IO server
@@ -36,26 +43,28 @@ export const attachSockets = <E extends EmissionMap>({
   onDisconnect?: Handler<[], void, E>;
   onAnyEvent?: Handler<[string], void, E>;
 }): Server => {
-  logger.info("ZOD-SOCKETS", target.address());
+  config.logger.info("ZOD-SOCKETS", target.address());
   io.on("connection", async (socket) => {
-    const commons: SocketFeatures = {
+    const emit = makeEmitter({ socket, config });
+    const broadcast = makeBroadcaster({ socket, config });
+    const withRooms = makeRoomService({ socket, config });
+    const commons: SocketFeatures & HandlingFeatures<E> = {
       socketId: socket.id,
       isConnected: () => socket.connected,
+      getRooms: () => Array.from(socket.rooms),
+      logger: config.logger,
+      emit,
+      broadcast,
+      withRooms,
     };
-    const emit = makeEmitter({ emission, socket, logger, timeout });
-    const broadcast = makeBroadcaster({ emission, socket, logger, timeout });
-    await onConnection({ input: [], logger, emit, broadcast, ...commons });
-    socket.onAny((event) =>
-      onAnyEvent({ input: [event], logger, emit, broadcast, ...commons }),
-    );
+    await onConnection({ input: [], ...commons });
+    socket.onAny((event) => onAnyEvent({ input: [event], ...commons }));
     for (const [event, action] of Object.entries(actions)) {
       socket.on(event, async (...params) =>
-        action.execute({ event, params, logger, emit, broadcast, ...commons }),
+        action.execute({ event, params, ...commons }),
       );
     }
-    socket.on("disconnect", () =>
-      onDisconnect({ input: [], logger, emit, broadcast, ...commons }),
-    );
+    socket.on("disconnect", () => onDisconnect({ input: [], ...commons }));
   });
   return io.attach(target);
 };

src/emission.spec.ts

@@ -1,7 +1,7 @@
 import { Socket } from "socket.io";
 import { MockedFunction, describe, expect, test, vi } from "vitest";
 import { z } from "zod";
-import { makeBroadcaster, makeEmitter } from "./emission";
+import { makeBroadcaster, makeEmitter, makeRoomService } from "./emission";
 import { AbstractLogger } from "./logger";
 
 describe("Emission", () => {
@@ -15,29 +15,39 @@ describe("Emission", () => {
   };
 
   const socketMock: Record<
-    "emit" | "timeout" | "emitWithAck",
+    "emit" | "timeout" | "emitWithAck" | "join" | "leave",
     MockedFunction<any>
-  > & { id: string; broadcast: typeof broadcastMock } = {
+  > & {
+    id: string;
+    broadcast: typeof broadcastMock;
+    to: (rooms: string | string[]) => typeof broadcastMock;
+  } = {
     id: "ID",
     emit: vi.fn(),
     timeout: vi.fn(() => socketMock),
     emitWithAck: vi.fn(),
     broadcast: broadcastMock,
+    to: vi.fn(() => broadcastMock),
+    join: vi.fn(),
+    leave: vi.fn(),
   };
   const loggerMock = { debug: vi.fn() };
+  const config = {
+    logger: loggerMock as unknown as AbstractLogger,
+    timeout: 100,
+    emission: {
+      one: { schema: z.tuple([z.string()]) },
+      two: { schema: z.tuple([z.number()]), ack: z.tuple([z.string()]) },
+    },
+  };
 
   describe.each([
     { maker: makeEmitter, target: socketMock, ack: ["test"] },
     { maker: makeBroadcaster, target: broadcastMock, ack: [["test"]] },
   ])("$maker.name", ({ maker, target, ack }) => {
     const emitter = maker({
       socket: socketMock as unknown as Socket,
-      logger: loggerMock as unknown as AbstractLogger,
-      timeout: 100,
-      emission: {
-        one: { schema: z.tuple([z.string()]) },
-        two: { schema: z.tuple([z.number()]), ack: z.tuple([z.string()]) },
-      },
+      config,
     });
 
     test("should create an emitter", () => {
@@ -60,4 +70,33 @@ describe("Emission", () => {
       expect(await emitter("two", 123)).toEqual(ack);
     });
   });
+
+  describe("makeRoomService", () => {
+    test.each(["room1", ["room2", "room3"]])(
+      "should provide methods in rooms context %#",
+      async (rooms) => {
+        const withRooms = makeRoomService({
+          socket: socketMock as unknown as Socket,
+          config,
+        });
+        expect(typeof withRooms).toBe("function");
+        const { broadcast, leave, join } = withRooms(rooms);
+        expect(socketMock.to).toHaveBeenLastCalledWith(rooms);
+        for (const method of [broadcast, leave, join]) {
+          expect(typeof method).toBe("function");
+        }
+        join();
+        expect(socketMock.join).toHaveBeenLastCalledWith(rooms);
+        if (typeof rooms === "string") {
+          leave();
+          expect(socketMock.leave).toHaveBeenLastCalledWith(rooms);
+        } else {
+          await leave();
+          for (const room of rooms) {
+            expect(socketMock.leave).toHaveBeenCalledWith(room);
+          }
+        }
+      },
+    );
+  });
 });