feat(query-db-collection): add meta support to QueryCollectionConfig (#363)

Co-authored-by: Kyle Mathews <[email protected]>

Author: lucasweng

.changeset/silent-monkeys-walk.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/query-db-collection": patch
+---
+
+Add meta support to QueryCollectionConfig to allow passing additional context to queryFn.

docs/reference/query-db-collection/functions/querycollectionoptions.md

@@ -8,10 +8,10 @@ title: queryCollectionOptions
 # Function: queryCollectionOptions()
 
 ```ts
-function queryCollectionOptions<TItem, TError, TQueryKey>(config): CollectionConfig<TItem, string | number, StandardSchemaV1<unknown, unknown>, TItem> & object
+function queryCollectionOptions<TItem, TError, TQueryKey, TKey, TInsertInput>(config): CollectionConfig<TItem, string | number, StandardSchemaV1<unknown, unknown>, TItem> & object
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:235](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L235)
+Defined in: [packages/query-db-collection/src/query.ts:277](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L277)
 
 Creates query collection options for use with a standard Collection
 
@@ -23,6 +23,10 @@ Creates query collection options for use with a standard Collection
 
 • **TQueryKey** *extends* readonly `unknown`[] = readonly `unknown`[]
 
+• **TKey** *extends* `string` \| `number` = `string` \| `number`
+
+• **TInsertInput** *extends* `object` = `TItem`
+
 ## Parameters
 
 ### config

docs/reference/query-db-collection/interfaces/querycollectionconfig.md

@@ -7,7 +7,7 @@ title: QueryCollectionConfig
 
 # Interface: QueryCollectionConfig\<TItem, TError, TQueryKey\>
 
-Defined in: [packages/query-db-collection/src/query.ts:26](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L26)
+Defined in: [packages/query-db-collection/src/query.ts:32](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L32)
 
 ## Type Parameters
 
@@ -25,7 +25,7 @@ Defined in: [packages/query-db-collection/src/query.ts:26](https://github.com/Ta
 optional enabled: boolean;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:36](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L36)
+Defined in: [packages/query-db-collection/src/query.ts:42](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L42)
 
 ***
 
@@ -35,7 +35,7 @@ Defined in: [packages/query-db-collection/src/query.ts:36](https://github.com/Ta
 getKey: (item) => string | number;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:68](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L68)
+Defined in: [packages/query-db-collection/src/query.ts:74](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L74)
 
 #### Parameters
 
@@ -55,7 +55,39 @@ Defined in: [packages/query-db-collection/src/query.ts:68](https://github.com/Ta
 optional id: string;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:67](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L67)
+Defined in: [packages/query-db-collection/src/query.ts:73](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L73)
+
+***
+
+### meta?
+
+```ts
+optional meta: Record<string, unknown>;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:242](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L242)
+
+Metadata to pass to the query.
+Available in queryFn via context.meta
+
+#### Example
+
+```ts
+// Using meta for error context
+queryFn: async (context) => {
+  try {
+    return await api.getTodos(userId)
+  } catch (error) {
+    // Use meta for better error messages
+    throw new Error(
+      context.meta?.errorMessage || 'Failed to load todos'
+    )
+  }
+},
+meta: {
+  errorMessage: `Failed to load todos for user ${userId}`
+}
+```
 
 ***
 
@@ -65,7 +97,7 @@ Defined in: [packages/query-db-collection/src/query.ts:67](https://github.com/Ta
 optional onDelete: DeleteMutationFn<TItem>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:213](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L213)
+Defined in: [packages/query-db-collection/src/query.ts:219](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L219)
 
 Optional asynchronous handler function called before a delete operation
 
@@ -131,7 +163,7 @@ onDelete: async ({ transaction, collection }) => {
 optional onInsert: InsertMutationFn<TItem>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:114](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L114)
+Defined in: [packages/query-db-collection/src/query.ts:120](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L120)
 
 Optional asynchronous handler function called before an insert operation
 
@@ -193,7 +225,7 @@ onInsert: async ({ transaction }) => {
 optional onUpdate: UpdateMutationFn<TItem>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:167](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L167)
+Defined in: [packages/query-db-collection/src/query.ts:173](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L173)
 
 Optional asynchronous handler function called before an update operation
 
@@ -266,7 +298,7 @@ onUpdate: async ({ transaction, collection }) => {
 queryClient: QueryClient;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:33](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L33)
+Defined in: [packages/query-db-collection/src/query.ts:39](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L39)
 
 ***
 
@@ -276,7 +308,7 @@ Defined in: [packages/query-db-collection/src/query.ts:33](https://github.com/Ta
 queryFn: (context) => Promise<TItem[]>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:32](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L32)
+Defined in: [packages/query-db-collection/src/query.ts:38](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L38)
 
 #### Parameters
 
@@ -322,7 +354,7 @@ if you want access to the direction, you can add it to the pageParam
 queryKey: TQueryKey;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:31](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L31)
+Defined in: [packages/query-db-collection/src/query.ts:37](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L37)
 
 ***
 
@@ -332,7 +364,7 @@ Defined in: [packages/query-db-collection/src/query.ts:31](https://github.com/Ta
 optional refetchInterval: number | false | (query) => undefined | number | false;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:37](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L37)
+Defined in: [packages/query-db-collection/src/query.ts:43](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L43)
 
 ***
 
@@ -342,7 +374,7 @@ Defined in: [packages/query-db-collection/src/query.ts:37](https://github.com/Ta
 optional retry: RetryValue<TError>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:44](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L44)
+Defined in: [packages/query-db-collection/src/query.ts:50](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L50)
 
 ***
 
@@ -352,7 +384,7 @@ Defined in: [packages/query-db-collection/src/query.ts:44](https://github.com/Ta
 optional retryDelay: RetryDelayValue<TError>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:51](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L51)
+Defined in: [packages/query-db-collection/src/query.ts:57](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L57)
 
 ***
 
@@ -362,17 +394,17 @@ Defined in: [packages/query-db-collection/src/query.ts:51](https://github.com/Ta
 optional schema: StandardSchemaV1<unknown, unknown>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:69](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L69)
+Defined in: [packages/query-db-collection/src/query.ts:75](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L75)
 
 ***
 
 ### staleTime?
 
 ```ts
-optional staleTime: StaleTime<TItem[], TError, TItem[], TQueryKey>;
+optional staleTime: StaleTimeFunction<TItem[], TError, TItem[], TQueryKey>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:58](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L58)
+Defined in: [packages/query-db-collection/src/query.ts:64](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L64)
 
 ***
 
@@ -382,7 +414,7 @@ Defined in: [packages/query-db-collection/src/query.ts:58](https://github.com/Ta
 optional startSync: boolean;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:71](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L71)
+Defined in: [packages/query-db-collection/src/query.ts:77](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L77)
 
 ***
 
@@ -392,4 +424,4 @@ Defined in: [packages/query-db-collection/src/query.ts:71](https://github.com/Ta
 optional sync: SyncConfig<TItem, string | number>;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:70](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L70)
+Defined in: [packages/query-db-collection/src/query.ts:76](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L76)

docs/reference/query-db-collection/interfaces/querycollectionutils.md

@@ -5,16 +5,24 @@ title: QueryCollectionUtils
 
 <!-- DO NOT EDIT: this page is autogenerated from the type comments -->
 
-# Interface: QueryCollectionUtils
+# Interface: QueryCollectionUtils\<TItem, TKey, TInsertInput\>
 
-Defined in: [packages/query-db-collection/src/query.ts:225](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L225)
+Defined in: [packages/query-db-collection/src/query.ts:256](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L256)
 
-Query collection utilities type
+Write operation types for batch operations
 
 ## Extends
 
 - `UtilsRecord`
 
+## Type Parameters
+
+• **TItem** *extends* `object` = `Record`\<`string`, `unknown`\>
+
+• **TKey** *extends* `string` \| `number` = `string` \| `number`
+
+• **TInsertInput** *extends* `object` = `TItem`
+
 ## Indexable
 
 ```ts
@@ -29,4 +37,104 @@ Query collection utilities type
 refetch: RefetchFn;
 ```
 
-Defined in: [packages/query-db-collection/src/query.ts:226](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L226)
+Defined in: [packages/query-db-collection/src/query.ts:261](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L261)
+
+***
+
+### writeBatch()
+
+```ts
+writeBatch: (operations) => void;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:266](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L266)
+
+#### Parameters
+
+##### operations
+
+[`SyncOperation`](../../type-aliases/syncoperation.md)\<`TItem`, `TKey`, `TInsertInput`\>[]
+
+#### Returns
+
+`void`
+
+***
+
+### writeDelete()
+
+```ts
+writeDelete: (keys) => void;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:264](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L264)
+
+#### Parameters
+
+##### keys
+
+`TKey` | `TKey`[]
+
+#### Returns
+
+`void`
+
+***
+
+### writeInsert()
+
+```ts
+writeInsert: (data) => void;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:262](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L262)
+
+#### Parameters
+
+##### data
+
+`TInsertInput` | `TInsertInput`[]
+
+#### Returns
+
+`void`
+
+***
+
+### writeUpdate()
+
+```ts
+writeUpdate: (updates) => void;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:263](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L263)
+
+#### Parameters
+
+##### updates
+
+`Partial`\<`TItem`\> | `Partial`\<`TItem`\>[]
+
+#### Returns
+
+`void`
+
+***
+
+### writeUpsert()
+
+```ts
+writeUpsert: (data) => void;
+```
+
+Defined in: [packages/query-db-collection/src/query.ts:265](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L265)
+
+#### Parameters
+
+##### data
+
+`Partial`\<`TItem`\> | `Partial`\<`TItem`\>[]
+
+#### Returns
+
+`void`

packages/query-db-collection/src/query.ts

@@ -218,6 +218,28 @@ export interface QueryCollectionConfig<
    */
   onDelete?: DeleteMutationFn<TItem>
   // TODO type returning { refetch: boolean }
+
+  /**
+   * Metadata to pass to the query.
+   * Available in queryFn via context.meta
+   *
+   * @example
+   * // Using meta for error context
+   * queryFn: async (context) => {
+   *   try {
+   *     return await api.getTodos(userId)
+   *   } catch (error) {
+   *     // Use meta for better error messages
+   *     throw new Error(
+   *       context.meta?.errorMessage || 'Failed to load todos'
+   *     )
+   *   }
+   * },
+   * meta: {
+   *   errorMessage: `Failed to load todos for user ${userId}`
+   * }
+   */
+  meta?: Record<string, unknown>
 }
 
 /**
@@ -276,6 +298,7 @@ export function queryCollectionOptions<
     onInsert,
     onUpdate,
     onDelete,
+    meta,
     ...baseCollectionConfig
   } = config
 
@@ -312,6 +335,7 @@ export function queryCollectionOptions<
     > = {
       queryKey: queryKey,
       queryFn: queryFn,
+      meta: meta,
       enabled: enabled,
       refetchInterval: refetchInterval,
       retry: retry,