room-kit 1.0.0

package/example/server.ts

@@ -0,0 +1,200 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+
+import { Server } from "socket.io";
+
+import { ClientSafeError, serveRoomType } from "../src/index";
+import { chatRoomType, type ChatMessage } from "./common";
+
+type ChatAuth = {
+  userId: string;
+};
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const port = Number(process.env.PORT || 3000);
+const publicDir = path.join(__dirname, "public");
+
+function normalizeRoomId(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ClientSafeError("Room id is required.");
+  }
+
+  return value.trim().toLowerCase();
+}
+
+function normalizeRoomKey(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ClientSafeError("Room key is required.");
+  }
+
+  return value.trim();
+}
+
+function normalizeUserId(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ClientSafeError("User id is required.");
+  }
+
+  return value.trim();
+}
+
+function normalizeDisplayName(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ClientSafeError("Display name is required.");
+  }
+
+  const name = value.trim();
+  if (name.length > 32) {
+    throw new ClientSafeError("Display name must be 32 characters or fewer.");
+  }
+
+  return name;
+}
+
+function normalizeMessageText(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ClientSafeError("Message text is required.");
+  }
+
+  const text = value.trim();
+  if (text.length > 500) {
+    throw new ClientSafeError("Message text must be 500 characters or fewer.");
+  }
+
+  return text;
+}
+
+function serveFile(filePath: string, res: http.ServerResponse): void {
+  fs.readFile(filePath, (error, contents) => {
+    if (error) {
+      res.statusCode = 404;
+      res.end("Not found");
+      return;
+    }
+
+    const ext = path.extname(filePath);
+    const contentType =
+      ext === ".html"
+        ? "text/html; charset=utf-8"
+        : ext === ".css"
+          ? "text/css; charset=utf-8"
+          : ext === ".js"
+            ? "text/javascript; charset=utf-8"
+            : "application/octet-stream";
+
+    res.writeHead(200, {
+      "content-type": contentType,
+      "cache-control": "no-store",
+    });
+    res.end(contents);
+  });
+}
+
+const server = http.createServer((req, res) => {
+  const requestUrl = new URL(req.url || "/", "http://127.0.0.1");
+
+  if (requestUrl.pathname === "/" || requestUrl.pathname === "/index.html") {
+    serveFile(path.join(publicDir, "index.html"), res);
+    return;
+  }
+
+  if (requestUrl.pathname === "/styles.css") {
+    serveFile(path.join(publicDir, "styles.css"), res);
+    return;
+  }
+
+  if (requestUrl.pathname === "/app.js") {
+    serveFile(path.join(publicDir, "app.js"), res);
+    return;
+  }
+
+  res.statusCode = 404;
+  res.end("Not found");
+});
+
+const io = new Server(server);
+
+io.on("connection", (socket) => {
+  serveRoomType<typeof chatRoomType, ChatAuth>(socket, chatRoomType, {
+    onAuth: () => ({
+      userId: socket.id,
+    }),
+
+    initState: async (join) => {
+      return {
+        roomKey: normalizeRoomKey(join.roomKey),
+        created: new Date().toISOString(),
+        history: [],
+      };
+    },
+
+    admit: async (join, ctx) => {
+      const roomId = normalizeRoomId(join.roomId);
+      const roomKey = normalizeRoomKey(join.roomKey);
+      const userId = normalizeUserId(ctx.auth.userId);
+      const userName = normalizeDisplayName(join.userName);
+
+      if (ctx.serverState.roomKey !== roomKey) {
+        throw new ClientSafeError("That room key is incorrect.");
+      }
+
+      return {
+        roomId,
+        memberId: userId,
+        memberProfile: {
+          userId,
+          userName,
+          joinedAt: Date.now(),
+        },
+        roomProfile: {
+          roomId,
+          created: ctx.serverState.created,
+          history: ctx.serverState.history.slice(-50),
+        },
+      };
+    },
+
+    onJoin: async (member, ctx) => {
+      await ctx.emit.systemNotice({
+        text: `${member.userName} joined the room`,
+        sentAt: new Date().toISOString(),
+      });
+    },
+
+    onLeave: async (member, ctx) => {
+      await ctx.emit.systemNotice({
+        text: `${member.userName} left the room`,
+        sentAt: new Date().toISOString(),
+      });
+    },
+
+    rpc: {
+      sendMessage: async ({ text }, ctx) => {
+        const messageText = normalizeMessageText(text);
+
+        const message: ChatMessage = {
+          id: randomUUID(),
+          name: ctx.memberProfile.userName,
+          text: messageText,
+          sentAt: new Date().toISOString(),
+        };
+
+        ctx.serverState.history.push(message);
+        if (ctx.serverState.history.length > 50) {
+          ctx.serverState.history.shift();
+        }
+
+        await ctx.emit.message(message);
+        return { id: message.id };
+      },
+    },
+  });
+});
+
+server.listen(port, "127.0.0.1", () => {
+  console.log(`Chat example listening on http://127.0.0.1:${port}`);
+});

package/jsr.json

@@ -0,0 +1,13 @@
+{
+  "name": "@onlycliches/room-kit",
+  "version": "1.0.0",
+  "description": "Type-safe channel primitives for Socket.IO events, requests, streams, and room membership.",
+  "exports": "./src/index.ts",
+  "publish": {
+    "include": [
+      "LICENSE",
+      "README.md",
+      "src/**/*.ts"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "room-kit",
+  "version": "1.0.0",
+  "description": "Type-safe room membership, presence, and realtime messaging for Socket.IO.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/only-cliches/room-kit.git"
+  },
+  "keywords": [
+    "socket.io",
+    "rooms",
+    "presence",
+    "membership",
+    "typescript",
+    "realtime",
+    "private rooms",
+    "rpc",
+    "events",
+    "pubsub"
+  ],
+  "author": "Scott Lott <me@scottlott.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/only-cliches/room-kit/issues"
+  },
+  "homepage": "https://github.com/only-cliches/room-kit#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}

package/src/client.ts

@@ -0,0 +1,433 @@
+import type {
+    ClientConnectionState,
+    ClientSocketLike,
+    EventEmitApi,
+    EventListenApi,
+    EventMetaFor,
+    JoinedRoom,
+    JoinRequest,
+    PresenceFor,
+    PresenceListQuery,
+    PresencePageFor,
+    PresenceValueFor,
+    RoomClient,
+    RoomDefinition,
+    RoomEvents,
+    RoomProfileFor,
+    RoomRpc,
+    RpcClientApi,
+} from "./types";
+
+const JOIN_EVENT = "room-kit:join";
+const LEAVE_EVENT = "room-kit:leave";
+const RPC_EVENT = "room-kit:rpc";
+const CLIENT_EVENT = "room-kit:client-event";
+const SERVER_EVENT = "room-kit:server-event";
+const PRESENCE_EVENT = "room-kit:presence";
+const PRESENCE_QUERY_EVENT = "room-kit:presence-query";
+
+type ClientRegistry = {
+    serverHandlerInstalled: boolean;
+    presenceHandlerInstalled: boolean;
+    reconnectHandlerInstalled: boolean;
+    disconnectHandlerInstalled: boolean;
+    connectErrorHandlerInstalled: boolean;
+    reconnectAttemptHandlerInstalled: boolean;
+    reconnectErrorHandlerInstalled: boolean;
+    reconnectFailedHandlerInstalled: boolean;
+    hasConnectedOnce: boolean;
+    connectionState: ClientConnectionState;
+    connectionListeners: Set<(state: ClientConnectionState) => void>;
+    joinedRooms: Map<string, JoinedRoomState<any>>;
+};
+
+type JoinedRoomState<TRoom extends RoomDefinition<any>> = {
+    name: string;
+    roomId: string;
+    memberId: string;
+    roomProfile: RoomProfileFor<TRoom>;
+    presenceCurrent: PresenceValueFor<TRoom>;
+    joinRequest: JoinRequest<TRoom>;
+    eventListeners: Map<string, Set<(payload: unknown, meta: EventMetaFor<TRoom>) => void>>;
+    presenceListeners: Set<(presence: PresenceFor<TRoom>) => void>;
+};
+
+const clientRegistries = new WeakMap<ClientSocketLike, ClientRegistry>();
+
+/**
+ * Binds a client socket to a room type and returns a typed room client.
+ *
+ * @example
+ * ```ts
+ * import { io } from "socket.io-client";
+ * import { createRoomClient } from "room-kit";
+ *
+ * const socket = io("http://127.0.0.1:3000");
+ * const client = createRoomClient(socket, chatRoomType);
+ * const joined = await client.join({ roomId: "team", roomKey: "secret", userName: "Ada" });
+ * ```
+ */
+export function createRoomClient<TRoom extends RoomDefinition<any>>(
+    socket: ClientSocketLike,
+    room: TRoom,
+): RoomClient<TRoom> {
+    return {
+        name: room.name,
+        get connection() {
+            const registry = getClientRegistry(socket);
+            return {
+                get current(): ClientConnectionState {
+                    return registry.connectionState;
+                },
+                onChange(handler: (state: ClientConnectionState) => void): () => void {
+                    registry.connectionListeners.add(handler);
+                    return () => {
+                        registry.connectionListeners.delete(handler);
+                    };
+                },
+            };
+        },
+        join(payload: JoinRequest<TRoom>): Promise<JoinedRoom<TRoom>> {
+            const registry = getClientRegistry(socket);
+
+            return emitAck<{
+                roomId: string;
+                memberId: string;
+                roomProfile: RoomProfileFor<TRoom>;
+                presence: PresenceValueFor<TRoom>;
+            }>(socket, JOIN_EVENT, {
+                roomType: room.name,
+                payload,
+            }).then((value) => {
+                const state: JoinedRoomState<TRoom> = {
+                    name: room.name,
+                    roomId: value.roomId,
+                    memberId: value.memberId,
+                    roomProfile: value.roomProfile,
+                    presenceCurrent: value.presence,
+                    joinRequest: payload,
+                    eventListeners: new Map(),
+                    presenceListeners: new Set(),
+                };
+
+                registry.joinedRooms.set(makeJoinedRoomKey(room.name, value.roomId), state);
+                return createJoinedRoom(socket, state);
+            });
+        },
+    };
+}
+
+function createJoinedRoom<TRoom extends RoomDefinition<any>>(
+    socket: ClientSocketLike,
+    state: JoinedRoomState<TRoom>,
+): JoinedRoom<TRoom> {
+    const rpc = new Proxy({} as RpcClientApi<TRoom>, {
+        get(_target, key) {
+            if (typeof key !== "string") {
+                return undefined;
+            }
+
+            return (...args: unknown[]) => {
+                return emitAck(socket, RPC_EVENT, {
+                    roomType: state.name,
+                    roomId: state.roomId,
+                    name: key,
+                    args,
+                });
+            };
+        },
+    });
+
+    const emit = new Proxy({} as EventEmitApi<TRoom>, {
+        get(_target, key) {
+            if (typeof key !== "string") {
+                return undefined;
+            }
+
+            return (payload: unknown) => {
+                return emitAck<void>(socket, CLIENT_EVENT, {
+                    roomType: state.name,
+                    roomId: state.roomId,
+                    name: key,
+                    payload,
+                });
+            };
+        },
+    });
+
+    const on = new Proxy({} as EventListenApi<TRoom>, {
+        get(_target, key) {
+            if (typeof key !== "string") {
+                return undefined;
+            }
+
+            return (handler: (payload: unknown, meta: EventMetaFor<TRoom>) => void) => {
+                const handlers = state.eventListeners.get(key) ?? new Set();
+                handlers.add(handler);
+                state.eventListeners.set(key, handlers);
+                return () => {
+                    handlers.delete(handler);
+                    if (handlers.size === 0) {
+                        state.eventListeners.delete(key);
+                    }
+                };
+            };
+        },
+    });
+
+    const base = {
+        name: state.name,
+        roomId: state.roomId,
+        memberId: state.memberId,
+        roomProfile: state.roomProfile,
+        rpc,
+        emit,
+        on,
+        async leave(): Promise<void> {
+            await emitAck<void>(socket, LEAVE_EVENT, {
+                roomType: state.name,
+                roomId: state.roomId,
+            });
+            const registry = getClientRegistry(socket);
+            registry.joinedRooms.delete(makeJoinedRoomKey(state.name, state.roomId));
+        },
+    };
+
+    return new Proxy(base, {
+        get(target, key, receiver) {
+            if (key === "presence") {
+                return {
+                    get current(): PresenceFor<TRoom> {
+                        return state.presenceCurrent as PresenceFor<TRoom>;
+                    },
+                    onChange(handler: (presence: PresenceFor<TRoom>) => void): () => void {
+                        state.presenceListeners.add(handler);
+                        return () => {
+                            state.presenceListeners.delete(handler);
+                        };
+                    },
+                    count(): Promise<number> {
+                        return emitAck<number>(socket, PRESENCE_QUERY_EVENT, {
+                            roomType: state.name,
+                            roomId: state.roomId,
+                            kind: "count",
+                        });
+                    },
+                    list(query: PresenceListQuery = {}): Promise<PresencePageFor<TRoom>> {
+                        return emitAck<PresencePageFor<TRoom>>(socket, PRESENCE_QUERY_EVENT, {
+                            roomType: state.name,
+                            roomId: state.roomId,
+                            kind: "list",
+                            ...query,
+                        });
+                    },
+                };
+            }
+
+            return Reflect.get(target, key, receiver);
+        },
+    }) as JoinedRoom<TRoom>;
+}
+
+function getClientRegistry(socket: ClientSocketLike): ClientRegistry {
+    const existing = clientRegistries.get(socket);
+    if (existing) {
+        return existing;
+    }
+
+    const created: ClientRegistry = {
+        serverHandlerInstalled: false,
+        presenceHandlerInstalled: false,
+        reconnectHandlerInstalled: false,
+        disconnectHandlerInstalled: false,
+        connectErrorHandlerInstalled: false,
+        reconnectAttemptHandlerInstalled: false,
+        reconnectErrorHandlerInstalled: false,
+        reconnectFailedHandlerInstalled: false,
+        hasConnectedOnce: false,
+        connectionState: "connecting",
+        connectionListeners: new Set(),
+        joinedRooms: new Map(),
+    };
+
+    installClientHandlers(socket, created);
+    clientRegistries.set(socket, created);
+    return created;
+}
+
+function installClientHandlers(socket: ClientSocketLike, registry: ClientRegistry): void {
+    if (!registry.serverHandlerInstalled) {
+        const onServerEvent = (frame: {
+            roomType: string;
+            roomId: string;
+            name: string;
+            payload: unknown;
+            meta: {
+                roomId: string;
+                sentAt: string;
+                source: unknown;
+            };
+        }) => {
+            const state = registry.joinedRooms.get(makeJoinedRoomKey(frame.roomType, frame.roomId));
+            if (!state) {
+                return;
+            }
+
+            const handlers = state.eventListeners.get(frame.name);
+            if (!handlers || handlers.size === 0) {
+                return;
+            }
+
+            const meta = {
+                ...frame.meta,
+                sentAt: new Date(frame.meta.sentAt),
+            } as EventMetaFor<any>;
+
+            for (const handler of handlers) {
+                handler(frame.payload, meta);
+            }
+        };
+
+        socket.on(SERVER_EVENT, onServerEvent);
+        registry.serverHandlerInstalled = true;
+    }
+
+    if (!registry.presenceHandlerInstalled) {
+        const onPresence = (frame: { roomType: string; roomId: string; presence: unknown }) => {
+            const state = registry.joinedRooms.get(makeJoinedRoomKey(frame.roomType, frame.roomId));
+            if (!state) {
+                return;
+            }
+
+            state.presenceCurrent = frame.presence as PresenceFor<any>;
+            if (state.presenceCurrent === undefined) {
+                return;
+            }
+
+            for (const handler of state.presenceListeners) {
+                handler(state.presenceCurrent);
+            }
+        };
+
+        socket.on(PRESENCE_EVENT, onPresence);
+        registry.presenceHandlerInstalled = true;
+    }
+
+    if (!registry.reconnectHandlerInstalled) {
+        const onConnect = () => {
+            registry.hasConnectedOnce = true;
+            setConnectionState(registry, "connected");
+            void replayJoinedRooms(socket, registry);
+        };
+
+        socket.on("connect", onConnect);
+        registry.reconnectHandlerInstalled = true;
+    }
+
+    if (!registry.disconnectHandlerInstalled) {
+        const onDisconnect = () => {
+            setConnectionState(registry, "disconnected");
+        };
+
+        socket.on("disconnect", onDisconnect);
+        registry.disconnectHandlerInstalled = true;
+    }
+
+    if (!registry.connectErrorHandlerInstalled) {
+        const onConnectError = () => {
+            setConnectionState(registry, registry.hasConnectedOnce ? "reconnecting" : "connecting");
+        };
+
+        socket.on("connect_error", onConnectError);
+        registry.connectErrorHandlerInstalled = true;
+    }
+
+    if (!registry.reconnectAttemptHandlerInstalled) {
+        const onReconnectAttempt = () => {
+            setConnectionState(registry, "reconnecting");
+        };
+
+        socket.on("reconnect_attempt", onReconnectAttempt);
+        registry.reconnectAttemptHandlerInstalled = true;
+    }
+
+    if (!registry.reconnectFailedHandlerInstalled) {
+        const onReconnectFailed = () => {
+            setConnectionState(registry, "disconnected");
+        };
+
+        socket.on("reconnect_failed", onReconnectFailed);
+        registry.reconnectFailedHandlerInstalled = true;
+    }
+
+    if (!registry.reconnectErrorHandlerInstalled) {
+        const onReconnectError = () => {
+            setConnectionState(registry, "reconnecting");
+        };
+
+        socket.on("reconnect_error", onReconnectError);
+        registry.reconnectErrorHandlerInstalled = true;
+    }
+}
+
+async function replayJoinedRooms(socket: ClientSocketLike, registry: ClientRegistry): Promise<void> {
+    for (const [key, state] of Array.from(registry.joinedRooms.entries())) {
+        try {
+            const value = await emitAck<{
+                roomId: string;
+                memberId: string;
+                roomProfile: RoomProfileFor<any>;
+                presence: PresenceFor<any>;
+            }>(socket, JOIN_EVENT, {
+                roomType: state.name,
+                payload: state.joinRequest,
+            });
+
+            state.roomId = value.roomId;
+            state.memberId = value.memberId;
+            state.roomProfile = value.roomProfile;
+            state.presenceCurrent = value.presence;
+
+            const newKey = makeJoinedRoomKey(state.name, value.roomId);
+            if (newKey !== key) {
+                registry.joinedRooms.delete(key);
+            }
+            registry.joinedRooms.set(newKey, state);
+        } catch {
+            registry.joinedRooms.delete(key);
+        }
+    }
+}
+
+function makeJoinedRoomKey(name: string, roomId: string): string {
+    return `${name}:${roomId}`;
+}
+
+function emitAck<TValue>(socket: ClientSocketLike, eventName: string, payload: unknown): Promise<TValue> {
+    return new Promise<TValue>((resolve, reject) => {
+        socket.emit(eventName, payload, (result: { ok: true; value: TValue } | { ok: false; error: string }) => {
+            if (!result || typeof result !== "object") {
+                reject(new Error("Invalid acknowledgement payload"));
+                return;
+            }
+
+            if (result.ok) {
+                resolve(result.value);
+                return;
+            }
+
+            reject(new Error(result.error));
+        });
+    });
+}
+
+function setConnectionState(registry: ClientRegistry, next: ClientConnectionState): void {
+    if (registry.connectionState === next) {
+        return;
+    }
+
+    registry.connectionState = next;
+    for (const listener of registry.connectionListeners) {
+        listener(next);
+    }
+}