fix: search empty state never renders due to stale fetch race condition (#144) (#146)

Co-authored-by: Ona <no-reply@ona.com>

Author: zacharias-ona

src/components/sidebar/page-search.test.tsx

@@ -79,9 +79,10 @@ describe("PageSearch", () => {
       await vi.advanceTimersByTimeAsync(350);
     });
 
-    // The fetch should have been called
+    // The fetch should have been called with the query and an abort signal
     expect(fetchMock).toHaveBeenCalledWith(
-      expect.stringContaining("zzzyyyxxxnonexistent999")
+      expect.stringContaining("zzzyyyxxxnonexistent999"),
+      expect.objectContaining({ signal: expect.any(AbortSignal) })
     );
 
     // The empty state message should be visible
@@ -144,6 +145,72 @@ describe("PageSearch", () => {
     ).toBeInTheDocument();
   });
 
+  it("aborts stale fetch when query changes rapidly", async () => {
+    // Track abort signals to verify cancellation
+    const signals: AbortSignal[] = [];
+    fetchMock.mockImplementation((_url: string | URL | Request, init?: RequestInit) => {
+      if (init?.signal) signals.push(init.signal);
+      return new Promise<Response>((resolve) => {
+        // Resolve after a delay, but only if not aborted
+        setTimeout(() => {
+          resolve(new Response(JSON.stringify({ results: [] }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }));
+        }, 100);
+      });
+    });
+
+    const user = userEvent.setup({
+      advanceTimers: vi.advanceTimersByTime,
+    });
+
+    render(<PageSearch />);
+
+    // Wait for workspace resolution
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50);
+    });
+
+    const input = screen.getByRole("combobox", { name: /search pages/i });
+    await user.click(input);
+    await user.type(input, "first");
+
+    // Advance past debounce to trigger first fetch
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(350);
+    });
+
+    // First fetch should be in-flight
+    expect(signals.length).toBe(1);
+    expect(signals[0].aborted).toBe(false);
+
+    // Type a new query before first fetch resolves
+    await user.clear(input);
+    await user.type(input, "second");
+
+    // The first signal should now be aborted
+    expect(signals[0].aborted).toBe(true);
+
+    // Advance past debounce for second query
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(350);
+    });
+
+    // Second fetch should have been called
+    expect(signals.length).toBe(2);
+
+    // Let second fetch resolve
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(150);
+    });
+
+    // Should show empty state (second query returned no results)
+    expect(
+      screen.getByText("No pages match your search")
+    ).toBeInTheDocument();
+  });
+
   it("shows skeletons while workspace is resolving even after search completes", async () => {
     // Make workspace resolution hang
     let resolveWorkspace: (value: unknown) => void;

src/components/sidebar/page-search.tsx

@@ -32,6 +32,7 @@ export function PageSearch() {
   const containerRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
 
   // Resolve workspace slug to ID
   useEffect(() => {
@@ -66,44 +67,55 @@ export function PageSearch() {
   }, [params.workspaceSlug]);
 
   const search = useCallback(
-    async (q: string) => {
+    async (q: string, signal: AbortSignal) => {
       if (!q.trim() || !workspaceId) {
-        setResults([]);
-        setLoading(false);
+        if (!signal.aborted) {
+          setResults([]);
+          setLoading(false);
+        }
         return;
       }
 
       try {
         const response = await fetch(
-          `/api/search?q=${encodeURIComponent(q.trim())}&workspace_id=${encodeURIComponent(workspaceId)}`
+          `/api/search?q=${encodeURIComponent(q.trim())}&workspace_id=${encodeURIComponent(workspaceId)}`,
+          { signal }
         );
+        if (signal.aborted) return;
         if (response.ok) {
           const data = (await response.json()) as { results: SearchResult[] };
+          if (signal.aborted) return;
           setResults(data.results);
           setSelectedIndex(0);
         } else {
           setResults([]);
         }
       } catch (error) {
+        if (signal.aborted) return;
         Sentry.captureException(error);
         setResults([]);
       } finally {
-        setLoading(false);
-        setSearched(true);
+        if (!signal.aborted) {
+          setLoading(false);
+          setSearched(true);
+        }
       }
     },
     [workspaceId]
   );
 
-  // Debounced search (300ms). The timer always fires; the search callback
-  // handles the case where workspaceId is not yet available by clearing
-  // loading. The rendering layer uses workspaceResolved to decide whether
-  // to show skeletons or the empty-state message.
+  // Debounced search with abort support. Cancels any in-flight fetch when
+  // the query or search callback changes, preventing stale responses from
+  // overwriting the current state.
   useEffect(() => {
     if (debounceRef.current) {
       clearTimeout(debounceRef.current);
       debounceRef.current = null;
     }
+    if (abortRef.current) {
+      abortRef.current.abort();
+      abortRef.current = null;
+    }
 
     if (!query.trim()) {
       setResults([]);
@@ -113,16 +125,21 @@ export function PageSearch() {
     }
 
     setLoading(true);
+    setSearched(false);
+    const controller = new AbortController();
+    abortRef.current = controller;
+
     debounceRef.current = setTimeout(() => {
       debounceRef.current = null;
-      search(query);
+      search(query, controller.signal);
     }, 300);
 
     return () => {
       if (debounceRef.current) {
         clearTimeout(debounceRef.current);
         debounceRef.current = null;
       }
+      controller.abort();
     };
   }, [query, search]);