Persisted collections: the sync wrapper's loadSubset is always async, so a live query over a loaded on-demand collection is never synchronously ready

[MAST1999]

• I've validated the bug against the latest version of DB packages (@tanstack/db@0.9.2, @tanstack/react-db@0.4.1, @tanstack/db-sqlite-persistence-core@0.2.23)

Describe the bug

createWrappedSyncConfig in db-sqlite-persistence-core returns its loadSubset as an async function, so it is always a Promise — even when everything it awaits is already settled and the wrapped sync answered with a synchronous true.

That matters because LoadSubsetFn is declared as a sometimes-synchronous contract in packages/db/src/types.ts:

export type LoadSubsetFn = (options: LoadSubsetOptions) => true | Promise<void>

and CollectionSyncManager.loadSubset branches on it (packages/db/src/collection/sync.ts:853):

if (result instanceof Promise) { this.trackLoadPromise(result); ... }
return true

An async implementation can never reach the true branch. So for any persisted collection, a live query over an already-loaded subset is never synchronously ready.

Under useLiveSuspenseQuery that is fatal rather than merely slow: a component that suspends before it mounts loses its refs, so each retry constructs a fresh live query, which is loading, which throws a fresh promise, which resolves, which retries. The boundary never releases.

To Reproduce

Full runnable repro (node + real-browser): https://gist.github.com/MAST1999/62526dceb542323d009d036e3bb8ed7e

npm install
npm run node      # the cause  — no React, no browser
npm run browser   # the symptom — real Chromium via @vitest/browser

There is no SQLite in the repro. It uses an in-memory PersistenceAdapter of the same shape as this repo's own createRecordingAdapter in packages/db-sqlite-persistence-core/tests/persisted.test.ts, because the defect is in the sync wrapper that persistedCollectionOptions puts in front of any adapter. The only difference between the two cases is whether the options went through persistedCollectionOptions.

The mock sync returns a bare true from loadSubset for a subset it has already loaded, which is exactly what the declared contract is for:

loadSubset: (options) => {
  const key = JSON.stringify(options.where ?? null)
  if (loaded.has(key)) return true   // already here — nothing to await
  loaded.add(key)
  begin(); for (const row of ROWS) write({ type: `insert`, value: row }); commit()
  return true
}

node-repro.mjs:

no persistence : ready (2 rows loaded)
persisted      : loading (2 rows loaded)

suspense.test.jsx, in Chromium:

✓ an unpersisted on-demand collection settles under Suspense    54ms
× the same collection with persistence never leaves its fallback
  → the boundary never released; the component re-suspended 13778 times

Expected behavior

A persisted on-demand collection should honour the same true | Promise<void> contract as an unpersisted one: when the wrapped sync answers true and there is nothing left to await, the wrapper should return true too, and the live query should be ready at construction.

Cause

packages/db-sqlite-persistence-core/src/persisted.ts, createWrappedSyncConfig (line 2654 on main @ dffb17f):

loadSubset: async (options: LoadSubsetOptions) => {
  const acquisition = { forwarded: false }
  acquisitions.set(options, acquisition)
  await fullStartPromise
  const resolvedSourceResult = await sourceResultPromise
  ...
  return runtime.loadSubset(options, (loadOptions) => { ... })
}

Note also that runtime.loadSubset (line 1043) re-runs hydrateSubsetUnsafe against the store on every call, including a repeat call for a subset already in activeSubsets — so the redundant work is real, not just the lost true.

async syntax structurally cannot express T | Promise<T> (microsoft/TypeScript#33595), so conforming to LoadSubsetFn requires hand-writing the branch.

Prior art in this repo

@tanstack/electric-db-collection writes its raw fetcher as async too, but does not hand it back directly — it wraps it (packages/electric-db-collection/src/electric.ts:860):

return new DeduplicatedLoadSubset({ loadSubset })

and DeduplicatedLoadSubset.loadSubset returns the literal true for an already-completed demand key. grep -rn "DeduplicatedLoadSubset" packages/db-sqlite-persistence-core/src/ returns nothing — the persistence package skips that layer entirely.

Additional context

This is distinct from #1855 (orderBy + limit chaining subset requests), though the two share a symptom. This one needs no orderBy and no limit — just persistence.

Happy to open a PR.

[MAST1999]

Follow-up after filing this: the suspense hang described above is not specific to persistence.

I rebuilt the repro without persistedCollectionOptions to check what was actually load-bearing, and useLiveSuspenseQuery fails to release over any on-demand collection whose loadSubset returns a promise — no persistence, no orderBy, no limit. Filed as #1858 with its own reproduction.

So the accurate framing of this issue is narrower than what I wrote: the persistence wrapper being unconditionally async means an already-loaded subset is needlessly re-read and needlessly asynchronous, which is a real defect against the declared true | Promise<void> contract and worth fixing on its own. But it is #1858 that turns it into a hang, and fixing this one alone would leave a genuinely cold load still hanging.

I have a PR ready for this one and will link it shortly.

[MAST1999]

PR: #1859