room-kit 1.0.2 → 1.0.5

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlycliches/room-kit",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Type-safe channel primitives for Socket.IO events, requests, streams, and room membership.",
   "exports": "./src/index.ts",
   "publish": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "room-kit",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Type-safe room membership, presence, and realtime messaging for Socket.IO.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -29,6 +29,7 @@ export type {
     RoomServerHandlers,
     RoomSnapshot,
     ServerAdmission,
+    ServerAdmissionInput,
     ServerSocketLike,
     VisibleMemberFor,
 } from "./types";

package/src/server.ts

@@ -3,6 +3,7 @@ import type {
     EventEmitApi,
     EventMetaFor,
     JoinRequest,
+    MemberProfileFor,
     PresenceFor,
     PresenceListQuery,
     PresencePageFor,
@@ -10,6 +11,7 @@ import type {
     RoomMemberSnapshot,
     RoomDefinition,
     RoomEvents,
+    RoomProfileFor,
     RoomServerAdapter,
     RoomServerBroadcastApi,
     RoomServerHandle,
@@ -18,6 +20,7 @@ import type {
     RoomSnapshot,
     ServerSocketLike,
     ServerStateFor,
+    ServerAdmission,
     PresenceValueFor,
     VisibleMemberFor,
 } from "./types";
@@ -178,6 +181,7 @@ type NamespaceState = {
 type AuthCacheEntry<TAuth> = {
     pending?: Promise<TAuth>;
     value?: TAuth;
+    hasValue?: boolean;
 };
 
 const namespaceStates = new WeakMap<object, NamespaceState>();
@@ -247,11 +251,12 @@ export function serveRoomType<TRoom extends RoomDefinition<any>, TAuth = unknown
                 roomProfile: undefined,
                 serverState: initialState,
             });
-            const admission = await handlers.admit(frame.payload as JoinRequest<TRoom>, provisional);
-            assertMatchingRoomIds(
+            const admission = await resolveAdmission(
+                socket,
+                handlers,
                 requestedRoomId,
-                admission.roomId,
-                (admission.roomProfile as { roomId: string }).roomId,
+                frame.payload as JoinRequest<TRoom>,
+                provisional,
             );
 
             const roomState: RoomState<TRoom> = roomCollection.get(admission.roomId) ?? {
@@ -650,7 +655,7 @@ async function resolveSocketAuth<TAuth>(
         return entry.pending;
     }
 
-    if (entry.value === undefined) {
+    if (!entry.hasValue) {
         const pending = Promise.resolve(handlers.onAuth?.(socket) as TAuth)
             .then((auth) => {
                 if (auth === false) {
@@ -660,6 +665,7 @@ async function resolveSocketAuth<TAuth>(
 
                 const current = authCache.get(socket) ?? {};
                 current.value = auth;
+                current.hasValue = true;
                 current.pending = undefined;
                 authCache.set(socket, current);
                 return auth;
@@ -692,6 +698,26 @@ async function resolveSocketAuth<TAuth>(
     handleRejectedAuth(authCache, socket, decision);
 }
 
+async function resolveAdmission<TRoom extends RoomDefinition<any>, TAuth>(
+    socket: ServerSocketLike,
+    handlers: RoomServerHandlers<TRoom, TAuth>,
+    joinRoomId: string,
+    join: JoinRequest<TRoom>,
+    ctx: RoomServerContext<TRoom, TAuth>,
+): Promise<ServerAdmission<TRoom>> {
+    const admission = handlers.admit ? await Promise.resolve(handlers.admit(join, ctx)) : {};
+    const roomId = admission.roomId ?? joinRoomId;
+    const roomProfile = admission.roomProfile ?? ({ roomId } as RoomProfileFor<TRoom>);
+    assertMatchingRoomIds(joinRoomId, roomId, (roomProfile as { roomId: string }).roomId);
+
+    return {
+        roomId,
+        memberId: admission.memberId ?? socket.id,
+        memberProfile: admission.memberProfile ?? ({} as MemberProfileFor<TRoom>),
+        roomProfile,
+    };
+}
+
 function handleRejectedAuth<TAuth>(
     authCache: WeakMap<ServerSocketLike, AuthCacheEntry<TAuth>>,
     socket: ServerSocketLike,

package/src/types.ts

@@ -381,7 +381,12 @@ export type EventListenApi<TRoom extends RoomDefinition<any>> = {
 };
 
 /**
- * Successful admission payload returned by `handlers.admit`.
+ * Successful admission payload used by the runtime after admission is
+ * normalized.
+ *
+ * The server persists these values as the membership record for the socket.
+ * `roomId`, `memberId`, `memberProfile`, and `roomProfile` must all be
+ * present in the finalized admission record.
  */
 export type ServerAdmission<TRoom extends RoomDefinition<any>> = {
     roomId: string;
@@ -390,6 +395,24 @@ export type ServerAdmission<TRoom extends RoomDefinition<any>> = {
     roomProfile: RoomProfileFor<TRoom>;
 };
 
+/**
+ * Partial admission payload accepted from `handlers.admit`.
+ *
+ * Handlers may return only the fields they want to override. The runtime fills
+ * missing values with:
+ *
+ * - `roomId`: the join request room id
+ * - `memberId`: the connected socket id
+ * - `memberProfile`: an empty object
+ * - `roomProfile`: an object with the resolved `roomId`
+ *
+ * The runtime still validates that any supplied `roomId` matches the join
+ * request and that any supplied `roomProfile.roomId` matches the resolved room
+ * id.
+ *
+ */
+export type ServerAdmissionInput<TRoom extends RoomDefinition<any>> = Partial<ServerAdmission<TRoom>>;
+
 /**
  * Optional decision result returned by `revalidateAuth`.
  *
@@ -407,10 +430,6 @@ export type AuthRevalidationDecision<TAuth> =
         message?: string;
     };
 
-type IsUnknown<T> = unknown extends T
-    ? ([T] extends [unknown] ? true : false)
-    : false;
-
 type RoomServerHandlersCommon<TRoom extends RoomDefinition<any>, TAuth> = {
     initState?(join: JoinRequest<TRoom>): Promise<ServerStateFor<TRoom>> | ServerStateFor<TRoom>;
     /**
@@ -428,7 +447,13 @@ type RoomServerHandlersCommon<TRoom extends RoomDefinition<any>, TAuth> = {
      * `{ kind: "reject", message }` to reject the operation.
      */
     revalidateAuth?(socket: ServerSocketLike, auth: TAuth): Promise<AuthRevalidationDecision<TAuth> | void> | AuthRevalidationDecision<TAuth> | void;
-    admit(join: JoinRequest<TRoom>, ctx: RoomServerContext<TRoom, TAuth>): Promise<ServerAdmission<TRoom>> | ServerAdmission<TRoom>;
+    /**
+     * Optional join admission hook.
+     *
+     * Return only the pieces you want to override. Missing fields are filled
+     * by the runtime.
+     */
+    admit?(join: JoinRequest<TRoom>, ctx: RoomServerContext<TRoom, TAuth>): Promise<ServerAdmissionInput<TRoom>> | ServerAdmissionInput<TRoom>;
     /**
      * Called once when a server socket disconnects.
      *
@@ -459,19 +484,21 @@ type RoomServerHandlersCommon<TRoom extends RoomDefinition<any>, TAuth> = {
 /**
  * Server handler contract for a room type.
  *
- * `onAuth` is required when `TAuth` is explicitly typed to a non-`unknown`
- * shape, and optional otherwise.
+ * `onAuth` and `admit` are both optional.
  *
- * Returning `false` rejects the socket before any room state is initialized.
+ * When `onAuth` is omitted, the socket is accepted with an `undefined` auth
+ * value. Returning `false` from `onAuth` still rejects the socket before room
+ * initialization.
+ *
+ * When `admit` is omitted, the runtime derives the admission record from the
+ * join request and socket id. When `admit` is present, it may return a partial
+ * admission and the server will fill in any missing fields as described by
+ * `ServerAdmissionInput`.
  */
 export type RoomServerHandlers<TRoom extends RoomDefinition<any>, TAuth = unknown> =
-    IsUnknown<TAuth> extends true
-        ? RoomServerHandlersCommon<TRoom, TAuth> & {
-            onAuth?(socket: ServerSocketLike): Promise<TAuth | false> | TAuth | false;
-        }
-        : RoomServerHandlersCommon<TRoom, TAuth> & {
-            onAuth(socket: ServerSocketLike): Promise<TAuth | false> | TAuth | false;
-        };
+    RoomServerHandlersCommon<TRoom, TAuth> & {
+        onAuth?(socket: ServerSocketLike): Promise<TAuth | false> | TAuth | false;
+    };
 
 /**
  * Context provided to server handlers (`admit`, `rpc`, `events`, join/leave).

package/test/room.spec.ts

@@ -875,6 +875,77 @@ describe("room kit", () => {
 		connection.close();
 	});
 
+	it("uses default auth and admission when handlers are omitted", async () => {
+		const namespace = new MockNamespace();
+		const roomType = createRoomType("default-server-config", "list");
+		const { client, connection, stop } = createClientPair(namespace, "alice-socket", roomType, {});
+
+		const joined = await client.join({
+			roomId: "room-1",
+			roomKey: "shared-key",
+			userId: "alice",
+			userName: "Ada",
+		});
+
+		expect(joined.memberId).toBe("alice-socket");
+		expect(joined.roomProfile).toMatchObject({
+			roomId: "room-1",
+		});
+		expect(stop.room("room-1")).toMatchObject({
+			roomId: "room-1",
+			members: [
+				{
+					memberId: "alice-socket",
+					memberProfile: {},
+				},
+			],
+		});
+
+		stop.cleanup();
+		connection.close();
+	});
+
+	it("fills in omitted admission fields", async () => {
+		const namespace = new MockNamespace();
+		const roomType = createRoomType("partial-admission", "list");
+		const handlers: RoomServerHandlers<typeof roomType> = {
+			admit: (join) => ({
+				memberProfile: {
+					userId: join.userId,
+					userName: join.userName,
+				},
+			}),
+		};
+		const { client, connection, stop } = createClientPair(namespace, "alice-socket", roomType, handlers);
+
+		const joined = await client.join({
+			roomId: "room-1",
+			roomKey: "shared-key",
+			userId: "alice",
+			userName: "Ada",
+		});
+
+		expect(joined.memberId).toBe("alice-socket");
+		expect(joined.roomProfile).toMatchObject({
+			roomId: "room-1",
+		});
+		expect(stop.room("room-1")).toMatchObject({
+			roomId: "room-1",
+			members: [
+				{
+					memberId: "alice-socket",
+					memberProfile: {
+						userId: "alice",
+						userName: "Ada",
+					},
+				},
+			],
+		});
+
+		stop.cleanup();
+		connection.close();
+	});
+
 	it("rejects when onAuth fails", async () => {
 		const namespace = new MockNamespace();
 		const roomType = createRoomType("reject-auth", "list");