fix(db): live query stuck loading when subquery-in-select inner is cold on-demand #1510
main fromrefs/pull/1510/head·opened 🎯 Changes#
A live query whose select contains a subquery against an on-demand collection hung forever when the outer returned zero rows and no other consumer had warmed the inner. The lazy mechanism only fires loadSubset per outer row via a per-row tap, so an empty outer never marked the inner ready, and allCollectionsReady stayed false.
Skip lazy aliases (subquery-in-select inner aliases and lazy-join inner aliases) in allCollectionsReady. The live query collection's isLoadingSubset gate still keeps the live query from marking ready while in-flight per-row lazy loads are pending.
✅ Checklist#
- I have tested this code locally with
pnpm test.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
Release Notes#
Bug Fixes
- Fixed live queries hanging indefinitely when performing nested subqueries within SELECT statements with on-demand data sources returning zero rows.
Tests
- Added comprehensive test coverage for lazy-loaded subquery readiness behavior with empty result sets and nested collection loading.
- 1
📝 Walkthrough
Walkthrough#
This PR fixes live queries hanging forever when a subquery-in-select source is an on-demand collection (cannot become ready until
loadSubsetruns) and the outer query returns zero rows. The fix modifies the readiness gate to skip lazy aliases, allowing the query to mark ready when zero outer rows eliminate the need for per-row subset loads. Comprehensive tests validate both the zero-row and normal-row cases.Changes#
Subquery-in-select Readiness Fix
Layer / File(s) Summary Readiness gate logic and documentation
packages/db/src/query/live/collection-config-builder.ts,.changeset/fix-subquery-in-select-empty-outer-hang.mdallCollectionsReady()now iterates over compiled alias→collection mappings and explicitly skips lazy aliases (marked inthis.lazySources), returningfalseif any non-lazy collection is not ready. Changeset documents the fix for the zero-outer-rows hang.Test suite for cold on-demand subqueries
packages/db/tests/query/includes-lazy-loading.test.tsAdds collection factories where readiness is gated on loadSubset, plus awithTimeouthelper to detect hangs. Two test cases validate: (1)liveQuery.preload()completes with ready/empty when outer returns zero rows and inner is never loaded; (2) per-row subqueries driveloadSubsetwith correlationinfilters when outer has rows.🎯 2 (Simple) | ⏱️ ~12 minutes
A rabbit reads the readiness gate,
Where lazy aliases now deflate the wait—
Cold on-demand collections, zero rows align,
No hanging query, the tests all pass fine! 🐰✨🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
Check name Status Explanation Resolution Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold. ✏️ Tip: You can configure your own custom pre-merge checks in the settings.✅ Passed checks (4 passed)
Check name Status Explanation Title check ✅ Passed The title clearly and specifically describes the main fix: preventing live queries from hanging when a subquery-in-select inner collection is on-demand and the outer query returns zero rows. Description check ✅ Passed The description addresses all required template sections: explains the problem and solution under 'Changes', confirms testing with 'pnpm test', and indicates a changeset was generated for release impact. Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request. Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request. ✨ Finishing Touches
🧪 Generate unit tests (beta)
- Create PR with unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment `@coderabbitai help` to get the list of available commands and usage tips.Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/db/tests/query/includes-lazy-loading.test.ts (1)
861-864: ⚡ Quick winReplace
as anywith a concrete result type for these assertions.Using
anydrops type safety in a key assertion path; a narrow local type keeps tests explicit and safer.As per coding guidelines, `**/*.{ts,tsx}`: Avoid using `any` types; use `unknown` instead when the type is truly unknown, and provide proper type annotations for return values.💡 Suggested fix
+type PostWithComments = { + id: number + title: string + comments: Array<{ id: number; body: string }> +} + -const post1 = stripVirtualProps(liveQuery.get(1)) as any -const post2 = stripVirtualProps(liveQuery.get(2)) as any +const post1 = stripVirtualProps(liveQuery.get(1)) as + | PostWithComments + | undefined +const post2 = stripVirtualProps(liveQuery.get(2)) as + | PostWithComments + | undefined🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-lazy-loading.test.ts` around lines 861 - 864, The test currently uses "as any" for post1/post2 which loses type safety; replace that with a concrete local type describing the expected result (e.g., declare a local PostWithComments type/interface that includes the comments array shape) and cast the result of stripVirtualProps(liveQuery.get(...)) to that type (or cast first to unknown then to the concrete type) so assertions like expect(post1.comments).toHaveLength(...) remain type-checked; update both post1 and post2 to use this concrete type instead of any and ensure the type matches the return shape from stripVirtualProps/liveQuery.get.🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/db/tests/query/includes-lazy-loading.test.ts`: - Around line 777-783: The withTimeout helper leaves the setTimeout running after the promise settles; modify withTimeout<T>(p: Promise<T>, ms: number, label: string) to store the timeout id from setTimeout, and when either the original promise p resolves/rejects or the timeout fires, clear the other side (i.e., call clearTimeout(timeoutId) when p settles and ensure the promise rejection handler clears if timeout wins) so no dangling timers remain after preload()/p settles; update the Promise.race usage accordingly around withTimeout to reference the timeout id and clear it on resolution/rejection. --- Nitpick comments: In `@packages/db/tests/query/includes-lazy-loading.test.ts`: - Around line 861-864: The test currently uses "as any" for post1/post2 which loses type safety; replace that with a concrete local type describing the expected result (e.g., declare a local PostWithComments type/interface that includes the comments array shape) and cast the result of stripVirtualProps(liveQuery.get(...)) to that type (or cast first to unknown then to the concrete type) so assertions like expect(post1.comments).toHaveLength(...) remain type-checked; update both post1 and post2 to use this concrete type instead of any and ensure the type matches the return shape from stripVirtualProps/liveQuery.get.🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
58d4bab5-5016-4dc1-b946-c51ef1b7586c📥 Commits
Reviewing files that changed from the base of the PR and between be656be5c5fa65cc1c2bf76bc0b60be3d9d2a577 and 1ac76ccba93441e2fb35f7ea06beca0c3c31f8be.
📒 Files selected for processing (3)
.changeset/fix-subquery-in-select-empty-outer-hang.mdpackages/db/src/query/live/collection-config-builder.tspackages/db/tests/query/includes-lazy-loading.test.ts
packages/db/tests/query/includes-lazy-loading.test.ts lines 777 to 783@@ -678,0 +763,21 @@763+ markReady()764+ return Promise.resolve()765+ }),766+ }767+ },768+ },769+ })770+771+ return { collection, loadSubsetCalls }772+ }773+774+ // Race a promise against a short timeout. Used to detect the hang —775+ // if preload never resolves, the test fails fast instead of timing out776+ // the whole vitest run.777+ function withTimeout<T>(p: Promise<T>, ms: number, label: string) {778+ return Promise.race([779+ p,780+ new Promise<never>((_, reject) =>781+ setTimeout(() => reject(new Error(`Timed out: ${label}`)), ms),782+ ),783+ ])⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
Clear the timeout after
preload()settles to avoid dangling timers.Promise.racehere leaves the timeout running even whenpresolves quickly, which can add avoidable delay/noise across test runs.💡 Suggested fix
-function withTimeout<T>(p: Promise<T>, ms: number, label: string) { - return Promise.race([ - p, - new Promise<never>((_, reject) => - setTimeout(() => reject(new Error(`Timed out: ${label}`)), ms), - ), - ]) -} +function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> { + return new Promise<T>((resolve, reject) => { + const timer = setTimeout(() => reject(new Error(`Timed out: ${label}`)), ms) + p.then( + (value) => { + clearTimeout(timer) + resolve(value) + }, + (error) => { + clearTimeout(timer) + reject(error) + }, + ) + }) +}📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
function withTimeout<T>(p: Promise<T>, ms: number, label: string): Promise<T> { return new Promise<T>((resolve, reject) => { const timer = setTimeout(() => reject(new Error(`Timed out: ${label}`)), ms) p.then( (value) => { clearTimeout(timer) resolve(value) }, (error) => { clearTimeout(timer) reject(error) }, ) }) }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-lazy-loading.test.ts` around lines 777 - 783, The withTimeout helper leaves the setTimeout running after the promise settles; modify withTimeout<T>(p: Promise<T>, ms: number, label: string) to store the timeout id from setTimeout, and when either the original promise p resolves/rejects or the timeout fires, clear the other side (i.e., call clearTimeout(timeoutId) when p settles and ensure the promise rejection handler clears if timeout wins) so no dangling timers remain after preload()/p settles; update the Promise.race usage accordingly around withTimeout to reference the timeout id and clear it on resolution/rejection.Closing, since this has been fixed on
mainbyallRequiredSourcesReady()skipping lazy on-demand sources. I re-ran this PR's tests unchanged against currentmainand all 12 pass. Thanks!marbemac(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit:
dff40be