Align useLiveQuery with useQuery, and remove dependency array

[matthewdavi]

🧩 Proposal: Deterministic Key / Dependency Handling in useLiveQuery

Summary

Currently, useLiveQuery in TanStack DB relies on a referential-equality–based dependency array similar to useEffect, which can lead to brittle re-renders and makes reusable query abstractions difficult to write. By contrast, TanStack Query uses a deterministic hash of the queryKey, resulting in predictable caching and better DX for reusable hooks.

Problem

• useLiveQuery accepts (liveQueryFn, [deps]) — similar to react query pre-v4, which makes it hard to create a single liveQueryOptions object to pass into useLiveQuery
• the dependency array differs from the queryKey in tanstack query in that it forces developers to manage referential stability manually.
• This pattern can lead to accidental re-renders or infinite loops when passing unstable objects/functions.
• The lack of deterministic hashing prevents ergonomic abstractions like useQuery({ queryKey, queryFn }).

Proposal

Align useLiveQuery more closely with useQuery by introducing:

useLiveQuery({
  queryDeps,
  queryFn,
})

and generating a deterministic hash of queryDeps, similar to TanStack Query’s key hashing.

Rationale

• Matches established mental model from useQuery.
• Simplifies creation of composable query hooks.
• Eliminates fragile referential checks while retaining cache correctness.

Possible Implementation Paths

1. Short-term:

   • Add optional queryDeps key inside the options object.
   • Use JSON-based deterministic hashing (like TanStack Query’s hashQueryKey).

2. Long-term:

   • Benchmark IR-building overhead. - I discussed on discord with @samwillis that an alternative to hashing the dependency array, would be to hash the actual query function, this way it could be deduped across multiple components subscribing to the same live query.
   • If fast enough, compute a deterministic hash of the query’s IR instead — eliminating the dependency array entirely.

Notes

• React Compiler’s memoization of function references would naturally optimize this path further.
• Even a minimal referential check before hashing could skip unnecessary IR rebuilds, and this would remove the need for any dependency array at all

[KyleAMathews]

Thanks for raising this discussion! I agree that dependency arrays aren't the best.

One thing about this proposal that might confuse people coming from Query is that queryKey there is the key for the cache where with DB it's just to invalidate the hook.

[matthewdavi]

we could name it queryDeps in that case, but ultimately I think hashing the queryFn in render to compare the IR agaisnt a registry is the best DX if it can be done quickly enough

[willhoney7]

I will add my two cents here that I've forgotten to include the dependency array for queries multiple times and it always catches me off guard.