fix(tanstack-react-query): use skipToken instead of overriding enabled option

[msvargas]

Problem

PowerSync's useQuery and useQueries hooks override the user's enabled option by forcing enabled: streamsHaveSynced at the end of the spread. Users who need conditional query control (e.g., enabled: !!userId) lose that ability — the query always runs once streams are synced, regardless of their condition.

Additionally, two secondary issues were discovered:

1. Stale streamsHaveSynced — The usePowerSyncQueries final useMemo was missing streamsHaveSynced in its dependency array, causing the returned value to stay stale when only streamsHaveSynced changed.

2. Race condition on first table resolution — resolveTables is async. The change listener attaches watching [] (empty) tables, so any write landing before resolveTables resolves is silently dropped. The listener that later attaches with real tables was created after the write, so it never sees it.

Solution

Replace the enabled override pattern with TanStack's skipToken. When streams haven't synced, the queryFn is set to Tanstack.skipToken, preventing query execution without modifying the user's enabled option.

For useSuspenseQuery, skipToken is not passed (TanStack rejects it for suspense). Suspense queries always receive the real queryFn, which is correct — suspense queries must resolve.

Race condition fix: A tablesInitialized ref tracks each query's [] -> [tables] transition. On the first transition, an explicit queryClient.invalidateQueries() rescues any data that was written and dropped during the pending resolveTables window.

Changes

File	Change
src/hooks/useQuery.ts	Conditionally apply skipToken when streams haven't synced (and not a suspense query); remove enabled override
src/hooks/useQueries.ts	Apply skipToken per-query; remove enabled override; add streamsHaveSynced to deps
src/hooks/usePowerSyncQueries.ts	Add tablesInitialized ref with rescue invalidation; add streamsHaveSynced to return memo deps
tests/enabled.test.tsx	Verify user enabled: false is respected for useQuery, useQueries, and useSuspenseQuery
tests/usePowerSyncQueries.test.tsx	Verify streamsHaveSynced dep update + race condition rescue

Testing

All 41 tests pass (5 test files, 40 passed, 1 pre-existing skip).

[changeset-bot]

🦋 Changeset detected

Latest commit: 3864737

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@powersync/tanstack-react-query	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[msvargas]

Hi @Chriztiaan, could you please review this fix when you have a chance? Feedback is very welcome. Also, thanks for the awesome packages! 🚀

[Chriztiaan]

Hey @msvargas, I have a few changes I'd like to push to your branch. Could you give me write permissions to your fork? Alternatively, you could apply the changes yourself - commit here: barvaz-engineering@833436e

[msvargas]

Thanks for the review @Chriztiaan! I've applied all your suggested changes from commit 833436e locally — they look great. I wasn't able to give you write permissions to the fork, but please feel free to close this PR and open a new one with your changes if you'd prefer to take it from here. Many thanks for the help!

[Chriztiaan]

Thank you for the effort @msvargas, it's greatly appreciated!

Closing this in favour of #1007.