QueryCollectionUtils.fetchStatus returns an array but is typed as a scalar

[cucumber-sp]

Version

@tanstack/query-db-collection@1.2.15 with @tanstack/db@0.9.2 and @tanstack/query-core@5.102.8.

Reproduction

import { createCollection } from '@tanstack/db'
import { QueryClient } from '@tanstack/query-core'
import { queryCollectionOptions } from '@tanstack/query-db-collection'

const collection = createCollection(queryCollectionOptions({
  queryKey: ['fetch-status-repro'],
  queryClient: new QueryClient(),
  queryFn: async () => [{ id: '1' }],
  getKey: (row: { id: string }) => row.id,
}))
await collection.preload()
console.log(collection.utils.fetchStatus, Array.isArray(collection.utils.fetchStatus))
// ['idle'] true
await collection.cleanup()

The published declaration dist/esm/query.d.ts says:

fetchStatus: 'fetching' | 'paused' | 'idle'

The implementation's getter maps over all active observers and returns an array of statuses, even with one observer. This makes code such as utils.fetchStatus === 'paused' compile but always return false. An offline/paused collection can therefore be misclassified as authoritative by callers that trust the public type.

Expected: Runtime value and declaration agree. If per-observer statuses are intended, type this as an array and document how consumers should aggregate it. If a scalar is intended, define and implement the aggregation policy for multiple observers.

We reproduced ['idle'] on the version set above and use a runtime guard for both shapes until the public contract is corrected. This is separate from #1828, which concerns the result-application barrier after fetch settlement.

[dasjideepak]

Hi @cucumber-sp, I'd like to work on this one.

Looking at the code, all the other getters in QueryCollectionUtils (isFetching, isLoading, dataUpdatedAt) combine the observers into one value, and fetchStatus is the only one returning an array.

So my plan is to keep the scalar type and aggregate it the same way: 'fetching' if any observer is fetching, else 'paused' if any is paused, else 'idle'. Plus a test for multiple observers.

Does that sound right, or would you prefer typing it as an array instead?