From 4f5bc7f9948089b140bef2257528b7566635b25b Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:15:42 -0600 Subject: [PATCH 1/4] docs(query-db-collection): document query option compatibility --- docs/collections/query-collection.md | 34 +++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/collections/query-collection.md b/docs/collections/query-collection.md index 73f3511edc..af52c3d6d0 100644 --- a/docs/collections/query-collection.md +++ b/docs/collections/query-collection.md @@ -56,13 +56,41 @@ The `queryCollectionOptions` function accepts the following options: ### Query Options -- `select`: Function that lets extract array items when they're wrapped with metadata +Query Collections use TanStack Query internally, but `queryCollectionOptions` is not a full `QueryObserverOptions` pass-through. It exposes the Query options that the collection adapter supports today and owns the options that affect row materialization, collection identity, and synchronization. + +The following Query options are forwarded to the underlying Query observer when they are explicitly defined: + - `enabled`: Whether the query should automatically run (default: `true`) -- `refetchInterval`: Refetch interval in milliseconds (default: 0 — set an interval to enable polling refetching) +- `refetchInterval`: Refetch interval in milliseconds - `retry`: Retry configuration for failed queries - `retryDelay`: Delay between retries - `staleTime`: How long data is considered fresh -- `meta`: Optional metadata that will be passed to the query function context +- `gcTime`: How long unused query data stays in the Query cache +- `meta`: Metadata passed to the query function context. Query Collections may add `loadSubsetOptions` for on-demand queries. + +These options are only passed to TanStack Query when you define them. If you omit them, `QueryClient.defaultOptions` can still apply. + +Some fields are owned or reinterpreted by the collection adapter rather than treated as ordinary Query option pass-through: + +- `queryKey`: Identifies the Query cache entry and, in on-demand mode, may be built from load-subset options. +- `queryFn`: Fetches the complete collection state or the requested on-demand subset. +- `select`: Extracts array rows from wrapped responses for DB materialization. This is not the same contract as TanStack Query's `select` option. +- `queryClient`: Supplies the Query client instance used by the collection. +- `syncMode`: Controls whether the collection syncs eagerly or on demand. +- `getKey`: Extracts each row's stable TanStack DB key. +- Mutation handlers such as `onInsert`, `onUpdate`, and `onDelete`. +- Direct write and persistence utilities exposed by Query Collection helpers. + +Other TanStack Query options are not currently exposed through `queryCollectionOptions`. Common examples include: + +- `initialData` +- `placeholderData` +- `refetchOnWindowFocus` +- `refetchOnReconnect` +- `refetchOnMount` +- `networkMode` +- `throwOnError` +- configurable `structuralSharing` ### Using with `queryOptions(...)` From 379ed9181084b8aeaf1a62e1242c533c5c0383b5 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:32:35 -0600 Subject: [PATCH 2/4] docs(query-db-collection): clarify option compatibility wording --- docs/collections/query-collection.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/collections/query-collection.md b/docs/collections/query-collection.md index af52c3d6d0..ae14bb9a9e 100644 --- a/docs/collections/query-collection.md +++ b/docs/collections/query-collection.md @@ -56,9 +56,9 @@ The `queryCollectionOptions` function accepts the following options: ### Query Options -Query Collections use TanStack Query internally, but `queryCollectionOptions` is not a full `QueryObserverOptions` pass-through. It exposes the Query options that the collection adapter supports today and owns the options that affect row materialization, collection identity, and synchronization. +Query Collections use TanStack Query internally, but `queryCollectionOptions` is not a full `QueryObserverOptions` pass-through. It exposes only the Query options supported by the collection adapter. Fields that affect row materialization, collection identity, and synchronization are handled by the adapter itself. -The following Query options are forwarded to the underlying Query observer when they are explicitly defined: +The following Query options are forwarded to the underlying Query observer: - `enabled`: Whether the query should automatically run (default: `true`) - `refetchInterval`: Refetch interval in milliseconds @@ -68,18 +68,17 @@ The following Query options are forwarded to the underlying Query observer when - `gcTime`: How long unused query data stays in the Query cache - `meta`: Metadata passed to the query function context. Query Collections may add `loadSubsetOptions` for on-demand queries. -These options are only passed to TanStack Query when you define them. If you omit them, `QueryClient.defaultOptions` can still apply. +Except for `meta`, these options are only passed to TanStack Query when you define them. If you omit them, `QueryClient.defaultOptions` can still apply. Some fields are owned or reinterpreted by the collection adapter rather than treated as ordinary Query option pass-through: - `queryKey`: Identifies the Query cache entry and, in on-demand mode, may be built from load-subset options. - `queryFn`: Fetches the complete collection state or the requested on-demand subset. -- `select`: Extracts array rows from wrapped responses for DB materialization. This is not the same contract as TanStack Query's `select` option. +- `select`: Extracts array rows from wrapped responses before they are stored in the collection. This is not the same contract as TanStack Query's `select` option. - `queryClient`: Supplies the Query client instance used by the collection. - `syncMode`: Controls whether the collection syncs eagerly or on demand. - `getKey`: Extracts each row's stable TanStack DB key. - Mutation handlers such as `onInsert`, `onUpdate`, and `onDelete`. -- Direct write and persistence utilities exposed by Query Collection helpers. Other TanStack Query options are not currently exposed through `queryCollectionOptions`. Common examples include: From 67c7d45c3855e1176b5bd7534e89ca07b0fdae00 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:50:05 -0600 Subject: [PATCH 3/4] docs(query-db-collection): add changeset --- .changeset/document-query-option-compatibility.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/document-query-option-compatibility.md diff --git a/.changeset/document-query-option-compatibility.md b/.changeset/document-query-option-compatibility.md new file mode 100644 index 0000000000..1a03d54668 --- /dev/null +++ b/.changeset/document-query-option-compatibility.md @@ -0,0 +1,5 @@ +--- +"@tanstack/query-db-collection": patch +--- + +Document the current TanStack Query option compatibility surface for Query Collections, including forwarded options, QueryClient defaults, adapter-owned fields, and common options that are not currently exposed. From 88b82a6a2441302c4c9adad3984b80876e0e87a0 Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 19:51:43 +0000 Subject: [PATCH 4/4] ci: apply automated fixes --- .changeset/document-query-option-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/document-query-option-compatibility.md b/.changeset/document-query-option-compatibility.md index 1a03d54668..d25ea160a1 100644 --- a/.changeset/document-query-option-compatibility.md +++ b/.changeset/document-query-option-compatibility.md @@ -1,5 +1,5 @@ --- -"@tanstack/query-db-collection": patch +'@tanstack/query-db-collection': patch --- Document the current TanStack Query option compatibility surface for Query Collections, including forwarded options, QueryClient defaults, adapter-owned fields, and common options that are not currently exposed.