Add QueryObserver state utility methods to QueryCollectionUtils

.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`)
+}
+```

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

docs/reference/interfaces/LocalOnlyCollectionUtils.md

@@ -16,7 +16,7 @@ Local-only collection utilities type
 ## Indexable
 
 ```ts
-[key: string]: Fn
+[key: string]: any
 ```
 
 ## Properties

docs/reference/interfaces/LocalStorageCollectionUtils.md

@@ -16,7 +16,7 @@ LocalStorage collection utilities type
 ## Indexable
 
 ```ts
-[key: string]: Fn
+[key: string]: any
 ```
 
 ## Properties

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
 

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
 
 ***
 

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

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 = {}
   }

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>
 
 /**
  *