Merge pull request #109 from MongooseMoo/agent/issue-105-channel-save-debounce

Debounce channel history persistence

Author: ctoth

src/hooks/useChannelHistory.test.tsx

@@ -188,6 +188,8 @@ describe("useChannelHistory", () => {
       }
     });
 
+    // The save effect debounces writes by SAVE_DEBOUNCE_MS (500ms), so give
+    // waitFor enough real time to let the trailing timer fire.
     await waitFor(() => {
       const saved = localStorage.getItem("channelHistory");
       expect(saved).not.toBeNull();
@@ -196,9 +198,35 @@ describe("useChannelHistory", () => {
       expect(parsed.version).toBe(1);
       expect(parsed.data.buffers.all.messages).toHaveLength(MAX_PERSISTED_ALL_MESSAGES);
       expect(parsed.data.buffers.gossip.messages).toHaveLength(MAX_PERSISTED_CHANNEL_MESSAGES);
-    });
+    }, { timeout: 2000 });
   });
 
+  it.each(["pagehide", "beforeunload"])(
+    "flushes pending channel history on %s before the debounce expires",
+    async (eventName) => {
+      const { result } = renderHook(() => useChannelHistory());
+
+      act(() => {
+        addChannelText("gossip", "Reader", "last-second message");
+      });
+
+      await waitFor(() => {
+        expect(result.current.buffers.get("all")?.messages).toHaveLength(1);
+      });
+      expect(localStorage.getItem("channelHistory")).toBeNull();
+
+      act(() => {
+        window.dispatchEvent(new Event(eventName));
+      });
+
+      const saved = localStorage.getItem("channelHistory");
+      expect(saved).not.toBeNull();
+      expect(JSON.parse(saved || "{}").data.buffers.all.messages[0].message).toBe(
+        "last-second message"
+      );
+    }
+  );
+
   it("caps older localStorage history when loading it", () => {
     localStorage.setItem("channelHistory", JSON.stringify({
       buffers: {

src/hooks/useChannelHistory.tsx

@@ -74,6 +74,11 @@ const channelHistorySchema: LocalStorageSchema<StoredChannelHistory> = {
   },
 };
 
+// Coalesce bursts of channel messages into one write instead of
+// re-serializing + persisting the whole history on every message. Mirrors
+// output.tsx's SAVE_DEBOUNCE_MS.
+const SAVE_DEBOUNCE_MS = 500;
+
 export const MAX_ALL_BUFFER_MESSAGES = 1000;
 export const MAX_CHANNEL_BUFFER_MESSAGES = 500;
 export const MAX_PERSISTED_ALL_MESSAGES = 200;
@@ -168,6 +173,43 @@ export const useChannelHistory = () => {
   const [linkPickerLinks, setLinkPickerLinks] = useState<ExtractedLink[] | null>(null);
   const lastKeyPress = useRef<{ key: string; time: number; count: number } | null>(null);
   const lastProcessedChannelEntryId = useRef(0);
+  const saveTimerRef = useRef<number | undefined>(undefined);
+  // Always holds the latest live state so the debounced timer callback and
+  // the unmount flush never persist stale values. Serialization happens in
+  // flushSave, not per change — that's the expensive half of the work.
+  const latestStateRef = useRef<{
+    buffers: Map<string, Buffer>;
+    bufferOrder: string[];
+    currentBufferIndex: number;
+    timestampsEnabled: boolean;
+  } | null>(null);
+
+  const cancelScheduledSave = useCallback(() => {
+    if (saveTimerRef.current !== undefined) {
+      window.clearTimeout(saveTimerRef.current);
+      saveTimerRef.current = undefined;
+    }
+  }, []);
+
+  const flushSave = useCallback(() => {
+    const latest = latestStateRef.current;
+    if (!latest) {
+      return;
+    }
+    saveStoredValue(channelHistorySchema, {
+      buffers: serializeBuffersForStorage(latest.buffers),
+      bufferOrder: latest.bufferOrder,
+      currentBufferIndex: latest.currentBufferIndex,
+      timestampsEnabled: latest.timestampsEnabled,
+    });
+  }, []);
+
+  const flushPendingSave = useCallback(() => {
+    if (saveTimerRef.current !== undefined) {
+      cancelScheduledSave();
+      flushSave();
+    }
+  }, [cancelScheduledSave, flushSave]);
 
   // Load state through the shared versioned persistence owner on mount.
   useEffect(() => {
@@ -195,15 +237,38 @@ export const useChannelHistory = () => {
     setTimestampsEnabled(parsed.timestampsEnabled ?? true);
   }, []);
 
-  // Save state through the same schema whenever it changes.
+  // Save state through the same schema whenever it changes, debounced so a
+  // burst of channel messages coalesces into one write instead of
+  // re-serializing the whole history on every message.
   useEffect(() => {
-    saveStoredValue(channelHistorySchema, {
-        buffers: serializeBuffersForStorage(buffers),
-        bufferOrder,
-        currentBufferIndex,
-        timestampsEnabled,
-    });
-  }, [buffers, bufferOrder, currentBufferIndex, timestampsEnabled]);
+    latestStateRef.current = {
+      buffers,
+      bufferOrder,
+      currentBufferIndex,
+      timestampsEnabled,
+    };
+
+    cancelScheduledSave();
+    saveTimerRef.current = window.setTimeout(() => {
+      saveTimerRef.current = undefined;
+      flushSave();
+    }, SAVE_DEBOUNCE_MS);
+  }, [buffers, bufferOrder, currentBufferIndex, timestampsEnabled, cancelScheduledSave, flushSave]);
+
+  // React root cleanup is not guaranteed during a reload or tab close, so
+  // synchronously flush pending history from the browser lifecycle as well as
+  // on unmount. The pending-timer check keeps consecutive lifecycle events
+  // (for example, beforeunload followed by pagehide) idempotent.
+  useEffect(() => {
+    window.addEventListener("pagehide", flushPendingSave);
+    window.addEventListener("beforeunload", flushPendingSave);
+
+    return () => {
+      window.removeEventListener("pagehide", flushPendingSave);
+      window.removeEventListener("beforeunload", flushPendingSave);
+      flushPendingSave();
+    };
+  }, [flushPendingSave]);
 
   // Handle channel messages. The "all" buffer is the aggregate of every
   // channel, so each channel message is appended both to its own channel