Add QueryObserver state utility methods to QueryCollectionUtils (#742)

KyleAMathews · claude · web-flow · commit 1367756d0a68 · 2025-11-05T10:27:07.000-07:00
* feat: Add QueryObserver state utilities and convert error utils to getters Adds new utilities to expose TanStack Query's QueryObserver state: - isFetching: Check if query is currently fetching - isRefetching: Check if query is refetching in background - isLoading: Check if query is loading for first time - dataUpdatedAt: Timestamp of last successful data update - fetchStatus: Current fetch status ('fetching' | 'paused' | 'idle') BREAKING CHANGE: Error state utilities are now getters instead of methods: - collection.utils.lastError() → collection.utils.lastError - collection.utils.isError() → collection.utils.isError - collection.utils.errorCount() → collection.utils.errorCount * refactor: Extract QueryCollectionUtilsImpl class from closure Addresses PR feedback from samwillis: refactor QueryCollectionUtilsImpl class to be extracted outside the function scope with required state passed through the constructor instead of relying on closure patterns. This improves code architecture by making dependencies explicit and avoiding nested class definitions within functions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: Update generated docs Re-generate documentation after QueryCollectionUtilsImpl refactoring. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: Re-generate documentation after build Regenerated all documentation files after running full build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: Fix outdated comment about closure usage Update QueryCollectionUtilsImpl class comment to accurately reflect that it now uses explicit dependency injection instead of closure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.changeset/query-observer-state-utils.md b/.changeset/query-observer-state-utils.md
@@ -0,0 +1,55 @@
+---
+"@tanstack/query-db-collection": minor
+"@tanstack/db": patch
+---
+
+Add QueryObserver state utilities and convert error utils to getters
+
+Exposes TanStack Query's QueryObserver state through QueryCollectionUtils, providing visibility into sync status beyond just error states. Also converts existing error state utilities from methods to getters for consistency with TanStack DB/Query patterns.
+
+**Breaking Changes:**
+
+- `lastError()`, `isError()`, and `errorCount()` are now getters instead of methods
+  - Before: `collection.utils.lastError()`
+  - After: `collection.utils.lastError`
+
+**New Utilities:**
+
+- `isFetching` - Check if query is currently fetching (initial or background)
+- `isRefetching` - Check if query is refetching in background
+- `isLoading` - Check if query is loading for first time
+- `dataUpdatedAt` - Get timestamp of last successful data update
+- `fetchStatus` - Get current fetch status ('fetching' | 'paused' | 'idle')
+
+**Use Cases:**
+
+- Show loading indicators during background refetches
+- Implement "Last updated X minutes ago" UI patterns
+- Better understanding of query sync behavior
+
+**Example Usage:**
+
+```ts
+const collection = queryCollectionOptions({
+  // ... config
+})
+
+// Check sync status
+if (collection.utils.isFetching) {
+  console.log("Syncing with server...")
+}
+
+if (collection.utils.isRefetching) {
+  console.log("Background refresh in progress")
+}
+
+// Show last update time
+const lastUpdate = new Date(collection.utils.dataUpdatedAt)
+console.log(`Last synced: ${lastUpdate.toLocaleTimeString()}`)
+
+// Check error state (now using getters)
+if (collection.utils.isError) {
+  console.error("Sync failed:", collection.utils.lastError)
+  console.log(`Failed ${collection.utils.errorCount} times`)
+}
+```
diff --git a/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md b/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md
@@ -22,7 +22,7 @@ Electric collection utilities type
 ## Indexable
 
 ```ts
-[key: string]: Fn
+[key: string]: any
 ```
 
 ## Properties
diff --git a/docs/reference/interfaces/LocalOnlyCollectionUtils.md b/docs/reference/interfaces/LocalOnlyCollectionUtils.md
@@ -16,7 +16,7 @@ Local-only collection utilities type
 ## Indexable
 
 ```ts
-[key: string]: Fn
+[key: string]: any
 ```
 
 ## Properties
diff --git a/docs/reference/interfaces/LocalStorageCollectionUtils.md b/docs/reference/interfaces/LocalStorageCollectionUtils.md
@@ -16,7 +16,7 @@ LocalStorage collection utilities type
 ## Indexable
 
 ```ts
-[key: string]: Fn
+[key: string]: any
 ```
 
 ## Properties
diff --git a/docs/reference/query-db-collection/functions/queryCollectionOptions.md b/docs/reference/query-db-collection/functions/queryCollectionOptions.md
@@ -8,10 +8,10 @@ title: queryCollectionOptions
 ## Call Signature
 
 ```ts
-function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, UtilsRecord> & object;
+function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:270](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L270)
+Defined in: [packages/query-db-collection/src/query.ts:370](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L370)
 
 Creates query collection options for use with a standard Collection.
 This integrates TanStack Query with TanStack DB for automatic synchronization.
@@ -64,7 +64,7 @@ Configuration options for the Query collection
 
 ### Returns
 
-`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, `UtilsRecord`\> & `object`
+`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, [`QueryCollectionUtils`](../../interfaces/QueryCollectionUtils.md)\<`InferSchemaOutput`\<`T`\>, `TKey`, `InferSchemaInput`\<`T`\>, `TError`\>\> & `object`
 
 Collection options with utilities for direct writes and manual operations
 
@@ -148,10 +148,10 @@ const todosCollection = createCollection(
 ## Call Signature
 
 ```ts
-function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<T, TKey, never, UtilsRecord> & object;
+function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:300](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L300)
+Defined in: [packages/query-db-collection/src/query.ts:405](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L405)
 
 Creates query collection options for use with a standard Collection.
 This integrates TanStack Query with TanStack DB for automatic synchronization.
@@ -204,7 +204,7 @@ Configuration options for the Query collection
 
 ### Returns
 
-`CollectionConfig`\<`T`, `TKey`, `never`, `UtilsRecord`\> & `object`
+`CollectionConfig`\<`T`, `TKey`, `never`, [`QueryCollectionUtils`](../../interfaces/QueryCollectionUtils.md)\<`T`, `TKey`, `T`, `TError`\>\> & `object`
 
 Collection options with utilities for direct writes and manual operations
 
@@ -288,10 +288,10 @@ const todosCollection = createCollection(
 ## Call Signature
 
 ```ts
-function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, UtilsRecord> & object;
+function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:328](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L328)
+Defined in: [packages/query-db-collection/src/query.ts:438](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L438)
 
 Creates query collection options for use with a standard Collection.
 This integrates TanStack Query with TanStack DB for automatic synchronization.
@@ -336,7 +336,7 @@ Configuration options for the Query collection
 
 ### Returns
 
-`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, `UtilsRecord`\> & `object`
+`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, [`QueryCollectionUtils`](../../interfaces/QueryCollectionUtils.md)\<`InferSchemaOutput`\<`T`\>, `TKey`, `InferSchemaInput`\<`T`\>, `TError`\>\> & `object`
 
 Collection options with utilities for direct writes and manual operations
 
@@ -420,10 +420,10 @@ const todosCollection = createCollection(
 ## Call Signature
 
 ```ts
-function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<T, TKey, never, UtilsRecord> & object;
+function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:357](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L357)
+Defined in: [packages/query-db-collection/src/query.ts:472](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L472)
 
 Creates query collection options for use with a standard Collection.
 This integrates TanStack Query with TanStack DB for automatic synchronization.
@@ -468,7 +468,7 @@ Configuration options for the Query collection
 
 ### Returns
 
-`CollectionConfig`\<`T`, `TKey`, `never`, `UtilsRecord`\> & `object`
+`CollectionConfig`\<`T`, `TKey`, `never`, [`QueryCollectionUtils`](../../interfaces/QueryCollectionUtils.md)\<`T`, `TKey`, `T`, `TError`\>\> & `object`
 
 Collection options with utilities for direct writes and manual operations
 
diff --git a/docs/reference/query-db-collection/interfaces/QueryCollectionUtils.md b/docs/reference/query-db-collection/interfaces/QueryCollectionUtils.md
@@ -43,7 +43,7 @@ The type of errors that can occur during queries
 ## Indexable
 
 ```ts
-[key: string]: Fn
+[key: string]: any
 ```
 
 ## Properties
@@ -54,7 +54,7 @@ The type of errors that can occur during queries
 clearError: () => Promise<void>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:181](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L181)
+Defined in: [packages/query-db-collection/src/query.ts:194](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L194)
 
 Clear the error state and trigger a refetch of the query
 
@@ -70,52 +70,100 @@ Error if the refetch fails
 
 ***
 
-### errorCount()
+### dataUpdatedAt
 
 ```ts
-errorCount: () => number;
+dataUpdatedAt: number;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:175](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L175)
+Defined in: [packages/query-db-collection/src/query.ts:185](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L185)
+
+Get timestamp of last successful data update (in milliseconds)
+
+***
+
+### errorCount
+
+```ts
+errorCount: number;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:177](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L177)
 
 Get the number of consecutive sync failures.
 Incremented only when query fails completely (not per retry attempt); reset on success.
 
-#### Returns
+***
 
-`number`
+### fetchStatus
+
+```ts
+fetchStatus: "idle" | "fetching" | "paused";
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:187](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L187)
+
+Get current fetch status
 
 ***
 
-### isError()
+### isError
 
 ```ts
-isError: () => boolean;
+isError: boolean;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:170](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L170)
+Defined in: [packages/query-db-collection/src/query.ts:172](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L172)
 
 Check if the collection is in an error state
 
-#### Returns
+***
+
+### isFetching
 
-`boolean`
+```ts
+isFetching: boolean;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:179](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L179)
+
+Check if query is currently fetching (initial or background)
 
 ***
 
-### lastError()
+### isLoading
 
 ```ts
-lastError: () => TError | undefined;
+isLoading: boolean;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:168](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L168)
+Defined in: [packages/query-db-collection/src/query.ts:183](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L183)
 
-Get the last error encountered by the query (if any); reset on success
+Check if query is loading for the first time (no data yet)
 
-#### Returns
+***
+
+### isRefetching
+
+```ts
+isRefetching: boolean;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:181](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L181)
 
-`TError` \| `undefined`
+Check if query is refetching in background (not initial fetch)
+
+***
+
+### lastError
+
+```ts
+lastError: TError | undefined;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:170](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L170)
+
+Get the last error encountered by the query (if any); reset on success
 
 ***
 
diff --git a/docs/reference/type-aliases/UtilsRecord.md b/docs/reference/type-aliases/UtilsRecord.md
@@ -6,9 +6,9 @@ title: UtilsRecord
 # Type Alias: UtilsRecord
 
 ```ts
-type UtilsRecord = Record<string, Fn>;
+type UtilsRecord = Record<string, any>;
 ```
 
 Defined in: [packages/db/src/types.ts:40](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L40)
 
-A record of utility functions that can be attached to a collection
+A record of utilities (functions or getters) that can be attached to a collection
diff --git a/packages/db/src/collection/index.ts b/packages/db/src/collection/index.ts
@@ -189,9 +189,9 @@ export function createCollection(
     options
   )
 
-  // Copy utils to both top level and .utils namespace
+  // Attach utils to collection
   if (options.utils) {
-    collection.utils = { ...options.utils }
+    collection.utils = options.utils
   } else {
     collection.utils = {}
   }
diff --git a/packages/db/src/types.ts b/packages/db/src/types.ts
@@ -35,9 +35,9 @@ export type TransactionState = `pending` | `persisting` | `completed` | `failed`
 export type Fn = (...args: Array<any>) => any
 
 /**
- * A record of utility functions that can be attached to a collection
+ * A record of utilities (functions or getters) that can be attached to a collection
  */
-export type UtilsRecord = Record<string, Fn>
+export type UtilsRecord = Record<string, any>
 
 /**
  *
diff --git a/packages/query-db-collection/src/query.ts b/packages/query-db-collection/src/query.ts
diff --git a/packages/query-db-collection/tests/query.test.ts b/packages/query-db-collection/tests/query.test.ts

Original file line number	Diff line number	Diff line change
`@@ -189,9 +189,9 @@ export function createCollection(`
`189`	`189`	`options`
`190`	`190`	`)`
`191`	`191`
`192`		`- // Copy utils to both top level and .utils namespace`
	`192`	`+ // Attach utils to collection`
`193`	`193`	`if (options.utils) {`
`194`		`- collection.utils = { ...options.utils }`
	`194`	`+ collection.utils = options.utils`
`195`	`195`	`} else {`
`196`	`196`	`collection.utils = {}`
`197`	`197`	`}`