@signe/room 2.6.0 → 2.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signe/room",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "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.6.0"
+    "@signe/sync": "2.7.1"
   },
   "publishConfig": {
     "access": "public"

package/readme.md

@@ -246,6 +246,76 @@ class GameRoom {
 }
 ```
 
+### Manual Synchronization
+
+By default, state changes are automatically synchronized to all clients. However, you can disable automatic synchronization and manually control when to broadcast changes using the `autoSync` option and the `$applySync` method.
+
+This is useful when you want to:
+- Batch multiple state changes before broadcasting
+- Control synchronization timing for performance optimization
+- Implement custom synchronization logic
+
+```ts
+@Room({
+  path: "game"
+})
+class GameRoom {
+  autoSync = false; // Disable automatic synchronization
+  
+  @sync() count = signal(0);
+  @sync() score = signal(0);
+  @sync() level = signal(1);
+
+  @Action("updateGameState")
+  updateGameState(player: Player, data: { count: number, score: number, level: number }) {
+    // Make multiple changes without triggering sync
+    this.count.set(data.count);
+    this.score.set(data.score);
+    this.level.set(data.level);
+    
+    // Manually trigger synchronization when ready
+    this.$applySync();
+  }
+
+  @Action("batchUpdate")
+  batchUpdate(player: Player, updates: any[]) {
+    // Apply multiple updates
+    updates.forEach(update => {
+      // ... apply updates
+    });
+    
+    // Sync all changes at once
+    this.$applySync();
+  }
+}
+```
+
+You can also toggle `autoSync` at runtime:
+
+```ts
+class GameRoom {
+  @sync() count = signal(0);
+
+  @Action("startBatchMode")
+  startBatchMode() {
+    this.$autoSync = false; // Disable auto sync
+  }
+
+  @Action("endBatchMode")
+  endBatchMode() {
+    this.$applySync(); // Sync pending changes
+    this.$autoSync = true; // Re-enable auto sync
+  }
+}
+```
+
+**Instance Properties:**
+- `$autoSync` (boolean): Controls whether synchronization happens automatically (default: `true`)
+- `$pendingSync` (Map): Stores pending synchronization changes when `autoSync` is disabled
+- `$applySync()` (method): Manually broadcasts all pending changes to all clients
+
+**Note:** When `autoSync` is disabled, changes are stored in `$pendingSync` until you call `$applySync()`. If you call `$applySync()` with no pending changes, it will broadcast the current state from `$memoryAll`, which is useful for forcing a full state synchronization.
+
 ### Connecting to World Service
 
 The World Service provides optimal room and shard assignment for distributed applications. It handles load balancing and allows clients to connect to the most appropriate server.

package/src/interfaces.ts

@@ -15,4 +15,9 @@ export interface RoomOnLeave {
 export interface RoomMethods {
   $send: (conn: Party.Connection, obj: any) => void;
   $broadcast: (obj: any) => void;
+  $applySync: () => void;
+  $sessionTransfer: (conn: Party.Connection, targetRoomId: string) => Promise<string | null>;
+  $pendingSync: Map<string, any>;
+  $memoryAll: Map<string, any>;
+  $autoSync: boolean;
 }

package/src/server.ts

@@ -246,12 +246,57 @@ export class Server implements Party.Server {
     };
 
     instance.$memoryAll = {}
+    instance.$autoSync = instance["autoSync"] !== false; // Default to true
+    instance.$pendingSync = new Map<string, any>();
     instance.$send = (conn: Party.Connection, obj: any) => {
       return this.send(conn, obj, instance)
     }
     instance.$broadcast = (obj: any) => {
       return this.broadcast(obj, instance)
     }
+    /**
+     * Applies pending synchronization changes by broadcasting them to all clients.
+     * This method is useful when autoSync is disabled and you want to manually trigger synchronization.
+     * 
+     * @method $applySync
+     * @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).
+     * 
+     * @example
+     * ```typescript
+     * // Disable auto sync
+     * instance.$autoSync = false;
+     * 
+     * // Make some changes
+     * instance.count.set(10);
+     * instance.text.set('hello');
+     * 
+     * // Manually apply sync when ready
+     * instance.$applySync();
+     * ```
+     */
+    instance.$applySync = () => {
+      let packet: any;
+      if (instance.$pendingSync.size > 0) {
+        if (options.getMemoryAll) {
+          buildObject(instance.$pendingSync, instance.$memoryAll);
+        }
+        packet = buildObject(instance.$pendingSync, instance.$memoryAll);
+        instance.$pendingSync.clear();
+      } else {
+        // No pending changes, broadcast current state from memory
+        packet = instance.$memoryAll;
+      }
+      
+      this.broadcast(
+        {
+          type: "sync",
+          value: packet,
+        },
+        instance
+      );
+    }
     instance.$sessionTransfer = async (conn: Party.Connection, targetRoomId: string) => {
       let user: any;
       
@@ -326,15 +371,28 @@ export class Server implements Party.Server {
       }
     };
 
-    // Sync callback: Broadcast changes to all clients
+    // Sync callback: Broadcast changes to all clients or store them for manual sync
     const syncCb = (values) => {
       if (options.getMemoryAll) {
         buildObject(values, instance.$memoryAll);
       }
+      // During initialization in hibernate mode, skip entirely
       if (init && this.isHibernate) {
         init = false;
         return;
       }
+      
+      // If autoSync is disabled, store changes in pendingSync instead of broadcasting
+      if (!instance.$autoSync) {
+        // Merge pending changes into $pendingSync
+        for (const [path, value] of values) {
+          instance.$pendingSync.set(path, value);
+        }
+        values.clear();
+        return;
+      }
+      
+      // Auto sync: broadcast immediately (even during init if autoSync is enabled)
       const packet = buildObject(values, instance.$memoryAll);
       this.broadcast(
         {
@@ -367,13 +425,14 @@ export class Server implements Party.Server {
 
     // Set up syncing and persistence with throttling to optimize performance
     syncClass(instance, {
-      onSync: throttle(syncCb, instance["throttleSync"] ?? 500),
-      onPersist: throttle(persistCb, instance["throttleStorage"] ?? 2000),
+      onSync: instance["throttleSync"] ? throttle(syncCb, instance["throttleSync"]) : syncCb,
+      onPersist: instance["throttleStorage"] ? throttle(persistCb, instance["throttleStorage"]) : persistCb,
     });
 
     await loadMemory();
 
     initPersist = false
+    init = false; // Allow syncs after initialization is complete
 
     return instance
   }