docs(query-db-collection): document query option compatibility by KyleAMathews · Pull Request #1653 · TanStack/db

KyleAMathews · 2026-07-07T19:50:38Z

Documents the current TanStack Query option compatibility surface for Query Collections. Users can now see which options are forwarded, how QueryClient.defaultOptions interact with omitted options, which fields are adapter-owned, and which common Query options are not currently exposed.

Approach

This keeps the change docs-only and focused in the existing Query Collection guide:

Adds gcTime to the documented forwarded Query options.
Clarifies that forwarded options other than adapter-extended meta are only passed when explicitly defined, so QueryClient.defaultOptions can still apply.
Separates adapter-owned fields such as queryKey, queryFn, select, queryClient, syncMode, getKey, and mutation handlers from ordinary Query option pass-through.
Lists common TanStack Query options that are not currently exposed through queryCollectionOptions.

Key invariants

This PR describes current behavior only.
It does not change runtime behavior, TypeScript types, tests, or generated reference docs.
It does not promise future support for unsupported Query options.

Non-goals

No option pass-through implementation.
No generated reference docs update.
No changes to Query Collection APIs.

Verification

pnpm prettier --write docs/collections/query-collection.md
pnpm prettier --check docs/collections/query-collection.md

Files changed

.changeset/document-query-option-compatibility.md — records the user-facing Query Collection docs update.
docs/collections/query-collection.md — documents the current Query option compatibility categories.

Summary by CodeRabbit

Documentation
- Updated “Query Options” guidance for collection-based queries to clarify that queryCollectionOptions is not a full QueryObserverOptions pass-through.
- Reworked the explanation of which options are forwarded to the query engine versus handled by the collection layer.
- Noted additional common options that are currently not exposed (including several initialization, refetch, error-handling, and structuralSharing configurations).

coderabbitai · 2026-07-07T19:52:31Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14004e90-fcab-4550-90e1-fcbf5279593d

📥 Commits

Reviewing files that changed from the base of the PR and between 88b82a6 and 4486f7d.

📒 Files selected for processing (1)

docs/collections/query-collection.md

📝 Walkthrough

Walkthrough

Documentation for queryCollectionOptions is revised to distinguish forwarded TanStack Query options, adapter-owned fields, and options not currently exposed. A changeset entry records the same compatibility surface.

Changes

Query option compatibility docs

Layer / File(s)	Summary
Documented option compatibility surface `docs/collections/query-collection.md`, `.changeset/document-query-option-compatibility.md`	Replaces the Query Options bullets with structured sections for forwarded options, adapter-owned or reinterpreted fields, and unexposed options, and adds a changeset note documenting the compatibility surface.

Estimated code review effort: 1 (Trivial) | ~5 minutes
Suggested reviewers: kevin-dp

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the docs-only query option compatibility update.
Description check	✅ Passed	The description is detailed and covers changes, approach, invariants, verification, and release impact, so it is mostly complete.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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
Commit unit tests in branch query-options-compat-docs

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

pkg-pr-new · 2026-07-07T19:55:04Z

More templates

@tanstack/angular-db

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

@tanstack/browser-db-sqlite-persistence

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

@tanstack/capacitor-db-sqlite-persistence

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

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

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/db-sqlite-persistence-core

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

@tanstack/electric-db-collection

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

@tanstack/electron-db-sqlite-persistence

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

@tanstack/expo-db-sqlite-persistence

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

@tanstack/node-db-sqlite-persistence

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

@tanstack/offline-transactions

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

@tanstack/powersync-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

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

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/tauri-db-sqlite-persistence

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 88b82a6

github-actions · 2026-07-07T19:55:42Z

Size Change: 0 B

Total Size: 125 kB

ℹ️ View Unchanged

Filename	Size
`packages/db/dist/esm/collection/change-events.js`	1.43 kB
`packages/db/dist/esm/collection/changes.js`	1.38 kB
`packages/db/dist/esm/collection/cleanup-queue.js`	810 B
`packages/db/dist/esm/collection/events.js`	434 B
`packages/db/dist/esm/collection/index.js`	3.62 kB
`packages/db/dist/esm/collection/indexes.js`	1.99 kB
`packages/db/dist/esm/collection/lifecycle.js`	1.69 kB
`packages/db/dist/esm/collection/mutations.js`	2.47 kB
`packages/db/dist/esm/collection/state.js`	5.4 kB
`packages/db/dist/esm/collection/subscription.js`	3.74 kB
`packages/db/dist/esm/collection/sync.js`	2.88 kB
`packages/db/dist/esm/collection/transaction-metadata.js`	144 B
`packages/db/dist/esm/deferred.js`	207 B
`packages/db/dist/esm/errors.js`	5.1 kB
`packages/db/dist/esm/event-emitter.js`	748 B
`packages/db/dist/esm/index.js`	3.16 kB
`packages/db/dist/esm/indexes/auto-index.js`	829 B
`packages/db/dist/esm/indexes/base-index.js`	767 B
`packages/db/dist/esm/indexes/basic-index.js`	2.06 kB
`packages/db/dist/esm/indexes/btree-index.js`	2.19 kB
`packages/db/dist/esm/indexes/index-registry.js`	820 B
`packages/db/dist/esm/indexes/reverse-index.js`	557 B
`packages/db/dist/esm/live-query-adapter.js`	318 B
`packages/db/dist/esm/local-only.js`	916 B
`packages/db/dist/esm/local-storage.js`	2.12 kB
`packages/db/dist/esm/optimistic-action.js`	359 B
`packages/db/dist/esm/paced-mutations.js`	496 B
`packages/db/dist/esm/proxy.js`	3.75 kB
`packages/db/dist/esm/query/builder/functions.js`	1.47 kB
`packages/db/dist/esm/query/builder/index.js`	5.84 kB
`packages/db/dist/esm/query/builder/ref-proxy.js`	1.24 kB
`packages/db/dist/esm/query/compiler/evaluators.js`	1.89 kB
`packages/db/dist/esm/query/compiler/expressions.js`	430 B
`packages/db/dist/esm/query/compiler/group-by.js`	3.56 kB
`packages/db/dist/esm/query/compiler/index.js`	6.67 kB
`packages/db/dist/esm/query/compiler/joins.js`	2.5 kB
`packages/db/dist/esm/query/compiler/lazy-targets.js`	923 B
`packages/db/dist/esm/query/compiler/order-by.js`	1.74 kB
`packages/db/dist/esm/query/compiler/select.js`	1.53 kB
`packages/db/dist/esm/query/effect.js`	4.77 kB
`packages/db/dist/esm/query/expression-helpers.js`	1.43 kB
`packages/db/dist/esm/query/ir.js`	1.25 kB
`packages/db/dist/esm/query/live-query-collection.js`	360 B
`packages/db/dist/esm/query/live/collection-config-builder.js`	9.1 kB
`packages/db/dist/esm/query/live/collection-registry.js`	264 B
`packages/db/dist/esm/query/live/collection-subscriber.js`	1.93 kB
`packages/db/dist/esm/query/live/internal.js`	145 B
`packages/db/dist/esm/query/live/utils.js`	1.81 kB
`packages/db/dist/esm/query/optimizer.js`	2.92 kB
`packages/db/dist/esm/query/predicate-utils.js`	2.97 kB
`packages/db/dist/esm/query/query-once.js`	359 B
`packages/db/dist/esm/query/subset-dedupe.js`	960 B
`packages/db/dist/esm/scheduler.js`	1.3 kB
`packages/db/dist/esm/SortedMap.js`	1.3 kB
`packages/db/dist/esm/strategies/debounceStrategy.js`	247 B
`packages/db/dist/esm/strategies/queueStrategy.js`	428 B
`packages/db/dist/esm/strategies/throttleStrategy.js`	246 B
`packages/db/dist/esm/transactions.js`	3.04 kB
`packages/db/dist/esm/utils.js`	927 B
`packages/db/dist/esm/utils/array-utils.js`	273 B
`packages/db/dist/esm/utils/browser-polyfills.js`	304 B
`packages/db/dist/esm/utils/btree.js`	5.61 kB
`packages/db/dist/esm/utils/comparison.js`	1.11 kB
`packages/db/dist/esm/utils/cursor.js`	457 B
`packages/db/dist/esm/utils/index-optimization.js`	2.39 kB
`packages/db/dist/esm/utils/type-guards.js`	157 B
`packages/db/dist/esm/utils/uuid.js`	449 B
`packages/db/dist/esm/virtual-props.js`	360 B

_{compressed-size-action::db-package-size}

github-actions · 2026-07-07T19:56:19Z

Size Change: 0 B

Total Size: 4.22 kB

ℹ️ View Unchanged

Filename	Size
`packages/react-db/dist/esm/index.js`	249 B
`packages/react-db/dist/esm/useLiveInfiniteQuery.js`	1.32 kB
`packages/react-db/dist/esm/useLiveQuery.js`	1.33 kB
`packages/react-db/dist/esm/useLiveQueryEffect.js`	355 B
`packages/react-db/dist/esm/useLiveSuspenseQuery.js`	567 B
`packages/react-db/dist/esm/usePacedMutations.js`	401 B

_{compressed-size-action::react-db-package-size}

kevin-dp

I don't think we need a changeset since this PR only touches docs.

KyleAMathews and others added 4 commits July 7, 2026 13:15

docs(query-db-collection): document query option compatibility

4f5bc7f

docs(query-db-collection): clarify option compatibility wording

379ed91

docs(query-db-collection): add changeset

67c7d45

ci: apply automated fixes

88b82a6

kevin-dp approved these changes Jul 9, 2026

View reviewed changes

Merge branch 'main' into query-options-compat-docs

4486f7d

KyleAMathews merged commit 580f9d0 into main Jul 9, 2026
8 of 9 checks passed

KyleAMathews deleted the query-options-compat-docs branch July 9, 2026 15:24

github-actions Bot mentioned this pull request Jul 9, 2026

ci: Version Packages #1661

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(query-db-collection): document query option compatibility#1653

docs(query-db-collection): document query option compatibility#1653
KyleAMathews merged 5 commits into
mainfrom
query-options-compat-docs

KyleAMathews commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

pkg-pr-new Bot commented Jul 7, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

kevin-dp left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

KyleAMathews commented Jul 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approach

Key invariants

Non-goals

Verification

Files changed

Related

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

pkg-pr-new Bot commented Jul 7, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kevin-dp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

KyleAMathews commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading