feat: add runtime deprecation warnings for handler return values

Based on external code review feedback, this commit implements a soft deprecation
strategy for mutation handler return values:

Runtime changes:
- Add console warnings when QueryCollection handlers return { refetch }
- Add console warnings when Electric handlers return { txid }
- Keep runtime functionality intact for backward compatibility
- Runtime support will be removed in v1.0 RC

Type improvements:
- Mark TReturn generic as @internal and deprecated across all mutation types
- Clarify that it exists only for backward compatibility

Documentation improvements:
- Clarify Electric JSDoc: handlers return Promise<void> but must not RESOLVE
  until synchronization is complete (avoiding "void but not void" confusion)
- Add timeout error handling example showing policy choices (rollback vs
  eventual consistency)
- Update changeset to clearly communicate this is a soft deprecation

This aligns with the review recommendation for a gradual migration path with
clear runtime feedback to help users migrate to the new explicit patterns.

Author: claude

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

@@ -4,13 +4,21 @@
 "@tanstack/query-db-collection": major
 ---
 
-**BREAKING**: Deprecate returning values from mutation handlers (`onInsert`, `onUpdate`, `onDelete`). Instead, use explicit sync coordination:
+**BREAKING (TypeScript only)**: Deprecate returning values from mutation handlers (`onInsert`, `onUpdate`, `onDelete`).
 
+**What's changed:**
+- Handler types now default to `Promise<void>` instead of `Promise<any>`
+- TypeScript will error on `return { refetch: false }` or `return { txid }`
+- Runtime still supports old return patterns for backward compatibility
+- **Deprecation warnings** are now logged when handlers return values
+- Old patterns will be fully removed in v1.0 RC
+
+**New pattern (explicit sync coordination):**
 - **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
 
-This change makes the API more explicit and consistent across all collection types. Magic return values like `{ refetch: false }` in Query Collections and `{ txid }` in Electric Collections are now deprecated. All handlers should coordinate sync explicitly within the handler function.
+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.
 
 Migration guide:
 

packages/db/src/types.ts

@@ -363,20 +363,29 @@ export type DeleteMutationFnParams<
   collection: Collection<T, TKey, TUtils>
 }
 
+/**
+ * @typeParam TReturn - @internal DEPRECATED: Defaults to void. Only kept for backward compatibility. Will be removed in v1.0.
+ */
 export type InsertMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = UtilsRecord,
   TReturn = void,
 > = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>
 
+/**
+ * @typeParam TReturn - @internal DEPRECATED: Defaults to void. Only kept for backward compatibility. Will be removed in v1.0.
+ */
 export type UpdateMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
   TUtils extends UtilsRecord = UtilsRecord,
   TReturn = void,
 > = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>
 
+/**
+ * @typeParam TReturn - @internal DEPRECATED: Defaults to void. Only kept for backward compatibility. Will be removed in v1.0.
+ */
 export type DeleteMutationFn<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,
@@ -413,6 +422,11 @@ export type CollectionStatus =
 
 export type SyncMode = `eager` | `on-demand`
 
+/**
+ * @typeParam TReturn - @internal DEPRECATED: This generic parameter exists for backward compatibility only.
+ * Mutation handlers should not return values. Use collection utilities (refetch, awaitTxId, etc.) for sync coordination.
+ * This parameter will be removed in v1.0.
+ */
 export interface BaseCollectionConfig<
   T extends object = Record<string, unknown>,
   TKey extends string | number = string | number,

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

@@ -122,13 +122,15 @@ export interface ElectricCollectionConfig<
    * Optional asynchronous handler function called before an insert operation
    *
    * **IMPORTANT - Electric Synchronization:**
-   * Electric collections require explicit synchronization coordination to ensure changes have synced
-   * from the server before dropping optimistic state. Use one of these patterns:
-   * 1. Call `await collection.utils.awaitTxId(txid)` (recommended for most cases)
-   * 2. Call `await collection.utils.awaitMatch()` for custom matching logic
+   * This handler returns `Promise<void>`, but **must not resolve** until synchronization is confirmed.
+   * You must await one of these synchronization utilities before the handler completes:
+   * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+   * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+   *
+   * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
    *
    * @param params Object containing transaction and collection information
-   * @returns Promise that should resolve to void
+   * @returns Promise<void> - Must not resolve until synchronization is complete
    * @deprecated Returning { txid } from handlers is deprecated. Use `await collection.utils.awaitTxId(txid)` instead.
    *
    * @example
@@ -154,6 +156,26 @@ export interface ElectricCollectionConfig<
    * }
    *
    * @example
+   * // Insert handler with timeout error handling
+   * onInsert: async ({ transaction, collection }) => {
+   *   const newItem = transaction.mutations[0].modified
+   *   const result = await api.todos.create({
+   *     data: newItem
+   *   })
+   *
+   *   try {
+   *     await collection.utils.awaitTxId(result.txid, 5000)
+   *   } catch (error) {
+   *     // Decide sync timeout policy:
+   *     // - Throw to rollback optimistic state
+   *     // - Catch to keep optimistic state (eventual consistency)
+   *     // - Schedule background retry
+   *     console.warn('Sync timeout, keeping optimistic state:', error)
+   *     // Don't throw - allow optimistic state to persist
+   *   }
+   * }
+   *
+   * @example
    * // Insert handler with multiple items
    * onInsert: async ({ transaction, collection }) => {
    *   const items = transaction.mutations.map(m => m.modified)
@@ -185,13 +207,15 @@ export interface ElectricCollectionConfig<
    * Optional asynchronous handler function called before an update operation
    *
    * **IMPORTANT - Electric Synchronization:**
-   * Electric collections require explicit synchronization coordination to ensure changes have synced
-   * from the server before dropping optimistic state. Use one of these patterns:
-   * 1. Call `await collection.utils.awaitTxId(txid)` (recommended for most cases)
-   * 2. Call `await collection.utils.awaitMatch()` for custom matching logic
+   * This handler returns `Promise<void>`, but **must not resolve** until synchronization is confirmed.
+   * You must await one of these synchronization utilities before the handler completes:
+   * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+   * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+   *
+   * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
    *
    * @param params Object containing transaction and collection information
-   * @returns Promise that should resolve to void
+   * @returns Promise<void> - Must not resolve until synchronization is complete
    * @deprecated Returning { txid } from handlers is deprecated. Use `await collection.utils.awaitTxId(txid)` instead.
    *
    * @example
@@ -225,13 +249,15 @@ export interface ElectricCollectionConfig<
    * Optional asynchronous handler function called before a delete operation
    *
    * **IMPORTANT - Electric Synchronization:**
-   * Electric collections require explicit synchronization coordination to ensure changes have synced
-   * from the server before dropping optimistic state. Use one of these patterns:
-   * 1. Call `await collection.utils.awaitTxId(txid)` (recommended for most cases)
-   * 2. Call `await collection.utils.awaitMatch()` for custom matching logic
+   * This handler returns `Promise<void>`, but **must not resolve** until synchronization is confirmed.
+   * You must await one of these synchronization utilities before the handler completes:
+   * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+   * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+   *
+   * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
    *
    * @param params Object containing transaction and collection information
-   * @returns Promise that should resolve to void
+   * @returns Promise<void> - Must not resolve until synchronization is complete
    * @deprecated Returning { txid } from handlers is deprecated. Use `await collection.utils.awaitTxId(txid)` instead.
    *
    * @example
@@ -584,6 +610,13 @@ export function electricCollectionOptions(
   ): Promise<void> => {
     // Only wait if result contains txid
     if (result && `txid` in result) {
+      // Warn about deprecated return value pattern
+      console.warn(
+        '[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'
+      )
+
       const timeout = result.timeout
       // Handle both single txid and array of txids
       if (Array.isArray(result.txid)) {

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

@@ -1033,6 +1033,16 @@ export function queryCollectionOptions(
   const wrappedOnInsert = onInsert
     ? async (params: InsertMutationFnParams<any>) => {
         const handlerResult = (await onInsert(params)) ?? {}
+
+        // Warn about deprecated return value pattern
+        if (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'
+          )
+        }
+
         const shouldRefetch =
           (handlerResult as { refetch?: boolean }).refetch !== false
 
@@ -1047,6 +1057,16 @@ export function queryCollectionOptions(
   const wrappedOnUpdate = onUpdate
     ? async (params: UpdateMutationFnParams<any>) => {
         const handlerResult = (await onUpdate(params)) ?? {}
+
+        // Warn about deprecated return value pattern
+        if (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'
+          )
+        }
+
         const shouldRefetch =
           (handlerResult as { refetch?: boolean }).refetch !== false
 
@@ -1061,6 +1081,16 @@ export function queryCollectionOptions(
   const wrappedOnDelete = onDelete
     ? async (params: DeleteMutationFnParams<any>) => {
         const handlerResult = (await onDelete(params)) ?? {}
+
+        // Warn about deprecated return value pattern
+        if (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'
+          )
+        }
+
         const shouldRefetch =
           (handlerResult as { refetch?: boolean }).refetch !== false