fix: prevent stale query cache from re-inserting deleted items (#1387)

* test: add stale cache consistency test for deleted item re-insertion

Adds a test that verifies deleted items are not re-inserted into syncedData
when a destroyed query observer is recreated and picks up stale TanStack Query
cache data (gcTime > 0).

Reproduces the scenario from #1354.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: apply automated fixes

* fix: update stale query cache entries on manual writes to prevent ghost items

updateCacheData previously only updated active query cache entries tracked in
hashToQueryKey. Stale cache entries from destroyed observers (kept alive by
gcTime > 0) were never updated, causing syncedData and the TQ cache to diverge.
When a new observer later picked up stale cache data, makeQueryResultHandler
would re-insert deleted items or revert updated values.

Now uses queryCache.findAll({ queryKey: baseKey }) to update all matching cache
entries (active and stale). Also adds prefix validation for function-based
queryKey to ensure derived keys extend the base key prefix.

Fixes #1354
Fixes #1385

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: add changeset for stale cache fix

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

.changeset/stale-cache-ghost-items.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/query-db-collection': patch
+---
+
+fix: Prevent stale query cache from re-inserting deleted items when a destroyed observer is recreated with gcTime > 0.

packages/query-db-collection/src/query.ts

@@ -558,6 +558,33 @@ export function queryCollectionOptions(
   // Default to eager sync mode if not provided
   const syncMode = baseCollectionConfig.syncMode ?? `eager`
 
+  // Compute the base query key once for cache lookups.
+  // All derived keys (from on-demand predicates or function-based queryKey) must
+  // share this prefix so that queryCache.findAll({ queryKey: baseKey }) can find them.
+  const baseKey: QueryKey =
+    typeof queryKey === `function`
+      ? (queryKey({}) as unknown as QueryKey)
+      : (queryKey as unknown as QueryKey)
+
+  /**
+   * Validates that a derived query key extends the base key prefix.
+   * TanStack Query uses prefix matching in findAll(), so all keys for this collection
+   * must start with baseKey for stale cache updates to work correctly.
+   */
+  const validateQueryKeyPrefix = (key: QueryKey): void => {
+    if (typeof queryKey !== `function`) return
+    const isValidPrefix =
+      key.length >= baseKey.length &&
+      baseKey.every((segment, i) => deepEquals(segment, key[i]))
+    if (!isValidPrefix) {
+      console.warn(
+        `[QueryCollection] queryKey function must return keys that extend the base key prefix. ` +
+          `Base: ${JSON.stringify(baseKey)}, Got: ${JSON.stringify(key)}. ` +
+          `This can cause stale cache issues.`,
+      )
+    }
+  }
+
   // Validate required parameters
 
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -680,6 +707,8 @@ export function queryCollectionOptions(
       const hashedQueryKey = hashKey(key)
       const extendedMeta = { ...meta, loadSubsetOptions: opts }
 
+      validateQueryKeyPrefix(key)
+
       if (state.observers.has(hashedQueryKey)) {
         // We already have a query for this queryKey
         // Increment reference count since another consumer is using this observer
@@ -1233,26 +1262,28 @@ export function queryCollectionOptions(
   }
 
   /**
-   * Updates the query cache with new items for ALL active query keys.
-   * This is critical for on-demand mode where multiple query keys may exist
-   * (each with different predicates).
+   * Updates the query cache with new items for ALL query keys matching this collection,
+   * including stale/inactive cache entries from destroyed observers.
+   *
+   * This prevents ghost items: when an observer is destroyed but gcTime > 0, TanStack Query
+   * keeps the cached data. If syncedData changes (via writeDelete/writeInsert/writeUpdate)
+   * after the observer is destroyed, the stale cache becomes inconsistent. When a new observer
+   * later picks up this stale cache, makeQueryResultHandler would create spurious sync
+   * operations (re-inserting deleted items, reverting updated values, etc).
+   *
+   * By updating all cache entries (active and stale), we ensure the cache always reflects
+   * the current syncedData state.
    */
   const updateCacheData = (items: Array<any>): void => {
-    // Get all active query keys from the hashToQueryKey map
-    const activeQueryKeys = Array.from(hashToQueryKey.values())
+    const allCached = queryClient.getQueryCache().findAll({ queryKey: baseKey })
 
-    if (activeQueryKeys.length > 0) {
-      // Update all active query keys in the cache
-      for (const key of activeQueryKeys) {
-        updateCacheDataForKey(key, items)
+    if (allCached.length > 0) {
+      for (const query of allCached) {
+        updateCacheDataForKey(query.queryKey, items)
       }
     } else {
-      // Fallback: no active queries yet, use the base query key
-      // This handles the case where updateCacheData is called before any queries are created
-      const baseKey =
-        typeof queryKey === `function`
-          ? queryKey({})
-          : (queryKey as unknown as QueryKey)
+      // Fallback: no queries in cache yet, seed the base query key.
+      // This handles the case where updateCacheData is called before any queries are created.
       updateCacheDataForKey(baseKey, items)
     }
   }

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

@@ -5,6 +5,7 @@ import {
   createLiveQueryCollection,
   eq,
   ilike,
+  inArray,
   or,
 } from '@tanstack/db'
 import { stripVirtualProps } from '../../db/tests/utils'
@@ -5207,4 +5208,210 @@ describe(`QueryCollection`, () => {
       customQueryClient.clear()
     })
   })
+
+  describe('Stale cache consistency', () => {
+    const sleep = (ms: number) =>
+      new Promise((resolve) => setTimeout(resolve, ms))
+
+    it('should not re-insert deleted item when a destroyed query is recreated with stale cache', async () => {
+      const customQueryClient = new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: Infinity,
+            gcTime: Infinity,
+            retry: false,
+            refetchOnWindowFocus: false,
+            refetchOnMount: false,
+            refetchOnReconnect: false,
+          },
+        },
+      })
+
+      interface Assignment {
+        id: number
+        task_id: number
+        resource_id: number
+        hours_per_day: number
+      }
+
+      const MUTATION_DELAY = 50
+
+      let serverItems: Array<Assignment> = [
+        { id: 1, task_id: 10, resource_id: 1, hours_per_day: 8 },
+        { id: 2, task_id: 10, resource_id: 2, hours_per_day: 4 },
+        { id: 3, task_id: 20, resource_id: 3, hours_per_day: 8 },
+      ]
+      let nextId = 100
+
+      const apiCreate = async (
+        item: Omit<Assignment, 'id'>,
+      ): Promise<Assignment> => {
+        await sleep(MUTATION_DELAY)
+        const created = { ...item, id: nextId++ }
+        serverItems.push(created)
+        return created
+      }
+
+      const apiDelete = async (id: number): Promise<void> => {
+        await sleep(MUTATION_DELAY)
+        serverItems = serverItems.filter((a) => a.id !== id)
+      }
+
+      const collection = createCollection(
+        queryCollectionOptions<Assignment>({
+          id: `stale-cache-${Date.now()}-${Math.random()}`,
+          queryClient: customQueryClient,
+          queryKey: ['stale-cache', String(Date.now()), String(Math.random())],
+          queryFn: async () => [...serverItems],
+          getKey: (item) => item.id,
+          syncMode: 'on-demand',
+          startSync: true,
+
+          onInsert: async ({ transaction, collection: col }) => {
+            const { id: _id, ...rest } = transaction.mutations[0].modified
+            const serverItem = await apiCreate(rest)
+            col.utils.writeInsert(serverItem)
+            return { refetch: false }
+          },
+
+          onDelete: async ({ transaction, collection: col }) => {
+            const id = transaction.mutations[0].key as number
+            await apiDelete(id)
+            col.utils.writeDelete(id)
+            return { refetch: false }
+          },
+        }),
+      )
+
+      // Always-active queries
+      const taskQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) => inArray(assignment.task_id, [10])),
+      })
+      await taskQuery.preload()
+
+      const projectQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) => eq(assignment.task_id, 10)),
+      })
+      await projectQuery.preload()
+
+      await vi.waitFor(() => {
+        expect(collection.size).toBe(3)
+      })
+
+      // Step 1: Toggle ON → add item → toggle OFF
+      let workloadQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) =>
+              inArray(assignment.resource_id, [1, 2, 3, 4]),
+            ),
+      })
+      await workloadQuery.preload()
+
+      collection.insert({
+        id: -1,
+        task_id: 10,
+        resource_id: 4,
+        hours_per_day: 8,
+      })
+
+      workloadQuery.cleanup()
+      workloadQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) =>
+              inArray(assignment.resource_id, [1, 2, 4]),
+            ),
+      })
+      await workloadQuery.preload()
+      await flushPromises()
+      await sleep(MUTATION_DELAY + 50)
+      await flushPromises()
+
+      const carolId = 100
+      expect(collection.has(carolId)).toBe(true)
+
+      // Step 2: Delete
+      collection.delete(carolId)
+
+      workloadQuery.cleanup()
+      workloadQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) => inArray(assignment.resource_id, [1, 2])),
+      })
+      await workloadQuery.preload()
+      await flushPromises()
+      await sleep(MUTATION_DELAY + 50)
+      await flushPromises()
+
+      expect(collection.has(carolId)).toBe(false)
+      expect(collection._state.syncedData.has(carolId)).toBe(false)
+
+      // Step 3: Toggle ON again (stale cache)
+      workloadQuery.cleanup()
+      workloadQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) =>
+              inArray(assignment.resource_id, [1, 2, 3, 4]),
+            ),
+      })
+      await workloadQuery.preload()
+      await flushPromises()
+
+      // Step 4: Re-add → toggle OFF
+      const t2 = collection.insert({
+        id: -2,
+        task_id: 10,
+        resource_id: 4,
+        hours_per_day: 8,
+      })
+
+      workloadQuery.cleanup()
+      workloadQuery = createLiveQueryCollection({
+        query: (q) =>
+          q
+            .from({ assignment: collection })
+            .where(({ assignment }) =>
+              inArray(assignment.resource_id, [1, 2, 4]),
+            ),
+      })
+      await workloadQuery.preload()
+      await flushPromises()
+
+      await t2.isPersisted.promise
+      await flushPromises()
+      await sleep(50)
+
+      // The deleted item (id=100) must NOT be in syncedData
+      expect(collection._state.syncedData.has(carolId)).toBe(false)
+
+      // The new item (id=101) should exist
+      expect(collection.has(101)).toBe(true)
+
+      // Only one assignment with resource_id=4
+      const allItems = Array.from(collection.values())
+      const carolAssignments = allItems.filter((a) => a.resource_id === 4)
+      expect(carolAssignments).toHaveLength(1)
+      expect(carolAssignments[0]?.id).toBe(101)
+
+      expect(collection.size).toBe(4)
+
+      workloadQuery.cleanup()
+      taskQuery.cleanup()
+      projectQuery.cleanup()
+      customQueryClient.clear()
+    })
+  })
 })