fix: improve editor autosave

packages/lib/client-only/hooks/use-envelope-autosave.ts

@@ -1,48 +1,97 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+/**
+ * Debounced, self-serialising autosave helper.
+ *
+ * Guarantees:
+ * - At most one `saveFn` call is in-flight at any time, so saves can never run
+ *   concurrently and land out of order.
+ * - The most recently queued payload is always committed. In particular calling
+ *   `flush()` while an older save is still in-flight waits for that save AND then
+ *   commits any newer payload queued in the meantime.
+ *
+ * The second guarantee is the important one: previously `flush()` would await an
+ * in-flight save and return immediately, silently dropping any newer payload that
+ * had been queued (and whose debounce timer it had just cleared). Under network
+ * lag this lost the user's latest changes - e.g. a freshly typed recipient would
+ * never be persisted and the editor would fall back to the "Recipient 1"
+ * placeholder.
+ */
 export function useEnvelopeAutosave<T>(saveFn: (data: T) => Promise<void>, delay = 1000) {
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastArgsRef = useRef<T | null>(null);
-  const pendingPromiseRef = useRef<Promise<void> | null>(null);
+
+  // The most recently queued, not-yet-saved payload. Wrapped in an object so that
+  // a queued falsy payload is still distinguishable from "nothing queued".
+  const pendingRef = useRef<{ value: T } | null>(null);
+
+  // The in-flight commit pump. Concurrent callers await this same promise rather
+  // than starting a second, overlapping save.
+  const commitPromiseRef = useRef<Promise<void> | null>(null);
+
+  // Always invoke the latest `saveFn` (which may close over fresh state) without
+  // having to rebuild `triggerSave`/`flush` on every render.
+  const saveFnRef = useRef(saveFn);
+  saveFnRef.current = saveFn;
 
   const [isPending, setIsPending] = useState(false);
   const [isCommiting, setIsCommiting] = useState(false);
 
+  /**
+   * Drains the queued payload, running `saveFn` one save at a time until nothing
+   * is left to save. If a newer payload is queued while a save is in-flight it is
+   * picked up on the next loop iteration, so the latest changes are never lost.
+   */
+  const commit = useCallback((): Promise<void> => {
+    // A pump is already running → share it instead of starting a second one.
+    if (commitPromiseRef.current) {
+      return commitPromiseRef.current;
+    }
+
+    // Nothing queued and nothing in-flight → no work to do.
+    if (!pendingRef.current) {
+      return Promise.resolve();
+    }
+
+    const pump = (async () => {
+      try {
+        setIsCommiting(true);
+
+        while (pendingRef.current) {
+          const { value } = pendingRef.current;
+          pendingRef.current = null;
+
+          await saveFnRef.current(value);
+        }
+      } finally {
+        // eslint-disable-next-line require-atomic-updates
+        commitPromiseRef.current = null;
+        setIsCommiting(false);
+        setIsPending(false);
+      }
+    })();
+
+    commitPromiseRef.current = pump;
+
+    return pump;
+  }, []);
+
   const triggerSave = useCallback(
     (data: T) => {
-      lastArgsRef.current = data;
+      pendingRef.current = { value: data };
 
-      // A debounce or promise means something is pending
+      // A debounce timer or an in-flight save means something is pending.
       setIsPending(true);
 
       if (timeoutRef.current) {
         clearTimeout(timeoutRef.current);
       }
 
-      // eslint-disable-next-line @typescript-eslint/no-misused-promises
-      timeoutRef.current = setTimeout(async () => {
-        if (!lastArgsRef.current) {
-          return;
-        }
-
-        const args = lastArgsRef.current;
-        lastArgsRef.current = null;
+      timeoutRef.current = setTimeout(() => {
         timeoutRef.current = null;
-
-        setIsCommiting(true);
-        pendingPromiseRef.current = saveFn(args);
-
-        try {
-          await pendingPromiseRef.current;
-        } finally {
-          // eslint-disable-next-line require-atomic-updates
-          pendingPromiseRef.current = null;
-          setIsCommiting(false);
-          setIsPending(false);
-        }
+        void commit();
       }, delay);
     },
-    [saveFn, delay],
+    [commit, delay],
   );
 
   const flush = useCallback(async () => {
@@ -51,34 +100,12 @@ export function useEnvelopeAutosave<T>(saveFn: (data: T) => Promise<void>, delay
       timeoutRef.current = null;
     }
 
-    if (pendingPromiseRef.current) {
-      // Already running → wait for it
-      await pendingPromiseRef.current;
-      return;
-    }
-
-    if (lastArgsRef.current) {
-      const args = lastArgsRef.current;
-      lastArgsRef.current = null;
-
-      setIsCommiting(true);
-      setIsPending(true);
-
-      pendingPromiseRef.current = saveFn(args);
-      try {
-        await pendingPromiseRef.current;
-      } finally {
-        // eslint-disable-next-line require-atomic-updates
-        pendingPromiseRef.current = null;
-        setIsCommiting(false);
-        setIsPending(false);
-      }
-    }
-  }, [saveFn]);
+    await commit();
+  }, [commit]);
 
   useEffect(() => {
     const handleBeforeUnload = () => {
-      if (timeoutRef.current || pendingPromiseRef.current) {
+      if (timeoutRef.current || pendingRef.current || commitPromiseRef.current) {
         void flush();
       }
     };