room-kit 1.0.0 → 1.0.1

package/README.md

@@ -61,7 +61,10 @@ export const chatRoom = defineRoomType<{
   rpc: {
     sendMessage: (input: { text: string }): Promise<{ id: string }>;
   };
-}>({ name: "chat", presence: "list" });
+}>({ 
+  name: "chat", // namespace
+  presence: "list" // allow clients to list room members
+});
 ```
 
 ```ts
@@ -155,13 +158,23 @@ const joined = await chatClient.join({
 });
 
 // Event payload and metadata are both inferred from the room schema.
-joined.on.message((payload, meta) => {
-  // meta.source.kind is "server" or "member".
-  console.log(payload.text, meta.source.kind);
+const cleanup = joined.listen({
+  events: {
+    message: (payload, meta) => {
+      // meta.source.kind is "server" or "member".
+      console.log(payload.text, meta.source.kind);
+    },
+  },
+  presence: {
+    onChange: (presence) => {
+      console.log(`${presence.count} members online`);
+    },
+  },
 });
 
 // Fully typed request/response based on your room definition.
 await joined.rpc.sendMessage({ text: "hello" });
+cleanup();
 // Cleanly leave the room when you're done.
 await joined.leave();
 ```
@@ -188,7 +201,7 @@ Runtime presence mode is configured in the `defineRoomType` options:
 
 `serveRoomType(socket, roomType, handlers, adapter?)` accepts:
 
-- `onAuth(socket)`: optional unless you type a non-`unknown` auth context.
+- `onAuth(socket)`: optional unless you type a non-`unknown` auth context. Return `false` to reject the socket before room initialization.
 - `onConnect(socket, auth)`: optional transport-connect hook attempted once when the socket handler is attached (after auth resolution).
 - `revalidateAuth(socket, auth)`: optional per-request auth validation hook; return `{ kind: "ok", auth? }` to continue or `{ kind: "reject" }` to deny.
 - `initState(joinRequest)`: initializes room server state on first join for a given room instance.
@@ -212,11 +225,11 @@ Server context (`ctx`) includes:
 
 `serveRoomType` returns a handle:
 
-- `stop()` unregisters listeners for that socket
-- `stop.rooms()` returns snapshots for all rooms on the namespace
-- `stop.room(roomId)` returns one room snapshot or `undefined`
-- `stop.count(roomId)` returns the current member count for a room (`0` when the room does not exist; throws when room presence mode is `"none"`)
-- `stop.members(roomId, query)` returns a paginated presence listing (`{ count: 0, offset: 0, limit: 0, members: [] }` when the room does not exist; throws when room presence mode is not `"list"`)
+- `handle.cleanup()` unregisters listeners for that socket
+- `handle.rooms()` returns snapshots for all rooms on the namespace
+- `handle.room(roomId)` returns one room snapshot or `undefined`
+- `handle.count(roomId)` returns the current member count for a room (`0` when the room does not exist; throws when room presence mode is `"none"`)
+- `handle.members(roomId, query)` returns a paginated presence listing (`{ count: 0, offset: 0, limit: 0, members: [] }` when the room does not exist; throws when room presence mode is not `"list"`)
 
 ## Client API
 
@@ -233,6 +246,7 @@ Server context (`ctx`) includes:
 - `joinedRoom.rpc.<name>(...args)` for typed RPC calls
 - `joinedRoom.emit.<event>(payload)` for client-emitted room events
 - `joinedRoom.on.<event>((payload, meta) => {})` for room event subscriptions
+- `joinedRoom.listen({ events, presence })` batches event and presence subscriptions and returns one cleanup function
 - `joinedRoom.leave()` to leave the room and unregister the joined-room handle
 - `joinedRoom.presence` is part of the typed API when room presence mode is `"count"` or `"list"`; it exposes `current`, `onChange(handler)`, `count()`, and `list({ offset, limit })` when presence mode is `"list"`.
 
@@ -240,6 +254,7 @@ Server context (`ctx`) includes:
 
 - Throw `ClientSafeError` for messages you want sent to clients.
 - Non-`ClientSafeError` exceptions are sanitized to: `"An internal server error occurred."`
+- `onAuth` may return `false` to reject the socket before any room state is initialized.
 - RPC and event dispatch only allow own properties (`Object.hasOwn`) to prevent prototype-based handler access.
 - Client event names are default-deny unless explicitly declared in `handlers.events`.
 - Do not trust client payloads for authorization; derive identity in `onAuth`.

package/example/public/app.ts

@@ -26,271 +26,268 @@ const keyInput = document.getElementById("key-input") as HTMLInputElement;
 const messageInput = document.getElementById("message-input") as HTMLInputElement;
 
 let joinedRoom: JoinedRoom<typeof chatRoomType> | null = null;
-let stopMessageListener: (() => void) | null = null;
-let stopSystemListener: (() => void) | null = null;
-let stopPresenceListener: (() => void) | null = null;
+let stopRoomListeners: (() => void) | null = null;
 let presenceOffset = 0;
 const presencePageSize = 4;
 
 function setStatus(message: string): void {
-  status.textContent = message;
+	status.textContent = message;
 }
 
 function setWorkspaceVisible(visible: boolean): void {
-  workspace.classList.toggle("hidden", !visible);
-  joinPanel.classList.toggle("hidden", visible);
+	workspace.classList.toggle("hidden", !visible);
+	joinPanel.classList.toggle("hidden", visible);
 }
 
 function clearMessages(): void {
-  messages.innerHTML = "";
+	messages.innerHTML = "";
 }
 
 function renderMessage(message: ChatMessage): void {
-  const item = document.createElement("article");
-  item.className = "message";
-  item.innerHTML = `
+	const item = document.createElement("article");
+	item.className = "message";
+	item.innerHTML = `
     <div class="message-header">
       <span class="message-name">${escapeHtml(message.name)}</span>
       <span class="message-time">${formatTime(message.sentAt)}</span>
     </div>
     <div class="message-text">${escapeHtml(message.text)}</div>
   `;
-  messages.appendChild(item);
-  messages.scrollTop = messages.scrollHeight;
+	messages.appendChild(item);
+	messages.scrollTop = messages.scrollHeight;
 }
 
 function renderSystemNotice(text: string, sentAt: string): void {
-  const item = document.createElement("article");
-  item.className = "message";
-  item.innerHTML = `
+	const item = document.createElement("article");
+	item.className = "message";
+	item.innerHTML = `
     <div class="message-header">
       <span class="message-name">System</span>
       <span class="message-time">${formatTime(sentAt)}</span>
     </div>
     <div class="message-text">${escapeHtml(text)}</div>
   `;
-  messages.appendChild(item);
-  messages.scrollTop = messages.scrollHeight;
+	messages.appendChild(item);
+	messages.scrollTop = messages.scrollHeight;
 }
 
 function renderHistory(history: ChatMessage[]): void {
-  clearMessages();
-  for (const message of history) {
-    renderMessage(message);
-  }
+	clearMessages();
+	for (const message of history) {
+		renderMessage(message);
+	}
 }
 
 function renderPresence(): void {
-  if (!joinedRoom) {
-    presenceCount.textContent = "0 online";
-    presencePage.textContent = "Showing 0 members.";
-    presenceList.innerHTML = "";
-    return;
-  }
-
-  const presence = joinedRoom.presence.current;
-  presenceCount.textContent = `${presence.count} online`;
-  presencePage.textContent = `Showing ${Math.min(presenceOffset + 1, presence.count)}-${Math.min(
-    presenceOffset + presence.members.length,
-    presence.count,
-  )} of ${presence.count} members.`;
-  presenceList.innerHTML = "";
-
-  if (presence.members.length === 0) {
-    const empty = document.createElement("li");
-    empty.className = "presence-empty";
-    empty.textContent = "Nobody is here yet.";
-    presenceList.appendChild(empty);
-    return;
-  }
-
-  for (const entry of presence.members) {
-    const item = document.createElement("li");
-    item.className = "presence-item";
-    item.innerHTML = `
+	if (!joinedRoom) {
+		presenceCount.textContent = "0 online";
+		presencePage.textContent = "Showing 0 members.";
+		presenceList.innerHTML = "";
+		return;
+	}
+
+	const presence = joinedRoom.presence.current;
+	presenceCount.textContent = `${presence.count} online`;
+	presencePage.textContent = `Showing ${Math.min(presenceOffset + 1, presence.count)}-${Math.min(
+		presenceOffset + presence.members.length,
+		presence.count,
+	)} of ${presence.count} members.`;
+	presenceList.innerHTML = "";
+
+	if (presence.members.length === 0) {
+		const empty = document.createElement("li");
+		empty.className = "presence-empty";
+		empty.textContent = "Nobody is here yet.";
+		presenceList.appendChild(empty);
+		return;
+	}
+
+	for (const entry of presence.members) {
+		const item = document.createElement("li");
+		item.className = "presence-item";
+		item.innerHTML = `
       <span>${escapeHtml(entry.memberProfile.userName)}</span>
       <span class="presence-pill" aria-hidden="true"></span>
     `;
-    presenceList.appendChild(item);
-  }
+		presenceList.appendChild(item);
+	}
 }
 
 async function refreshPresence(): Promise<void> {
-  if (!joinedRoom) {
-    return;
-  }
-
-  const [count, page] = await Promise.all([
-    joinedRoom.presence.count(),
-    joinedRoom.presence.list({ offset: presenceOffset, limit: presencePageSize }),
-  ]);
-
-  presenceCount.textContent = `${count} online`;
-  presencePage.textContent = page.members.length === 0
-    ? `Showing 0 of ${count} members.`
-    : `Showing ${page.offset + 1}-${page.offset + page.members.length} of ${count} members.`;
-
-  presenceList.innerHTML = "";
-  if (page.members.length === 0) {
-    const empty = document.createElement("li");
-    empty.className = "presence-empty";
-    empty.textContent = "Nobody is here yet.";
-    presenceList.appendChild(empty);
-    return;
-  }
-
-  for (const entry of page.members) {
-    const item = document.createElement("li");
-    item.className = "presence-item";
-    item.innerHTML = `
+	if (!joinedRoom) {
+		return;
+	}
+
+	const [count, page] = await Promise.all([
+		joinedRoom.presence.count(),
+		joinedRoom.presence.list({ offset: presenceOffset, limit: presencePageSize }),
+	]);
+
+	presenceCount.textContent = `${count} online`;
+	presencePage.textContent = page.members.length === 0
+		? `Showing 0 of ${count} members.`
+		: `Showing ${page.offset + 1}-${page.offset + page.members.length} of ${count} members.`;
+
+	presenceList.innerHTML = "";
+	if (page.members.length === 0) {
+		const empty = document.createElement("li");
+		empty.className = "presence-empty";
+		empty.textContent = "Nobody is here yet.";
+		presenceList.appendChild(empty);
+		return;
+	}
+
+	for (const entry of page.members) {
+		const item = document.createElement("li");
+		item.className = "presence-item";
+		item.innerHTML = `
       <span>${escapeHtml(entry.memberProfile.userName)}</span>
       <span class="presence-pill" aria-hidden="true"></span>
     `;
-    presenceList.appendChild(item);
-  }
+		presenceList.appendChild(item);
+	}
 }
 
 function formatTime(value: string): string {
-  const date = new Date(value);
-  return Number.isNaN(date.getTime())
-    ? ""
-    : new Intl.DateTimeFormat(undefined, {
-        hour: "2-digit",
-        minute: "2-digit",
-      }).format(date);
+	const date = new Date(value);
+	return Number.isNaN(date.getTime())
+		? ""
+		: new Intl.DateTimeFormat(undefined, {
+			hour: "2-digit",
+			minute: "2-digit",
+		}).format(date);
 }
 
 function escapeHtml(value: string): string {
-  return String(value)
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&#39;");
+	return String(value)
+		.replaceAll("&", "&amp;")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;");
 }
 
 async function connectRoom(): Promise<void> {
-  const payload = {
-    roomId: roomInput.value.trim().toLowerCase(),
-    roomKey: keyInput.value,
-    userName: nameInput.value,
-  };
-
-  setStatus("Joining room...");
-
-  try {
-    presenceOffset = 0;
-    joinedRoom = await chatClient.join(payload);
-    renderHistory(joinedRoom.roomProfile.history);
-    await refreshPresence();
-
-    stopMessageListener = joinedRoom.on.message((message) => {
-      renderMessage(message);
-    });
-
-    stopSystemListener = joinedRoom.on.systemNotice((notice) => {
-      renderSystemNotice(notice.text, notice.sentAt);
-    });
-
-    stopPresenceListener = joinedRoom.presence.onChange(() => {
-      void refreshPresence();
-    });
-
-    roomTitle.textContent = joinedRoom.roomId;
-    roomSubtitle.textContent = `Signed in as ${payload.userName}. The room stays private behind the shared key.`;
-    setWorkspaceVisible(true);
-    setStatus(`Connected to ${joinedRoom.roomId}.`);
-    messageInput.focus();
-  } catch (error) {
-    joinedRoom = null;
-    setStatus(error instanceof Error ? error.message : String(error));
-  }
+	const payload = {
+		roomId: roomInput.value.trim().toLowerCase(),
+		roomKey: keyInput.value,
+		userName: nameInput.value,
+	};
+
+	setStatus("Joining room...");
+
+	try {
+		presenceOffset = 0;
+		joinedRoom = await chatClient.join(payload);
+		renderHistory(joinedRoom.roomProfile.history);
+		stopRoomListeners = joinedRoom.listen({
+			events: {
+				message: (message) => {
+					renderMessage(message);
+				},
+				systemNotice: (notice) => {
+					renderSystemNotice(notice.text, notice.sentAt);
+				},
+			},
+			presence: {
+				onChange: () => {
+					void refreshPresence();
+				},
+			},
+		});
+		await refreshPresence();
+
+		roomTitle.textContent = joinedRoom.roomId;
+		roomSubtitle.textContent = `Signed in as ${payload.userName}. The room stays private behind the shared key.`;
+		setWorkspaceVisible(true);
+		setStatus(`Connected to ${joinedRoom.roomId}.`);
+		messageInput.focus();
+	} catch (error) {
+		joinedRoom = null;
+		setStatus(error instanceof Error ? error.message : String(error));
+	}
 }
 
 async function leaveRoom(): Promise<void> {
-  if (!joinedRoom) {
-    return;
-  }
-
-  const roomId = joinedRoom.roomId;
-
-  try {
-    await joinedRoom.leave();
-  } finally {
-    stopMessageListener?.();
-    stopSystemListener?.();
-    stopPresenceListener?.();
-    stopMessageListener = null;
-    stopSystemListener = null;
-    stopPresenceListener = null;
-    joinedRoom = null;
-
-    setWorkspaceVisible(false);
-    joinForm.reset();
-    clearMessages();
-    presenceList.innerHTML = "";
-    presenceCount.textContent = "0 online";
-    presencePage.textContent = "Showing 0 members.";
-    roomTitle.textContent = "-";
-    roomSubtitle.textContent = "-";
-    setStatus(`Left ${roomId}.`);
-  }
+	if (!joinedRoom) {
+		return;
+	}
+
+	const roomId = joinedRoom.roomId;
+
+	try {
+		await joinedRoom.leave();
+	} finally {
+		stopRoomListeners?.();
+		stopRoomListeners = null;
+		joinedRoom = null;
+
+		setWorkspaceVisible(false);
+		joinForm.reset();
+		clearMessages();
+		presenceList.innerHTML = "";
+		presenceCount.textContent = "0 online";
+		presencePage.textContent = "Showing 0 members.";
+		roomTitle.textContent = "-";
+		roomSubtitle.textContent = "-";
+		setStatus(`Left ${roomId}.`);
+	}
 }
 
 joinForm.addEventListener("submit", async (event) => {
-  event.preventDefault();
-  await connectRoom();
+	event.preventDefault();
+	await connectRoom();
 });
 
 messageForm.addEventListener("submit", async (event) => {
-  event.preventDefault();
-
-  if (!joinedRoom) {
-    setStatus("Join a room before sending messages.");
-    return;
-  }
-
-  const text = messageInput.value.trim();
-  if (!text) {
-    return;
-  }
-
-  try {
-    await joinedRoom.rpc.sendMessage({ text });
-    messageInput.value = "";
-  } catch (error) {
-    setStatus(error instanceof Error ? error.message : String(error));
-  }
+	event.preventDefault();
+
+	if (!joinedRoom) {
+		setStatus("Join a room before sending messages.");
+		return;
+	}
+
+	const text = messageInput.value.trim();
+	if (!text) {
+		return;
+	}
+
+	try {
+		await joinedRoom.rpc.sendMessage({ text });
+		messageInput.value = "";
+	} catch (error) {
+		setStatus(error instanceof Error ? error.message : String(error));
+	}
 });
 
 leaveButton.addEventListener("click", async () => {
-  await leaveRoom();
+	await leaveRoom();
 });
 
 presencePrevButton.addEventListener("click", async () => {
-  if (!joinedRoom || presenceOffset === 0) {
-    return;
-  }
+	if (!joinedRoom || presenceOffset === 0) {
+		return;
+	}
 
-  presenceOffset = Math.max(0, presenceOffset - presencePageSize);
-  await refreshPresence();
+	presenceOffset = Math.max(0, presenceOffset - presencePageSize);
+	await refreshPresence();
 });
 
 presenceNextButton.addEventListener("click", async () => {
-  if (!joinedRoom) {
-    return;
-  }
+	if (!joinedRoom) {
+		return;
+	}
 
-  presenceOffset += presencePageSize;
-  await refreshPresence();
+	presenceOffset += presencePageSize;
+	await refreshPresence();
 });
 
 socket.on("connect", () => {
-  setStatus("Connected. Join a room to start chatting.");
+	setStatus("Connected. Join a room to start chatting.");
 });
 
 socket.on("disconnect", () => {
-  setStatus("Disconnected from the server.");
+	setStatus("Disconnected from the server.");
 });
 
 setWorkspaceVisible(false);