feat: add warnOnce utility and improve deprecation warnings

- Add warnOnce utility to prevent console spam (logs each warning once)
- QueryCollection: warn about deprecated auto-refetch behavior
- QueryCollection: clarify { refetch: false } is correct pattern for now
- ElectricCollection: use warnOnce for { txid } return deprecation
- Update docs to accurately describe current vs v1.0 behavior
- Update changeset with clearer migration guidance

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: KyleAMathews

.changeset/deprecate-handler-return-values.md

@@ -4,47 +4,48 @@
 '@tanstack/query-db-collection': minor
 ---
 
-**BREAKING (TypeScript only)**: Deprecate returning values from mutation handlers (`onInsert`, `onUpdate`, `onDelete`).
+**Deprecation**: Mutation handler return values and QueryCollection auto-refetch behavior.
 
 **What's changed:**
 
 - Handler types now default to `Promise<void>` instead of `Promise<any>`, indicating the new expected pattern
-- Old return patterns (`return { refetch }`, `return { txid }`) still work at runtime with deprecation warnings
-- **Deprecation warnings** are now logged when handlers return values
-- Old patterns will be fully removed in v1.0
+- **Deprecation warnings** are now logged (once per session) when deprecated patterns are used
+- Warnings now use `warnOnce` to avoid console spam
 
-**New pattern (explicit sync coordination):**
+**QueryCollection changes:**
 
-- **Query Collections**: Call `await collection.utils.refetch()` to sync server state
-- **Electric Collections**: Call `await collection.utils.awaitTxId(txid)` or `await collection.utils.awaitMatch(fn)` to wait for synchronization
-- **Other Collections**: Use appropriate sync utilities for your collection type
+- Auto-refetch after handlers is **deprecated** and will be removed in v1.0
+- To skip auto-refetch now, return `{ refetch: false }` from your handler
+- In v1.0: call `await collection.utils.refetch()` explicitly when needed, or omit to skip
 
-This change makes the API more explicit and consistent across all collection types. All handlers should coordinate sync explicitly within the handler function using `await`, rather than relying on magic return values.
+**ElectricCollection changes:**
 
-Migration guide:
+- Returning `{ txid }` is deprecated - use `await collection.utils.awaitTxId(txid)` instead
+
+**Migration guide:**
 
 ```typescript
-// Before (Query Collection)
+// QueryCollection - skip refetch (current)
 onInsert: async ({ transaction }) => {
   await api.create(transaction.mutations[0].modified)
-  // Implicitly refetches
+  return { refetch: false } // Opt out of auto-refetch
 }
 
-// After (Query Collection)
+// QueryCollection - with refetch (v1.0 pattern)
 onInsert: async ({ transaction, collection }) => {
   await api.create(transaction.mutations[0].modified)
-  await collection.utils.refetch()
+  await collection.utils.refetch() // Explicit refetch
 }
 
-// Before (Electric Collection)
+// ElectricCollection - before
 onInsert: async ({ transaction }) => {
   const result = await api.create(transaction.mutations[0].modified)
-  return { txid: result.txid }
+  return { txid: result.txid } // Deprecated
 }
 
-// After (Electric Collection)
+// ElectricCollection - after
 onInsert: async ({ transaction, collection }) => {
   const result = await api.create(transaction.mutations[0].modified)
-  await collection.utils.awaitTxId(result.txid)
+  await collection.utils.awaitTxId(result.txid) // Explicit
 }
 ```

docs/collections/query-collection.md

@@ -199,7 +199,7 @@ const productsCollection = createCollection(
 
 ## Persistence Handlers
 
-You can define handlers that are called when mutations occur. These handlers persist changes to your backend and trigger refetches when needed:
+You can define handlers that are called when mutations occur. These handlers persist changes to your backend:
 
 ```typescript
 const todosCollection = createCollection(
@@ -209,62 +209,80 @@ const todosCollection = createCollection(
     queryClient,
     getKey: (item) => item.id,
 
-    onInsert: async ({ transaction, collection }) => {
+    onInsert: async ({ transaction }) => {
       const newItems = transaction.mutations.map((m) => m.modified)
       await api.createTodos(newItems)
-      // Trigger refetch to sync server state
-      await collection.utils.refetch()
+      // Auto-refetch happens after handler completes (pre-1.0 behavior)
     },
 
-    onUpdate: async ({ transaction, collection }) => {
+    onUpdate: async ({ transaction }) => {
       const updates = transaction.mutations.map((m) => ({
         id: m.key,
         changes: m.changes,
       }))
       await api.updateTodos(updates)
-      // Refetch after persisting changes
-      await collection.utils.refetch()
     },
 
-    onDelete: async ({ transaction, collection }) => {
+    onDelete: async ({ transaction }) => {
       const ids = transaction.mutations.map((m) => m.key)
       await api.deleteTodos(ids)
-      await collection.utils.refetch()
     },
   })
 )
 ```
 
+> **Note**: QueryCollection currently auto-refetches after handlers complete. See [Controlling Refetch Behavior](#controlling-refetch-behavior) for details on this transitional behavior.
+
 ### Controlling Refetch Behavior
 
-After persisting mutations to your backend, call `collection.utils.refetch()` to sync the server state back to your collection. This ensures the local state matches the server state after server-side processing.
+> **⚠️ Transitional API**: QueryCollection currently auto-refetches after handlers complete. This behavior is deprecated and will be removed in v1.0. See the migration notes below.
+
+#### Current Behavior (Pre-1.0)
+
+By default, QueryCollection automatically refetches after each handler completes. To **skip** auto-refetch, return `{ refetch: false }`:
 
 ```typescript
-onInsert: async ({ transaction, collection }) => {
+onInsert: async ({ transaction }) => {
   await api.createTodos(transaction.mutations.map((m) => m.modified))
 
-  // Trigger refetch to sync server state
-  await collection.utils.refetch()
+  // Skip auto-refetch - use this when server doesn't modify the data
+  return { refetch: false }
 }
 ```
 
-You can skip the refetch when:
+If you don't return `{ refetch: false }`, auto-refetch happens automatically.
 
-- You're confident the server state exactly matches what you sent (no server-side processing)
-- You're handling state updates through other mechanisms (like WebSockets or direct writes)
-- You want to optimize for fewer network requests
+#### v1.0 Behavior (Future)
+
+In v1.0, auto-refetch will be **removed**. Handlers will need to explicitly call `collection.utils.refetch()` when refetching is needed:
+
+```typescript
+onInsert: async ({ transaction, collection }) => {
+  await api.createTodos(transaction.mutations.map((m) => m.modified))
+
+  // Explicitly trigger refetch when you need server state
+  await collection.utils.refetch()
+}
+```
 
-**When to skip refetch:**
+To skip refetch in v1.0, simply don't call `refetch()`:
 
 ```typescript
 onInsert: async ({ transaction }) => {
   await api.createTodos(transaction.mutations.map((m) => m.modified))
 
-  // Skip refetch - only do this if server doesn't modify the data
-  // The optimistic state will remain as-is
+  // No refetch call = no refetch (v1.0 behavior)
 }
 ```
 
+#### When to Skip Refetch
+
+Skip refetching when:
+
+- You're confident the server state exactly matches what you sent (no server-side processing)
+- You're handling state updates through other mechanisms (like WebSockets or direct writes)
+- You want to optimize for fewer network requests
+
 ## Utility Methods
 
 The collection provides these utility methods via `collection.utils`:

packages/db/src/index.ts

@@ -13,7 +13,7 @@ export * from './optimistic-action'
 export * from './local-only'
 export * from './local-storage'
 export * from './errors'
-export { deepEquals } from './utils'
+export { deepEquals, warnOnce, resetWarnings } from './utils'
 export * from './paced-mutations'
 export * from './strategies/index.js'
 

packages/db/src/utils.ts

@@ -237,3 +237,40 @@ export const DEFAULT_COMPARE_OPTIONS: CompareOptions = {
   nulls: `first`,
   stringSort: `locale`,
 }
+
+/**
+ * Set of warning keys that have already been shown.
+ * Used to prevent duplicate warnings from spamming the console.
+ */
+const warnedKeys = new Set<string>()
+
+/**
+ * Log a warning message only once per unique key.
+ * Subsequent calls with the same key will be silently ignored.
+ *
+ * @param key - Unique identifier for this warning
+ * @param message - The warning message to display
+ *
+ * @example
+ * ```typescript
+ * // First call logs the warning
+ * warnOnce('deprecated-api', 'This API is deprecated')
+ *
+ * // Subsequent calls with same key are ignored
+ * warnOnce('deprecated-api', 'This API is deprecated') // silent
+ * ```
+ */
+export function warnOnce(key: string, message: string): void {
+  if (warnedKeys.has(key)) {
+    return
+  }
+  warnedKeys.add(key)
+  console.warn(message)
+}
+
+/**
+ * Reset all warning states. Primarily useful for testing.
+ */
+export function resetWarnings(): void {
+  warnedKeys.clear()
+}

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

@@ -6,7 +6,7 @@ import {
 } from '@electric-sql/client'
 import { Store } from '@tanstack/store'
 import DebugModule from 'debug'
-import { DeduplicatedLoadSubset, and } from '@tanstack/db'
+import { DeduplicatedLoadSubset, and, warnOnce } from '@tanstack/db'
 import {
   ExpectedNumberInAwaitTxIdError,
   StreamAbortedError,
@@ -837,7 +837,8 @@ export function electricCollectionOptions<T extends Row<unknown>>(
     // Only wait if result contains txid
     if (result && `txid` in result) {
       // Warn about deprecated return value pattern
-      console.warn(
+      warnOnce(
+        'electric-collection-txid-return',
         '[TanStack DB] DEPRECATED: Returning { txid } from mutation handlers is deprecated and will be removed in v1.0. ' +
           'Use `await collection.utils.awaitTxId(txid)` instead of returning { txid }. ' +
           'See migration guide: https://tanstack.com/db/latest/docs/collections/electric-collection#persistence-handlers--synchronization',

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

@@ -1,5 +1,5 @@
 import { QueryObserver, hashKey } from '@tanstack/query-core'
-import { deepEquals } from '@tanstack/db'
+import { deepEquals, warnOnce } from '@tanstack/db'
 import {
   GetKeyRequiredError,
   QueryClientRequiredError,
@@ -1251,23 +1251,31 @@ export function queryCollectionOptions(
     ? async (params: InsertMutationFnParams<any>) => {
         const handlerResult = (await onInsert(params)) ?? {}
 
-        // Warn about deprecated return value pattern
-        if (
+        const explicitRefetchFalse =
           handlerResult &&
           typeof handlerResult === 'object' &&
-          Object.keys(handlerResult).length > 0
-        ) {
-          console.warn(
-            '[TanStack DB] DEPRECATED: Returning values from mutation handlers is deprecated and will be removed in v1.0. ' +
-              'Use `await collection.utils.refetch()` instead of returning { refetch }. ' +
-              'See migration guide: https://tanstack.com/db/latest/docs/guides/mutations#collection-specific-handler-patterns',
+          'refetch' in handlerResult &&
+          handlerResult.refetch === false
+
+        if (explicitRefetchFalse) {
+          // User is correctly opting out of auto-refetch - warn about upcoming change
+          warnOnce(
+            'query-collection-refetch-false',
+            '[TanStack DB] Note: `return { refetch: false }` is the correct way to skip auto-refetch for now. ' +
+              'In v1.0, auto-refetch will be removed entirely and you should call `await collection.utils.refetch()` explicitly when needed, ' +
+              'or omit it to skip refetching. ' +
+              'See: https://tanstack.com/db/latest/docs/collections/query-collection#controlling-refetch-behavior',
+          )
+        } else {
+          // Auto-refetch is happening - warn about upcoming removal
+          warnOnce(
+            'query-collection-auto-refetch',
+            '[TanStack DB] DEPRECATED: QueryCollection handlers currently auto-refetch after completion. ' +
+              'This behavior will be removed in v1.0. To prepare: ' +
+              '(1) Add `await collection.utils.refetch()` to your handler if you need refetching, or ' +
+              '(2) Return `{ refetch: false }` to opt out now if you don\'t need it. ' +
+              'See: https://tanstack.com/db/latest/docs/collections/query-collection#controlling-refetch-behavior',
           )
-        }
-
-        const shouldRefetch =
-          (handlerResult as { refetch?: boolean }).refetch !== false
-
-        if (shouldRefetch) {
           await refetch()
         }
 
@@ -1279,23 +1287,29 @@ export function queryCollectionOptions(
     ? async (params: UpdateMutationFnParams<any>) => {
         const handlerResult = (await onUpdate(params)) ?? {}
 
-        // Warn about deprecated return value pattern
-        if (
+        const explicitRefetchFalse =
           handlerResult &&
           typeof handlerResult === 'object' &&
-          Object.keys(handlerResult).length > 0
-        ) {
-          console.warn(
-            '[TanStack DB] DEPRECATED: Returning values from mutation handlers is deprecated and will be removed in v1.0. ' +
-              'Use `await collection.utils.refetch()` instead of returning { refetch }. ' +
-              'See migration guide: https://tanstack.com/db/latest/docs/guides/mutations#collection-specific-handler-patterns',
+          'refetch' in handlerResult &&
+          handlerResult.refetch === false
+
+        if (explicitRefetchFalse) {
+          warnOnce(
+            'query-collection-refetch-false',
+            '[TanStack DB] Note: `return { refetch: false }` is the correct way to skip auto-refetch for now. ' +
+              'In v1.0, auto-refetch will be removed entirely and you should call `await collection.utils.refetch()` explicitly when needed, ' +
+              'or omit it to skip refetching. ' +
+              'See: https://tanstack.com/db/latest/docs/collections/query-collection#controlling-refetch-behavior',
+          )
+        } else {
+          warnOnce(
+            'query-collection-auto-refetch',
+            '[TanStack DB] DEPRECATED: QueryCollection handlers currently auto-refetch after completion. ' +
+              'This behavior will be removed in v1.0. To prepare: ' +
+              '(1) Add `await collection.utils.refetch()` to your handler if you need refetching, or ' +
+              '(2) Return `{ refetch: false }` to opt out now if you don\'t need it. ' +
+              'See: https://tanstack.com/db/latest/docs/collections/query-collection#controlling-refetch-behavior',
           )
-        }
-
-        const shouldRefetch =
-          (handlerResult as { refetch?: boolean }).refetch !== false
-
-        if (shouldRefetch) {
           await refetch()
         }
 
@@ -1307,23 +1321,29 @@ export function queryCollectionOptions(
     ? async (params: DeleteMutationFnParams<any>) => {
         const handlerResult = (await onDelete(params)) ?? {}
 
-        // Warn about deprecated return value pattern
-        if (
+        const explicitRefetchFalse =
           handlerResult &&
           typeof handlerResult === 'object' &&
-          Object.keys(handlerResult).length > 0
-        ) {
-          console.warn(
-            '[TanStack DB] DEPRECATED: Returning values from mutation handlers is deprecated and will be removed in v1.0. ' +
-              'Use `await collection.utils.refetch()` instead of returning { refetch }. ' +
-              'See migration guide: https://tanstack.com/db/latest/docs/guides/mutations#collection-specific-handler-patterns',
+          'refetch' in handlerResult &&
+          handlerResult.refetch === false
+
+        if (explicitRefetchFalse) {
+          warnOnce(
+            'query-collection-refetch-false',
+            '[TanStack DB] Note: `return { refetch: false }` is the correct way to skip auto-refetch for now. ' +
+              'In v1.0, auto-refetch will be removed entirely and you should call `await collection.utils.refetch()` explicitly when needed, ' +
+              'or omit it to skip refetching. ' +
+              'See: https://tanstack.com/db/latest/docs/collections/query-collection#controlling-refetch-behavior',
+          )
+        } else {
+          warnOnce(
+            'query-collection-auto-refetch',
+            '[TanStack DB] DEPRECATED: QueryCollection handlers currently auto-refetch after completion. ' +
+              'This behavior will be removed in v1.0. To prepare: ' +
+              '(1) Add `await collection.utils.refetch()` to your handler if you need refetching, or ' +
+              '(2) Return `{ refetch: false }` to opt out now if you don\'t need it. ' +
+              'See: https://tanstack.com/db/latest/docs/collections/query-collection#controlling-refetch-behavior',
           )
-        }
-
-        const shouldRefetch =
-          (handlerResult as { refetch?: boolean }).refetch !== false
-
-        if (shouldRefetch) {
           await refetch()
         }