fix(react-query): resolve hydration mismatch in SSR with prefetched queries

packages/query-core/src/__tests__/queriesObserver.test.tsx

@@ -347,4 +347,303 @@ describe('queriesObserver', () => {
     expect(queryFn1).toHaveBeenCalledTimes(1)
     expect(queryFn2).toHaveBeenCalledTimes(1)
   })
+
+  describe('SSR Hydration', () => {
+    describe('Hydration Mismatch Problem', () => {
+      test('should demonstrate state divergence between server snapshot and client result for hydrated queries', () => {
+        const key1 = queryKey()
+        const key2 = queryKey()
+
+        queryClient.setQueryData(key1, { amount: 10 })
+        queryClient.setQueryData(key2, { amount: 20 })
+
+        const query1 = queryClient.getQueryCache().find({ queryKey: key1 })
+        const query2 = queryClient.getQueryCache().find({ queryKey: key2 })
+
+        if (query1) {
+          query1.state.dataUpdatedAt = 0
+          query1.state.fetchStatus = 'idle'
+        }
+        if (query2) {
+          query2.state.dataUpdatedAt = 0
+          query2.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueriesObserver(queryClient, [
+          { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+          { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+        ])
+
+        const clientResults = observer.getCurrentResult()
+        const serverResults = observer.getServerResult()
+
+        // 서버와 클라이언트의 차이를 명확히 보여줌
+        expect(serverResults[0]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+        })
+        expect(serverResults[1]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+        })
+
+        expect(clientResults[0]).toMatchObject({
+          status: 'success',
+          data: { amount: 10 },
+          isLoading: false,
+          isPending: false,
+        })
+        expect(clientResults[1]).toMatchObject({
+          status: 'success',
+          data: { amount: 20 },
+          isLoading: false,
+          isPending: false,
+        })
+      })
+    })
+
+    describe('Solution with getServerResult', () => {
+      test('getServerResult should return pending state for hydrated queries', () => {
+        const key1 = queryKey()
+        const key2 = queryKey()
+
+        queryClient.setQueryData(key1, { amount: 10 })
+        queryClient.setQueryData(key2, { amount: 20 })
+
+        const query1 = queryClient.getQueryCache().find({ queryKey: key1 })
+        const query2 = queryClient.getQueryCache().find({ queryKey: key2 })
+
+        if (query1) {
+          query1.state.dataUpdatedAt = 0
+          query1.state.fetchStatus = 'idle'
+        }
+        if (query2) {
+          query2.state.dataUpdatedAt = 0
+          query2.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueriesObserver(queryClient, [
+          { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+          { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+        ])
+
+        const clientResults = observer.getCurrentResult()
+        const serverResults = observer.getServerResult()
+
+        expect(clientResults[0]).toMatchObject({
+          status: 'success',
+          data: { amount: 10 },
+          isLoading: false,
+        })
+        expect(serverResults[0]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+          isLoading: false,
+          isPending: true,
+          isSuccess: false,
+        })
+
+        expect(clientResults[1]).toMatchObject({
+          status: 'success',
+          data: { amount: 20 },
+          isLoading: false,
+        })
+        expect(serverResults[1]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+          isLoading: false,
+          isPending: true,
+          isSuccess: false,
+        })
+      })
+
+      test('should handle mixed hydrated and non-hydrated queries', () => {
+        const key1 = queryKey()
+        const key2 = queryKey()
+
+        queryClient.setQueryData(key1, { amount: 10 })
+        queryClient.setQueryData(key2, { amount: 20 })
+
+        const query1 = queryClient.getQueryCache().find({ queryKey: key1 })
+        const query2 = queryClient.getQueryCache().find({ queryKey: key2 })
+
+        if (query1) {
+          query1.state.dataUpdatedAt = 0
+          query1.state.fetchStatus = 'idle'
+        }
+        if (query2) {
+          // Use a non-zero sentinel to indicate "non-hydrated"
+          query2.state.dataUpdatedAt = 1
+          query2.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueriesObserver(queryClient, [
+          { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+          { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+        ])
+
+        const serverResults = observer.getServerResult()
+
+        expect(serverResults[0]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+          isPending: true,
+        })
+
+        expect(serverResults[1]).toMatchObject({
+          status: 'success',
+          data: { amount: 20 },
+          isPending: false,
+        })
+      })
+
+      test('should handle fetching state during hydration for multiple queries', () => {
+        const key1 = queryKey()
+        const key2 = queryKey()
+
+        queryClient.setQueryData(key1, { amount: 10 })
+        queryClient.setQueryData(key2, { amount: 20 })
+
+        const query1 = queryClient.getQueryCache().find({ queryKey: key1 })
+        const query2 = queryClient.getQueryCache().find({ queryKey: key2 })
+
+        if (query1) {
+          query1.state.dataUpdatedAt = 0
+          query1.state.fetchStatus = 'fetching'
+        }
+        if (query2) {
+          query2.state.dataUpdatedAt = 0
+          query2.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueriesObserver(queryClient, [
+          { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+          { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+        ])
+
+        const serverResults = observer.getServerResult()
+
+        expect(serverResults[0]).toMatchObject({
+          status: 'pending',
+          fetchStatus: 'fetching',
+          isLoading: true,
+          isFetching: true,
+          isPending: true,
+        })
+
+        expect(serverResults[1]).toMatchObject({
+          status: 'pending',
+          fetchStatus: 'idle',
+          isLoading: false,
+          isPending: true,
+        })
+      })
+
+      test('should handle combine function with server snapshots', () => {
+        const key1 = queryKey()
+        const key2 = queryKey()
+
+        queryClient.setQueryData(key1, { amount: 10 })
+        queryClient.setQueryData(key2, { amount: 20 })
+
+        const query1 = queryClient.getQueryCache().find({ queryKey: key1 })
+        const query2 = queryClient.getQueryCache().find({ queryKey: key2 })
+
+        if (query1) {
+          query1.state.dataUpdatedAt = 0
+          query1.state.fetchStatus = 'idle'
+        }
+        if (query2) {
+          query2.state.dataUpdatedAt = 0
+          query2.state.fetchStatus = 'idle'
+        }
+
+        const combineResults = vi.fn((results: Array<QueryObserverResult>) => ({
+          totalAmount: results.reduce(
+            (sum, r) => sum + ((r.data as any)?.amount ?? 0),
+            0,
+          ),
+          allSuccess: results.every((r) => r.status === 'success'),
+          allPending: results.every((r) => r.status === 'pending'),
+        }))
+
+        const observer = new QueriesObserver(
+          queryClient,
+          [
+            { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+            { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+          ],
+          { combine: combineResults },
+        )
+
+        const clientResults = observer.getCurrentResult()
+        expect(clientResults).toHaveLength(2)
+        expect(clientResults[0]).toMatchObject({
+          status: 'success',
+          data: { amount: 10 },
+        })
+        expect(clientResults[1]).toMatchObject({
+          status: 'success',
+          data: { amount: 20 },
+        })
+
+        const serverResults = observer.getServerResult()
+        expect(serverResults).toHaveLength(2)
+        expect(serverResults[0]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+        })
+        expect(serverResults[1]).toMatchObject({
+          status: 'pending',
+          data: undefined,
+        })
+
+        const [_, getCombined] = observer.getOptimisticResult(
+          [
+            { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+            { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+          ],
+          combineResults,
+        )
+
+        const combined = getCombined(serverResults)
+        expect(combined).toEqual({
+          totalAmount: 0,
+          allSuccess: false,
+          allPending: true,
+        })
+      })
+
+      test('should handle combine with mixed hydrated and non-hydrated queries', () => {
+        const key1 = queryKey()
+        const key2 = queryKey()
+
+        queryClient.setQueryData(key1, { amount: 10 })
+        const query1 = queryClient.getQueryCache().find({ queryKey: key1 })
+        if (query1) {
+          query1.state.dataUpdatedAt = 0
+          query1.state.fetchStatus = 'idle'
+        }
+
+        const observer = new QueriesObserver(
+          queryClient,
+          [
+            { queryKey: key1, queryFn: () => ({ amount: 10 }) },
+            { queryKey: key2, queryFn: () => ({ amount: 20 }) },
+          ],
+          {
+            combine: (results) => ({
+              hasAllData: results.every((r) => r.data !== undefined),
+              loadedCount: results.filter((r) => r.isSuccess).length,
+            }),
+          },
+        )
+
+        const serverResults = observer.getServerResult()
+
+        expect(serverResults[0]).toMatchObject({ status: 'pending' })
+        expect(serverResults[1]).toMatchObject({ status: 'pending' })
+      })
+    })
+  })
 })