feat: implement idle cleanup for collection garbage collection (#590)

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

.changeset/silent-readers-report.md

@@ -0,0 +1,16 @@
+---
+"@tanstack/db": patch
+---
+
+Implement idle cleanup for collection garbage collection
+
+Collection cleanup operations now use `requestIdleCallback()` to prevent blocking the UI thread during garbage collection. This improvement ensures better performance by scheduling cleanup during browser idle time rather than immediately when collections have no active subscribers.
+
+**Key improvements:**
+
+- Non-blocking cleanup operations that don't interfere with user interactions
+- Automatic fallback to `setTimeout` for older browsers without `requestIdleCallback` support
+- Proper callback management to prevent race conditions during cleanup rescheduling
+- Maintains full backward compatibility with existing collection lifecycle behavior
+
+This addresses performance concerns where collection cleanup could cause UI thread blocking during active application usage.

packages/db/src/collection/lifecycle.ts

@@ -2,6 +2,11 @@ import {
   CollectionInErrorStateError,
   InvalidCollectionStatusTransitionError,
 } from "../errors"
+import {
+  safeCancelIdleCallback,
+  safeRequestIdleCallback,
+} from "../utils/browser-polyfills"
+import type { IdleCallbackDeadline } from "../utils/browser-polyfills"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { CollectionConfig, CollectionStatus } from "../types"
 import type { CollectionEventsManager } from "./events"
@@ -29,6 +34,7 @@ export class CollectionLifecycleManager<
   public hasReceivedFirstCommit = false
   public onFirstReadyCallbacks: Array<() => void> = []
   public gcTimeoutId: ReturnType<typeof setTimeout> | null = null
+  private idleCallbackId: number | null = null
 
   /**
    * Creates a new CollectionLifecycleManager instance
@@ -167,9 +173,8 @@ export class CollectionLifecycleManager<
 
     this.gcTimeoutId = setTimeout(() => {
       if (this.changes.activeSubscribersCount === 0) {
-        // We call the main collection cleanup, not just the one for the
-        // lifecycle manager
-        this.cleanup()
+        // Schedule cleanup during idle time to avoid blocking the UI thread
+        this.scheduleIdleCleanup()
       }
     }, gcTime)
   }
@@ -183,6 +188,77 @@ export class CollectionLifecycleManager<
       clearTimeout(this.gcTimeoutId)
       this.gcTimeoutId = null
     }
+    // Also cancel any pending idle cleanup
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+      this.idleCallbackId = null
+    }
+  }
+
+  /**
+   * Schedule cleanup to run during browser idle time
+   * This prevents blocking the UI thread during cleanup operations
+   */
+  private scheduleIdleCleanup(): void {
+    // Cancel any existing idle callback
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+    }
+
+    // Schedule cleanup with a timeout of 1 second
+    // This ensures cleanup happens even if the browser is busy
+    this.idleCallbackId = safeRequestIdleCallback(
+      (deadline) => {
+        // Perform cleanup if we still have no subscribers
+        if (this.changes.activeSubscribersCount === 0) {
+          const cleanupCompleted = this.performCleanup(deadline)
+          // Only clear the callback ID if cleanup actually completed
+          if (cleanupCompleted) {
+            this.idleCallbackId = null
+          }
+        } else {
+          // No need to cleanup, clear the callback ID
+          this.idleCallbackId = null
+        }
+      },
+      { timeout: 1000 }
+    )
+  }
+
+  /**
+   * Perform cleanup operations, optionally in chunks during idle time
+   * @returns true if cleanup was completed, false if it was rescheduled
+   */
+  private performCleanup(deadline?: IdleCallbackDeadline): boolean {
+    // If we have a deadline, we can potentially split cleanup into chunks
+    // For now, we'll do all cleanup at once but check if we have time
+    const hasTime =
+      !deadline || deadline.timeRemaining() > 0 || deadline.didTimeout
+
+    if (hasTime) {
+      // Perform all cleanup operations
+      this.events.cleanup()
+      this.sync.cleanup()
+      this.state.cleanup()
+      this.changes.cleanup()
+      this.indexes.cleanup()
+
+      if (this.gcTimeoutId) {
+        clearTimeout(this.gcTimeoutId)
+        this.gcTimeoutId = null
+      }
+
+      this.hasBeenReady = false
+      this.onFirstReadyCallbacks = []
+
+      // Set status to cleaned-up
+      this.setStatus(`cleaned-up`)
+      return true
+    } else {
+      // If we don't have time, reschedule for the next idle period
+      this.scheduleIdleCleanup()
+      return false
+    }
   }
 
   /**
@@ -201,21 +277,13 @@ export class CollectionLifecycleManager<
   }
 
   public cleanup(): void {
-    this.events.cleanup()
-    this.sync.cleanup()
-    this.state.cleanup()
-    this.changes.cleanup()
-    this.indexes.cleanup()
-
-    if (this.gcTimeoutId) {
-      clearTimeout(this.gcTimeoutId)
-      this.gcTimeoutId = null
+    // Cancel any pending idle cleanup
+    if (this.idleCallbackId !== null) {
+      safeCancelIdleCallback(this.idleCallbackId)
+      this.idleCallbackId = null
     }
 
-    this.hasBeenReady = false
-    this.onFirstReadyCallbacks = []
-
-    // Set status to cleaned-up
-    this.setStatus(`cleaned-up`)
+    // Perform cleanup immediately (used when explicitly called)
+    this.performCleanup()
   }
 }

packages/db/src/utils/browser-polyfills.ts

@@ -0,0 +1,39 @@
+// Type definitions for requestIdleCallback - compatible with existing browser types
+export type IdleCallbackDeadline = {
+  didTimeout: boolean
+  timeRemaining: () => number
+}
+
+export type IdleCallbackFunction = (deadline: IdleCallbackDeadline) => void
+
+const requestIdleCallbackPolyfill = (
+  callback: IdleCallbackFunction
+): number => {
+  // Use a very small timeout for the polyfill to simulate idle time
+  const timeout = 0
+  const timeoutId = setTimeout(() => {
+    callback({
+      didTimeout: true, // Always indicate timeout for the polyfill
+      timeRemaining: () => 50, // Return some time remaining for polyfill
+    })
+  }, timeout)
+  return timeoutId as unknown as number
+}
+
+const cancelIdleCallbackPolyfill = (id: number): void => {
+  clearTimeout(id as unknown as ReturnType<typeof setTimeout>)
+}
+
+export const safeRequestIdleCallback: (
+  callback: IdleCallbackFunction,
+  options?: { timeout?: number }
+) => number =
+  typeof window !== `undefined` && `requestIdleCallback` in window
+    ? (callback, options) =>
+        (window as any).requestIdleCallback(callback, options)
+    : (callback, _options) => requestIdleCallbackPolyfill(callback)
+
+export const safeCancelIdleCallback: (id: number) => void =
+  typeof window !== `undefined` && `cancelIdleCallback` in window
+    ? (id) => (window as any).cancelIdleCallback(id)
+    : cancelIdleCallbackPolyfill

packages/db/tests/collection-lifecycle.test.ts

@@ -25,6 +25,10 @@ describe(`Collection Lifecycle Management`, () => {
       timeoutCallbacks.delete(id)
     })
 
+    // Mock requestIdleCallback - in tests, it falls back to setTimeout
+    // which we're already mocking, so the idle callback will be triggered
+    // through our mockSetTimeout
+
     global.setTimeout = mockSetTimeout as any
     global.clearTimeout = mockClearTimeout as any
   })
@@ -43,6 +47,14 @@ describe(`Collection Lifecycle Management`, () => {
     }
   }
 
+  const triggerAllTimeouts = () => {
+    const callbacks = Array.from(timeoutCallbacks.entries())
+    callbacks.forEach(([id, callback]) => {
+      callback()
+      timeoutCallbacks.delete(id)
+    })
+  }
+
   describe(`Collection Status Tracking`, () => {
     it(`should start with idle status and transition to ready after first commit when startSync is false`, () => {
       let beginCallback: (() => void) | undefined
@@ -300,14 +312,18 @@ describe(`Collection Lifecycle Management`, () => {
       const subscription = collection.subscribeChanges(() => {})
       subscription.unsubscribe()
 
-      expect(collection.status).toBe(`loading`) // or "ready"
+      expect(collection.status).toBe(`loading`)
 
-      // Trigger GC timeout
-      const timerId = mockSetTimeout.mock.results[0]?.value
-      if (timerId) {
-        triggerTimeout(timerId)
+      // Trigger GC timeout - this will schedule the idle cleanup
+      const gcTimerId = mockSetTimeout.mock.results[0]?.value
+      if (gcTimerId) {
+        triggerTimeout(gcTimerId)
       }
 
+      // Now trigger all remaining timeouts to handle the idle callback
+      // (which is implemented via setTimeout in our polyfill)
+      triggerAllTimeouts()
+
       expect(collection.status).toBe(`cleaned-up`)
     })