feat: implement exact targeting for refetching queries to prevent unintended cascading effects

Author: lucasweng

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

@@ -601,6 +601,7 @@ export function queryCollectionOptions(
     return queryClient.refetchQueries(
       {
         queryKey: queryKey,
+        exact: true,
       },
       {
         throwOnError: opts?.throwOnError,

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

@@ -1958,6 +1958,81 @@ describe(`QueryCollection`, () => {
     })
   })
 
+  it(`should use exact targeting when refetching to avoid unintended cascading of related queries`, async () => {
+    // Create multiple collections with related but distinct query keys
+    const queryKey = [`todos`]
+    const queryKey1 = [`todos`, `project-1`]
+    const queryKey2 = [`todos`, `project-2`]
+
+    const mockItems = [{ id: `1`, name: `Item 1` }]
+    const queryFn = vi.fn().mockResolvedValue(mockItems)
+    const queryFn1 = vi.fn().mockResolvedValue(mockItems)
+    const queryFn2 = vi.fn().mockResolvedValue(mockItems)
+
+    const config: QueryCollectionConfig<TestItem> = {
+      id: `all-todos`,
+      queryClient,
+      queryKey: queryKey,
+      queryFn: queryFn,
+      getKey,
+      startSync: true,
+    }
+    const config1: QueryCollectionConfig<TestItem> = {
+      id: `project-1-todos`,
+      queryClient,
+      queryKey: queryKey1,
+      queryFn: queryFn1,
+      getKey,
+      startSync: true,
+    }
+    const config2: QueryCollectionConfig<TestItem> = {
+      id: `project-2-todos`,
+      queryClient,
+      queryKey: queryKey2,
+      queryFn: queryFn2,
+      getKey,
+      startSync: true,
+    }
+
+    const options = queryCollectionOptions(config)
+    const options1 = queryCollectionOptions(config1)
+    const options2 = queryCollectionOptions(config2)
+
+    const collection = createCollection(options)
+    const collection1 = createCollection(options1)
+    const collection2 = createCollection(options2)
+
+    // Wait for initial queries to complete
+    await vi.waitFor(() => {
+      expect(queryFn).toHaveBeenCalledTimes(1)
+      expect(queryFn1).toHaveBeenCalledTimes(1)
+      expect(queryFn2).toHaveBeenCalledTimes(1)
+      expect(collection.status).toBe(`ready`)
+    })
+
+    // Reset call counts to test refetch behavior
+    queryFn.mockClear()
+    queryFn1.mockClear()
+    queryFn2.mockClear()
+
+    // Refetch the target collection with key ['todos', 'project-1']
+    await collection1.utils.refetch()
+
+    // Verify that only the target query was refetched
+    await vi.waitFor(() => {
+      expect(queryFn1).toHaveBeenCalledTimes(1)
+      expect(queryFn).not.toHaveBeenCalled()
+      expect(queryFn2).not.toHaveBeenCalled()
+    })
+
+    // Cleanup
+    await Promise.all([
+      collection.cleanup(),
+      collection1.cleanup(),
+      collection2.cleanup(),
+    ])
+  })
+
   describe(`Error Handling`, () => {
     // Helper to create test collection with common configuration
     const createErrorHandlingTestCollection = (