fix(db): reclaim collections that sync before anything subscribes

.changeset/lucky-donkeys-repeat.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/db': patch
+---
+
+Garbage collect collections that start syncing before anything subscribes to them.
+
+`startGCTimer` only ran when the last subscriber left, so a collection whose subscriber count never rose above zero never armed it. Sync started from `startSync: true`, `preload()` or `startSyncImmediate()` therefore ran forever, and a live query started that way held a subscription on every collection it read from for the lifetime of the page — regardless of how short its `gcTime` was.
+
+Framework adapters build their live query collection while rendering and subscribe once that render commits, so every render React, Vue, Svelte or Solid discards before committing — a suspended subtree, a render that throws, a time-sliced render restarted by an interleaved update — stranded a fully compiled query graph rooted at a long-lived source collection. Under a route that repeatedly re-rendered without committing this exhausted the renderer's heap.
+
+Sync starting without a subscriber now arms the same GC timer, floored at 50ms so that a subscriber arriving with the commit is never beaten to it. Collections with `gcTime: 0` still opt out of GC entirely, and the timer armed when the last subscriber leaves still fires on `gcTime` exactly.

packages/db/skills/db-core/live-queries/SKILL.md

@@ -203,7 +203,11 @@ const activeUserPosts = createLiveQueryCollection((q) =>
 Create derived collections once at module scope and reuse them. Do not recreate on every render or navigation.
 
 Live query collections default to `gcTime: 5_000`. An explicit `gcTime: 0` is
-preserved and disables garbage collection for that derived collection.
+preserved and disables garbage collection for that derived collection --
+including the reclamation of a collection that started syncing and never gained
+a subscriber. Note this is the opposite of `gcTime: 0` in TanStack Query, where
+it collects as soon as the query goes inactive; use a small positive value if
+you want prompt collection here.
 
 ## Virtual Properties
 

packages/db/skills/meta-framework/SKILL.md

@@ -373,7 +373,7 @@ export const Route = createFileRoute('/todos')({
 })
 ```
 
-Without preloading, the collection starts syncing only when the component mounts, causing a loading flash. Preloading in the route loader starts sync during navigation, making data available immediately when the component renders.
+Without preloading, the collection starts syncing when the component first renders, causing a loading flash. Preloading in the route loader starts sync during navigation, so the data is already there on that first render.
 
 ### MEDIUM Creating separate collection instances in one scope
 

packages/db/src/collection/cleanup-queue.ts

@@ -42,6 +42,15 @@ export class CleanupQueue {
 
   public cancel(key: unknown): void {
     this.tasks.delete(key)
+
+    // Retire the root timer with the last task. A non-empty queue keeps its
+    // timer even when the cancelled task was the earliest: it wakes early,
+    // finds nothing due and reschedules, which costs less than rescanning
+    // every task on each cancellation.
+    if (this.tasks.size === 0 && this.timeoutId !== null) {
+      clearTimeout(this.timeoutId)
+      this.timeoutId = null
+    }
   }
 
   /**

packages/db/src/collection/lifecycle.ts

@@ -17,6 +17,16 @@ import type { CollectionChangesManager } from './changes'
 import type { CollectionSyncManager } from './sync'
 import type { CollectionStateManager } from './state'
 
+/**
+ * Floor applied to the GC delay of a collection that started syncing before
+ * anything subscribed. Adapters build their live query while rendering and
+ * subscribe when that render commits, so the delay has to outlive that gap;
+ * `gcTime` cannot, because adapters pass a near-zero one to make teardown on
+ * unmount immediate. Does not apply to the timer armed when the last
+ * subscriber leaves, which still honours `gcTime` exactly.
+ */
+const UNSUBSCRIBED_GC_FLOOR_MS = 50
+
 export class CollectionLifecycleManager<
   TOutput extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -158,11 +168,23 @@ export class CollectionLifecycleManager<
     }
   }
 
+  /**
+   * Start the garbage collection timer for a collection with no subscribers
+   * Called when sync starts outside a subscription
+   */
+  public startGCTimerIfUnsubscribed(): void {
+    if (this.changes.activeSubscribersCount > 0) {
+      return
+    }
+
+    this.startGCTimer(UNSUBSCRIBED_GC_FLOOR_MS)
+  }
+
   /**
    * Start the garbage collection timer
    * Called when the collection becomes inactive (no subscribers)
    */
-  public startGCTimer(): void {
+  public startGCTimer(minDelay = 0): void {
     const gcTime = this.config.gcTime ?? 300000 // 5 minutes default
 
     // If gcTime is 0, negative, or non-finite (Infinity, -Infinity, NaN), GC is disabled.
@@ -172,12 +194,16 @@ export class CollectionLifecycleManager<
       return
     }
 
-    CleanupQueue.getInstance().schedule(this, gcTime, () => {
-      if (this.changes.activeSubscribersCount === 0) {
-        // Schedule cleanup during idle time to avoid blocking the UI thread
-        this.scheduleIdleCleanup()
-      }
-    })
+    CleanupQueue.getInstance().schedule(
+      this,
+      Math.max(gcTime, minDelay),
+      () => {
+        if (this.changes.activeSubscribersCount === 0) {
+          // Schedule cleanup during idle time to avoid blocking the UI thread
+          this.scheduleIdleCleanup()
+        }
+      },
+    )
   }
 
   /**

packages/db/src/collection/sync.ts

@@ -272,6 +272,12 @@ export class CollectionSyncManager<
             `Either provide a loadSubset handler or use syncMode "eager".`,
         )
       }
+
+      // Every route into sync passes through here, so it is the one place
+      // that sees sync start ahead of the subscriber that would justify it.
+      // `addSubscriber` counts itself in before calling us, so a subscription
+      // starting sync leaves the timer alone.
+      this.lifecycle.startGCTimerIfUnsubscribed()
     } catch (error) {
       this.lifecycle.setStatus(`error`)
       throw error

packages/db/tests/orphaned-live-query-gc.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest'
+import { createCollection } from '../src/collection/index.js'
+import { createLiveQueryCollection } from '../src/query/live-query-collection.js'
+import { mockSyncCollectionOptions } from './utils.js'
+
+/**
+ * A live query collection created with `startSync: true` subscribes to its
+ * source collections at construction time. `startGCTimer()` is only ever
+ * called from `removeSubscriber()` on the 1 -> 0 transition, so a collection
+ * that never gains a subscriber never arms its GC timer and is never cleaned
+ * up -- no matter how small `gcTime` is.
+ *
+ * This is exactly the state left behind by a React render attempt that is
+ * discarded before commit: `useLiveQuery` constructs the collection with
+ * `startSync: true` in the render body, and the only teardown path runs from
+ * the `useSyncExternalStore` subscribe cleanup, which never happens.
+ */
+
+type Person = { id: string; name: string; active: boolean }
+
+const GC_TIME_MS = 1
+
+const makeSource = (id: string) =>
+  createCollection(
+    mockSyncCollectionOptions<Person>({
+      id,
+      getKey: (p) => p.id,
+      initialData: [
+        { id: `1`, name: `Alice`, active: true },
+        { id: `2`, name: `Bob`, active: false },
+      ],
+    }),
+  )
+
+const makeOrphan = (source: ReturnType<typeof makeSource>, id: string) =>
+  createLiveQueryCollection({
+    id,
+    // Same two options `useLiveQuery` passes from its render body.
+    startSync: true,
+    gcTime: GC_TIME_MS,
+    query: (q) =>
+      q
+        .from({ p: source })
+        .select(({ p }) => ({ id: p.id, name: p.name, active: p.active })),
+  })
+
+// Well past gcTime, plus room for the CleanupQueue's batching microtask.
+const waitPastGcTime = () => new Promise((r) => setTimeout(r, 100))
+
+const writeToSource = (
+  source: ReturnType<typeof makeSource>,
+  person: Person,
+) => {
+  source.utils.begin()
+  source.utils.write({ type: `insert`, value: person })
+  source.utils.commit()
+}
+
+describe(`live query collections that never gain a subscriber`, () => {
+  it(`is cleaned up after gcTime even though nothing ever subscribed`, async () => {
+    const source = makeSource(`gc-single-source`)
+    expect(source.subscriberCount).toBe(0)
+
+    const orphan = makeOrphan(source, `gc-single-orphan`)
+
+    // Construction started sync, which subscribed to the source.
+    expect(source.subscriberCount).toBe(1)
+
+    await waitPastGcTime()
+
+    // Nothing ever subscribed to `orphan`, so it is unreachable from user code
+    // the moment the caller drops its reference. After gcTime it should have
+    // released the source.
+    expect(orphan.status).toBe(`cleaned-up`)
+    expect(source.subscriberCount).toBe(0)
+  })
+
+  it(`releases the source when every orphan's gcTime has elapsed`, async () => {
+    const source = makeSource(`gc-many-source`)
+    const N = 200
+
+    const counts: Array<number> = []
+    for (let i = 0; i < N; i++) {
+      makeOrphan(source, `gc-many-orphan-${i}`)
+      counts.push(source.subscriberCount)
+    }
+
+    // Strictly monotonic: every construction adds a subscription, none is
+    // ever removed.
+    expect(counts[0]).toBe(1)
+    expect(counts[N - 1]).toBe(N)
+
+    await waitPastGcTime()
+
+    console.log(
+      `[orphan-gc] after ${N} never-subscribed constructions + ${GC_TIME_MS}ms gcTime: source.subscriberCount =`,
+      source.subscriberCount,
+    )
+
+    expect(source.subscriberCount).toBe(0)
+  })
+
+  it(`stops reprocessing source changes once gcTime has elapsed`, async () => {
+    const N = 200
+
+    const bare = makeSource(`gc-cost-bare-source`)
+    const loaded = makeSource(`gc-cost-loaded-source`)
+    for (let i = 0; i < N; i++) {
+      makeOrphan(loaded, `gc-cost-orphan-${i}`)
+    }
+
+    await waitPastGcTime()
+
+    const time = (source: ReturnType<typeof makeSource>, tag: string) => {
+      const start = performance.now()
+      for (let i = 0; i < 50; i++) {
+        writeToSource(source, { id: `w${i}`, name: `W${i}`, active: true })
+      }
+      const ms = performance.now() - start
+
+      console.log(`[orphan-gc] 50 source writes (${tag}): ${ms.toFixed(2)}ms`)
+      return ms
+    }
+
+    const bareMs = time(bare, `no orphans`)
+    const loadedMs = time(loaded, `${N} orphans, all past gcTime`)
+
+    console.log(
+      `[orphan-gc] write cost multiplier with ${N} orphans:`,
+      (loadedMs / Math.max(bareMs, 0.001)).toFixed(1) + `x`,
+    )
+
+    // Orphans that were never subscribed to should have been reclaimed, so a
+    // write should cost about the same either way.
+    expect(loadedMs).toBeLessThan(bareMs * 5 + 5)
+  })
+
+  it(`retains no heap once gcTime has elapsed`, async () => {
+    const source = makeSource(`gc-heap-source`)
+    const N = 1000
+
+    const forceGc = (globalThis as { gc?: () => void }).gc
+    forceGc?.()
+    const before = process.memoryUsage().heapUsed
+
+    for (let i = 0; i < N; i++) {
+      makeOrphan(source, `gc-heap-orphan-${i}`)
+    }
+
+    await waitPastGcTime()
+    forceGc?.()
+    const after = process.memoryUsage().heapUsed
+
+    const retained = after - before
+
+    console.log(
+      `[orphan-gc] ${N} never-subscribed live queries retained ${(retained / 1024 / 1024).toFixed(1)} MB` +
+        ` (${Math.round(retained / N / 1024)} KB each), forced GC: ${forceGc ? `yes` : `unavailable`},` +
+        ` source.subscriberCount = ${source.subscriberCount}`,
+    )
+
+    expect(source.subscriberCount).toBe(0)
+    // Whatever the exact per-graph size, nothing should survive. Only
+    // meaningful when the heap can actually be collected first, so run this
+    // file under `NODE_OPTIONS=--expose-gc` for the byte assertion.
+    if (forceGc) {
+      expect(retained).toBeLessThan(N * 1024)
+    }
+  })
+
+  it(`is cleaned up when a subscriber does attach and then detach (control)`, async () => {
+    const source = makeSource(`gc-control-source`)
+    const live = makeOrphan(source, `gc-control-live`)
+
+    const subscription = live.subscribeChanges(() => {})
+    expect(live.subscriberCount).toBe(1)
+
+    subscription.unsubscribe()
+    await waitPastGcTime()
+
+    expect(live.status).toBe(`cleaned-up`)
+    expect(source.subscriberCount).toBe(0)
+  })
+})