Skip to content
Source
Sign inSign up
TanStack/db

fix(db): live query stuck loading when subquery-in-select inner is cold on-demand #1510

Closedmarbemac(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/1510/headopened

🎯 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.

Review Change Stack

    1. More templates

      @tanstack/angular-db

      npm i https://pkg.pr.new/@tanstack/angular-db@1510

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1510

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1510

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1510

      @tanstack/db

      npm i https://pkg.pr.new/@tanstack/db@1510

      @tanstack/db-ivm

      npm i https://pkg.pr.new/@tanstack/db-ivm@1510

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1510

      @tanstack/electric-db-collection

      npm i https://pkg.pr.new/@tanstack/electric-db-collection@1510

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1510

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1510

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1510

      @tanstack/offline-transactions

      npm i https://pkg.pr.new/@tanstack/offline-transactions@1510

      @tanstack/powersync-db-collection

      npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1510

      @tanstack/query-db-collection

      npm i https://pkg.pr.new/@tanstack/query-db-collection@1510

      @tanstack/react-db

      npm i https://pkg.pr.new/@tanstack/react-db@1510

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1510

      @tanstack/rxdb-db-collection

      npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1510

      @tanstack/solid-db

      npm i https://pkg.pr.new/@tanstack/solid-db@1510

      @tanstack/svelte-db

      npm i https://pkg.pr.new/@tanstack/svelte-db@1510

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1510

      @tanstack/trailbase-db-collection

      npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1510

      @tanstack/vue-db

      npm i https://pkg.pr.new/@tanstack/vue-db@1510

      commit: dff40be

    2. 📝 Walkthrough

      Walkthrough

      This PR fixes live queries hanging forever when a subquery-in-select source is an on-demand collection (cannot become ready until loadSubset runs) 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.md
      allCollectionsReady() now iterates over compiled alias→collection mappings and explicitly skips lazy aliases (marked in this.lazySources), returning false if 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.ts
      Adds collection factories where readiness is gated on loadSubset, plus a withTimeout helper 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 drive loadSubset with correlation in filters 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 nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring 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.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe 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✅ PassedThe 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✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      ✏️ Tip: You can configure your own custom pre-merge checks in the settings.
      ✨ 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.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    3. Actionable comments posted: 1

      🧹 Nitpick comments (1)
      packages/db/tests/query/includes-lazy-loading.test.ts (1)

      861-864: ⚡ Quick win

      Replace as any with a concrete result type for these assertions.

      Using any drops type safety in a key assertion path; a narrow local type keeps tests explicit and safer.

      💡 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
      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.
      🤖 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.md
      • packages/db/src/query/live/collection-config-builder.ts
      • packages/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 out
      776+ // 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.race here leaves the timeout running even when p resolves 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.
    4. Closing, since this has been fixed on main by allRequiredSourcesReady() skipping lazy on-demand sources. I re-ran this PR's tests unchanged against current main and all 12 pass. Thanks!

Sign in to join this conversation.