@signe/room 2.7.2 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signe/room",
-  "version": "2.7.2",
+  "version": "2.8.0",
   "description": "",
   "main": "./dist/index.js",
   "keywords": [],
@@ -17,7 +17,7 @@
     "dset": "^3.1.3",
     "partysocket": "^1.0.1",
     "zod": "^3.23.8",
-    "@signe/sync": "2.7.2"
+    "@signe/sync": "2.8.0"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -134,6 +134,73 @@ You can return:
 
 ## Advanced Features
 
+### Session Transfer
+
+You can transfer a user's session from one room to another using `$sessionTransfer`.
+This preserves the same session id (privateId) across rooms.
+
+Server-side (inside a room or action):
+
+```ts
+@Action("transfer")
+async transfer(player: Player, data: { targetRoomId: string }, conn: Party.Connection) {
+  const transferToken = await this.$sessionTransfer(conn, data.targetRoomId);
+  return { transferToken };
+}
+```
+
+Client-side:
+- Connect to the target room with the same session id (`privateId`).
+- You can pass it as `id` in `connectionRoom` options from `@signe/sync/client`.
+- The target room restores the session and user data.
+
+Example (client):
+```ts
+import { connectionRoom } from "@signe/sync/client";
+
+await connectionRoom(
+  {
+    host: "https://your-host",
+    room: "targetRoomId",
+    id: "private-session-id",
+  },
+  roomInstance
+);
+```
+
+Optional: hydrate transferred snapshots before loading
+
+If your user snapshot contains ids for complex instances (e.g. inventory items),
+implement `onSessionRestore` on the room to resolve ids into instances before `load`.
+
+```ts
+class GameRoom {
+  async onSessionRestore({ userSnapshot }) {
+    if (Array.isArray(userSnapshot.items)) {
+      const items = await this.itemRegistry.resolveMany(userSnapshot.items);
+      return { ...userSnapshot, items };
+    }
+    return userSnapshot;
+  }
+}
+```
+
+### Snapshot Hydration (Ids -> Instances)
+
+When a snapshot only contains ids for complex objects, you need to resolve them
+before calling `load`. This is useful even outside session transfer.
+
+```ts
+const snapshot = createStatesSnapshotDeep(user);
+
+// Resolve ids to instances
+const items = await itemRegistry.resolveMany(snapshot.items);
+
+// Hydrate and load
+const hydrated = { ...snapshot, items };
+load(user, hydrated, true);
+```
+
 ### Room Configuration
 
 The `@Room` decorator accepts various configuration options:
@@ -571,4 +638,4 @@ test('test', async () => {
 
 ## License
 
-MIT
+MIT

package/src/server.ts

@@ -6,7 +6,8 @@ import {
   load,
   syncClass,
   DELETE_TOKEN,
-  generateShortUUID
+  generateShortUUID,
+  createStatesSnapshotDeep
 } from "@signe/sync";
 import type * as Party from "./types/party";
 import {
@@ -248,6 +249,7 @@ export class Server implements Party.Server {
     instance.$memoryAll = {}
     instance.$autoSync = instance["autoSync"] !== false; // Default to true
     instance.$pendingSync = new Map<string, any>();
+    instance.$pendingInitialSync = new Map<Party.Connection, string>(); // Store connections waiting for initial sync with their publicId
     instance.$send = (conn: Party.Connection, obj: any) => {
       return this.send(conn, obj, instance)
     }
@@ -262,6 +264,7 @@ export class Server implements Party.Server {
      * @description Broadcasts all pending synchronization changes and clears the pending queue.
      * If there are pending changes, they are merged with $memoryAll and broadcast. If there are no
      * pending changes, it broadcasts the current state from $memoryAll (useful for forcing a full sync).
+     * Also sends initial sync to connections that were waiting for it (with their pId).
      * 
      * @example
      * ```typescript
@@ -289,13 +292,28 @@ export class Server implements Party.Server {
         packet = instance.$memoryAll;
       }
       
-      this.broadcast(
-        {
+      // Send initial sync to connections that were waiting for it (with their pId)
+      const pendingConnections = new Set(instance.$pendingInitialSync.keys());
+      for (const [conn, publicId] of instance.$pendingInitialSync) {
+        this.send(conn, {
           type: "sync",
-          value: packet,
-        },
-        instance
-      );
+          value: {
+            pId: publicId,
+            ...packet,
+          },
+        }, instance);
+      }
+      instance.$pendingInitialSync.clear();
+      
+      // Broadcast to all other connections (excluding those that just received initial sync)
+      for (const conn of this.room.getConnections()) {
+        if (!pendingConnections.has(conn)) {
+          this.send(conn, {
+            type: "sync",
+            value: packet,
+          }, instance);
+        }
+      }
     }
     instance.$sessionTransfer = async (conn: Party.Connection, targetRoomId: string) => {
       let user: any;
@@ -339,7 +357,7 @@ export class Server implements Party.Server {
       }
 
       // Create a snapshot of the user state
-      const userSnapshot = createStatesSnapshot(user);
+      const userSnapshot = createStatesSnapshotDeep(user);
 
       const transferData = {
         privateId,
@@ -645,7 +663,7 @@ export class Server implements Party.Server {
         } else {
           user = isClass(classType) ? new classType() : classType(conn, ctx);
           signal()[publicId] = user;
-          const snapshot = createStatesSnapshot(user);
+          const snapshot = createStatesSnapshotDeep(user);
           this.room.storage.put(`${usersPropName}.${publicId}`, snapshot);
         }
       }
@@ -678,8 +696,8 @@ export class Server implements Party.Server {
     await awaitReturn(subRoom["onJoin"]?.(user, conn, ctx));
 
     // Send initial sync data with both IDs to the new connection
-    // Only send if autoSync is enabled (default behavior)
     if (subRoom.$autoSync) {
+      // Auto sync enabled: send immediately
       this.send(conn, {
         type: "sync",
         value: {
@@ -687,6 +705,9 @@ export class Server implements Party.Server {
           ...subRoom.$memoryAll,
         },
       }, subRoom);
+    } else {
+      // Auto sync disabled: store connection to receive sync on next $applySync()
+      subRoom.$pendingInitialSync.set(conn, publicId);
     }
   }
 
@@ -1039,6 +1060,11 @@ export class Server implements Party.Server {
       return;
     }
 
+    // Clean up pending initial sync for this connection
+    if (subRoom.$pendingInitialSync) {
+      subRoom.$pendingInitialSync.delete(conn);
+    }
+
     const signal = this.getUsersProperty(subRoom);
 
     if (!conn.state) {
@@ -1156,15 +1182,26 @@ export class Server implements Party.Server {
           
           // Create new user instance
           const user = isClass(classType) ? new classType() : classType();
+
+          const hydratedSnapshot =
+            (await awaitReturn(
+              subRoom["onSessionRestore"]?.({
+                userSnapshot,
+                publicId,
+                privateId,
+                sessionState,
+                room: this.room,
+              })
+            )) ?? userSnapshot;
           
           // Load user data from snapshot
-          load(user, userSnapshot, true);
+          load(user, hydratedSnapshot, true);
           
           // Add user to signal
           signal()[publicId] = user;
 
           // Save user snapshot to storage
-          await this.room.storage.put(`${usersPropName}.${publicId}`, userSnapshot);
+          await this.room.storage.put(`${usersPropName}.${publicId}`, hydratedSnapshot);
         }
       }