fix(query-db-collection): cancel idle on-demand queries #1573
main fromrefs/pull/1573/head·opened Fixes #350
Summary#
- cancel tracked TanStack Query requests when idle on-demand query collection cleanup drops the last reference
- preserve the explicit collection cleanup path that already awaits cancel/remove for all tracked query keys
- add regression coverage proving
QueryFunctionContext.signalaborts when the last on-demand live query subscriber cleans up - document passing
ctx.signalto abortable request clients
Test plan#
corepack pnpm --filter @tanstack/electric-db-collection... buildcorepack pnpm --filter @tanstack/query-db-collection buildcorepack pnpm --filter @tanstack/query-db-collection test -- tests/query.test.tscorepack pnpm test:sherifcorepack pnpm exec prettier --check packages/query-db-collection/src/query.ts packages/query-db-collection/tests/query.test.ts docs/collections/query-collection.md .changeset/query-collection-cancel-idle.md && git diff --checkcorepack pnpm exec eslint packages/query-db-collection/src/query.ts packages/query-db-collection/tests/query.test.ts(no errors; existing warnings only)
Known existing failure:
corepack pnpm test:docsfails becausedocs/reference/index.mdlinks to missingdocs/reference/functions/caseWhen.md, unrelated to this change.
Summary by CodeRabbit#
Documentation
- Added Query Function Context documentation showing how
queryFnreceives TanStack Query's signal for proper cleanup in on-demand collections.
- Added Query Function Context documentation showing how
Improvements
- On-demand query collection requests are now automatically canceled when no longer referenced, reducing unnecessary resource usage.
- 1
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/query-db-collection/src/query.ts (1)
1581-1590: ⚠️ Potential issue | 🟠 MajorFix observer reuse after cancellation to avoid immediate AbortError rejection
cleanupQueryIfIdle()’sif (hasListeners)branch cancels viacancelQueryByHash()and returns without removingstate.observersfor that query key. On a fast remount,createQueryFromOpts()will reuse the existing observer and immediately reject whenobserver.getCurrentResult().isErroris set—so a canceled preload can surface as an immediate error instead of starting a fresh request.Suggested fix
const cancelQueryByHash = (hashedQueryKey: string) => { const key = hashToQueryKey.get(hashedQueryKey) if (!key) { return } - void queryClient.cancelQueries({ queryKey: key, exact: true }) + void queryClient.cancelQueries({ queryKey: key, exact: true, silent: true }) }Add regression:
preload()→cleanup()while in flight →preload()again on the same key beforegcTimeexpires should start a new request and not reject immediately withAbortError.🤖 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/query-db-collection/src/query.ts` around lines 1581 - 1590, cleanupQueryIfIdle() cancels the in-flight query via cancelQueryByHash(hashedQueryKey) but leaves the stale observer in state.observers causing createQueryFromOpts() to reuse an observer whose observer.getCurrentResult().isError immediately rejects; after cancelQueryByHash(hashedQueryKey) remove the corresponding observer entry from state.observers for hashedQueryKey (while still setting queryRefCounts.set(hashedQueryKey, 0) so invalidate/resubscribe paths still work) so a subsequent preload() will create a fresh observer instead of reusing the aborted one.🤖 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/query-db-collection/tests/query.test.ts`: - Around line 5328-5371: The test creates a dedicated QueryClient instance (customQueryClient) with a long gcTime but never clears it; wrap the test logic that uses customQueryClient (the block that builds config, options, collection, query, preloadPromise and awaits cleanup) in a try/finally and call customQueryClient.clear() in the finally so the client's GC timers are cancelled; reference the QueryClient constructor usage (customQueryClient), the QueryCollectionConfig config, and the created collection/query so you clear the exact client after the test finishes. --- Outside diff comments: In `@packages/query-db-collection/src/query.ts`: - Around line 1581-1590: cleanupQueryIfIdle() cancels the in-flight query via cancelQueryByHash(hashedQueryKey) but leaves the stale observer in state.observers causing createQueryFromOpts() to reuse an observer whose observer.getCurrentResult().isError immediately rejects; after cancelQueryByHash(hashedQueryKey) remove the corresponding observer entry from state.observers for hashedQueryKey (while still setting queryRefCounts.set(hashedQueryKey, 0) so invalidate/resubscribe paths still work) so a subsequent preload() will create a fresh observer instead of reusing the aborted one.🪄 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:
07c20a16-3142-463a-9a57-1d136f4a9abe📥 Commits
Reviewing files that changed from the base of the PR and between 66210a5ba2760a3e5cee19819aa81a055e19d1e1 and caaf58064a3a6e89ecdef657a03f3ffb4875f9a0.
📒 Files selected for processing (4)
.changeset/query-collection-cancel-idle.mddocs/collections/query-collection.mdpackages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts
packages/query-db-collection/tests/query.test.ts lines 5328 to 5371@@ -5310,0 +5351,21 @@5351+ query: (q) => q.from({ item: collection }).select(({ item }) => item),5352+ })5353+5354+ const preloadPromise = query.preload().catch((error) => error)5355+5356+ await vi.waitFor(() => {5357+ expect(queryFn).toHaveBeenCalledTimes(1)5358+ expect(capturedSignal).toBeDefined()5359+ })5360+5361+ expect(capturedSignal!.aborted).toBe(false)5362+5363+ await query.cleanup()5364+5365+ await vi.waitFor(() => {5366+ expect(capturedSignal!.aborted).toBe(true)5367+ })5368+5369+ await preloadPromise5370+ expect(collection.size).toBe(0)5371+ })⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
Clear the dedicated
QueryClientin afinallyblock.This test creates a separate client with a 5-minute
gcTime, but it never clears it. That leaves cache GC timers alive outside the sharedafterEach()cleanup and can make this spec leak into later tests.Suggested fix
- const customQueryClient = new QueryClient({ + const customQueryClient = new QueryClient({ defaultOptions: { queries: { gcTime: 5 * 60 * 1000, retry: false, }, }, }) - - const config: QueryCollectionConfig<TestItem> = { - id: `in-flight-abort-test`, - queryClient: customQueryClient, - queryKey: baseQueryKey, - queryFn, - getKey, - startSync: true, - syncMode: `on-demand`, - } - - const options = queryCollectionOptions(config) - const collection = createCollection(options) - - const query = createLiveQueryCollection({ - query: (q) => q.from({ item: collection }).select(({ item }) => item), - }) - - const preloadPromise = query.preload().catch((error) => error) - - await vi.waitFor(() => { - expect(queryFn).toHaveBeenCalledTimes(1) - expect(capturedSignal).toBeDefined() - }) - - expect(capturedSignal!.aborted).toBe(false) - - await query.cleanup() - - await vi.waitFor(() => { - expect(capturedSignal!.aborted).toBe(true) - }) - - await preloadPromise - expect(collection.size).toBe(0) + try { + const config: QueryCollectionConfig<TestItem> = { + id: `in-flight-abort-test`, + queryClient: customQueryClient, + queryKey: baseQueryKey, + queryFn, + getKey, + startSync: true, + syncMode: `on-demand`, + } + + const options = queryCollectionOptions(config) + const collection = createCollection(options) + + const query = createLiveQueryCollection({ + query: (q) => q.from({ item: collection }).select(({ item }) => item), + }) + + const preloadPromise = query.preload().catch((error) => error) + + await vi.waitFor(() => { + expect(queryFn).toHaveBeenCalledTimes(1) + expect(capturedSignal).toBeDefined() + }) + + expect(capturedSignal!.aborted).toBe(false) + + await query.cleanup() + + await vi.waitFor(() => { + expect(capturedSignal!.aborted).toBe(true) + }) + + await preloadPromise + expect(collection.size).toBe(0) + } finally { + customQueryClient.clear() + }📝 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.
const customQueryClient = new QueryClient({ defaultOptions: { queries: { gcTime: 5 * 60 * 1000, retry: false, }, }, }) try { const config: QueryCollectionConfig<TestItem> = { id: `in-flight-abort-test`, queryClient: customQueryClient, queryKey: baseQueryKey, queryFn, getKey, startSync: true, syncMode: `on-demand`, } const options = queryCollectionOptions(config) const collection = createCollection(options) const query = createLiveQueryCollection({ query: (q) => q.from({ item: collection }).select(({ item }) => item), }) const preloadPromise = query.preload().catch((error) => error) await vi.waitFor(() => { expect(queryFn).toHaveBeenCalledTimes(1) expect(capturedSignal).toBeDefined() }) expect(capturedSignal!.aborted).toBe(false) await query.cleanup() await vi.waitFor(() => { expect(capturedSignal!.aborted).toBe(true) }) await preloadPromise expect(collection.size).toBe(0) } finally { customQueryClient.clear() }🤖 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/query-db-collection/tests/query.test.ts` around lines 5328 - 5371, The test creates a dedicated QueryClient instance (customQueryClient) with a long gcTime but never clears it; wrap the test logic that uses customQueryClient (the block that builds config, options, collection, query, preloadPromise and awaits cleanup) in a try/finally and call customQueryClient.clear() in the finally so the client's GC timers are cancelled; reference the QueryClient constructor usage (customQueryClient), the QueryCollectionConfig config, and the created collection/query so you clear the exact client after the test finishes.Closing as superseded by current main. The retained query-db lifecycle regressions now prove final-owner cleanup aborts the in-flight request and an immediate remount starts a fresh request without reusing the canceled observer. The broader lease policy remains tracked in #1657.
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
📝 Walkthrough
Walkthrough#
The PR implements active request cancellation in query collections: when tracked queries become unused, the library now cancels in-flight TanStack Query requests via their
AbortSignal. A newcancelQueryByHash()helper and optional cancellation parameter drive the feature across cleanup paths, with test validation and updated documentation showing signal usage.Changes#
Query Collection Request Cancellation
packages/query-db-collection/src/query.tscancelQueryByHash()to abort in-flight requests and extendscleanupQueryInternal()with an optional{ cancel?: boolean }parameter (default true) for fine-grained cancellation control.packages/query-db-collection/src/query.tsforceCleanupQuery()which explicitly disables cancellation (cancel: false).packages/query-db-collection/tests/query.test.tsqueryFnAbortSignal, callscleanup()to trigger cancellation, asserts the signal is aborted, and confirms the collection is empty after the aborted preload completes.packages/query-db-collection/src/query.ts,docs/collections/query-collection.mdqueryFn: async (ctx) => fetch(..., { signal: ctx.signal })for proper signal handling..changeset/query-collection-cancel-idle.md@tanstack/query-db-collectiondocumenting the request cancellation behavior.Estimated code review effort#
🎯 3 (Moderate) | ⏱️ ~20 minutes
Suggested reviewers#
Poem#
🚥 Pre-merge checks | ✅ 3 | ❌ 2
❌ Failed checks (1 warning, 1 inconclusive)#
#350: cancels in-flight requests on cleanup via queryClient.cancelQueries(), documents signal usage in queryFn with examples, and adds test coverage proving signal.abort() is triggered on cleanup. Meta support implementation is not addressed in this PR.#350requirements) is intentionally deferred to a separate PR or should be included in this changeset for completeness.✅ Passed checks (3 passed)
#350objectives: code changes implement automatic cancellation on cleanup, documentation explains signal usage, test validates abort behavior, and changelog entry records the feature. No unrelated modifications detected.✨ Finishing Touches
🧪 Generate unit tests (beta)
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