feat: Add non-optimistic mutations support (#250)

Co-authored-by: Claude <noreply@anthropic.com>

Author: KyleAMathews

.changeset/mighty-falcons-invite.md

@@ -0,0 +1,10 @@
+---
+"@tanstack/db": patch
+---
+
+Add non-optimistic mutations support
+
+- Add `optimistic` option to insert, update, and delete operations
+- Default `optimistic: true` maintains backward compatibility
+- When `optimistic: false`, mutations only apply after server confirmation
+- Enables better control for server-validated operations and confirmation workflows

docs/overview.md

@@ -575,6 +575,21 @@ insert([
   { text: "Buy groceries", completed: false },
   { text: "Walk dog", completed: false },
 ])
+
+// Insert with optimistic updates disabled
+myCollection.insert(
+  { text: "Server-validated item", completed: false },
+  { optimistic: false }
+)
+
+// Insert with metadata and optimistic control
+myCollection.insert(
+  { text: "Custom item", completed: false },
+  { 
+    metadata: { source: "import" },
+    optimistic: true  // default behavior
+  }
+)
 ```
 
 ##### `update`
@@ -598,6 +613,27 @@ update([todo1.id, todo2.id], (drafts) => {
 update(todo.id, { metadata: { reason: "user update" } }, (draft) => {
   draft.text = "Updated text"
 })
+
+// Update without optimistic updates
+update(
+  todo.id, 
+  { optimistic: false }, 
+  (draft) => {
+    draft.status = "server-validated"
+  }
+)
+
+// Update with both metadata and optimistic control
+update(
+  todo.id,
+  { 
+    metadata: { reason: "admin update" },
+    optimistic: false 
+  },
+  (draft) => {
+    draft.priority = "high"
+  }
+)
 ```
 
 ##### `delete`
@@ -611,6 +647,67 @@ delete([todo1.id, todo2.id])
 
 // Delete with metadata
 delete(todo.id, { metadata: { reason: "completed" } })
+
+// Delete without optimistic updates (waits for server confirmation)
+delete(todo.id, { optimistic: false })
+
+// Delete with metadata and optimistic control
+delete(todo.id, { 
+  metadata: { reason: "admin deletion" },
+  optimistic: false 
+})
+```
+
+#### Controlling optimistic behavior
+
+By default, all mutations (`insert`, `update`, `delete`) apply optimistic updates immediately to provide instant feedback in your UI. However, there are cases where you may want to disable this behavior and wait for server confirmation before applying changes locally.
+
+##### When to use `optimistic: false`
+
+Consider disabling optimistic updates when:
+
+- **Complex server-side processing**: Inserts that depend on server-side generation (e.g., cascading foreign keys, computed fields)
+- **Validation requirements**: Operations where backend validation might reject the change
+- **Confirmation workflows**: Deletes where UX should wait for confirmation before removing data
+- **Batch operations**: Large operations where optimistic rollback would be disruptive
+
+##### Behavior differences
+
+**`optimistic: true` (default)**:
+- Immediately applies mutation to the local store
+- Provides instant UI feedback  
+- Requires rollback if server rejects the mutation
+- Best for simple, predictable operations
+
+**`optimistic: false`**:
+- Does not modify local store until server confirms
+- No immediate UI feedback, but no rollback needed
+- UI updates only after successful server response
+- Best for complex or validation-heavy operations
+
+```typescript
+// Example: Critical deletion that needs confirmation
+const handleDeleteAccount = () => {
+  // Don't remove from UI until server confirms
+  userCollection.delete(userId, { optimistic: false })
+}
+
+// Example: Server-generated data
+const handleCreateInvoice = () => {
+  // Server generates invoice number, tax calculations, etc.
+  invoiceCollection.insert(invoiceData, { optimistic: false })
+}
+
+// Example: Mixed approach in same transaction
+tx.mutate(() => {
+  // Instant UI feedback for simple change
+  todoCollection.update(todoId, (draft) => {
+    draft.completed = true
+  })
+  
+  // Wait for server confirmation for complex change
+  auditCollection.insert(auditRecord, { optimistic: false })
+})
 ```
 
 ## Usage examples

packages/db/src/collection.ts

@@ -634,7 +634,7 @@ export class CollectionImpl<
     // Apply active transactions only (completed transactions are handled by sync operations)
     for (const transaction of activeTransactions) {
       for (const mutation of transaction.mutations) {
-        if (mutation.collection === this) {
+        if (mutation.collection === this && mutation.optimistic) {
           switch (mutation.type) {
             case `insert`:
             case `update`:
@@ -1064,7 +1064,7 @@ export class CollectionImpl<
       for (const transaction of this.transactions.values()) {
         if (![`completed`, `failed`].includes(transaction.state)) {
           for (const mutation of transaction.mutations) {
-            if (mutation.collection === this) {
+            if (mutation.collection === this && mutation.optimistic) {
               switch (mutation.type) {
                 case `insert`:
                 case `update`:
@@ -1358,6 +1358,7 @@ export class CollectionImpl<
         key,
         metadata: config?.metadata as unknown,
         syncMetadata: this.config.sync.getSyncMetadata?.() || {},
+        optimistic: config?.optimistic ?? true,
         type: `insert`,
         createdAt: new Date(),
         updatedAt: new Date(),
@@ -1573,6 +1574,7 @@ export class CollectionImpl<
             string,
             unknown
           >,
+          optimistic: config.optimistic ?? true,
           type: `update`,
           createdAt: new Date(),
           updatedAt: new Date(),
@@ -1696,6 +1698,7 @@ export class CollectionImpl<
           string,
           unknown
         >,
+        optimistic: config?.optimistic ?? true,
         type: `delete`,
         createdAt: new Date(),
         updatedAt: new Date(),

packages/db/src/proxy.ts

@@ -505,7 +505,6 @@ export function createChangeProxy<
                   if (typeof callback === `function`) {
                     // Replace the original callback with our wrapped version
                     const wrappedCallback = function (
-                      // eslint-disable-next-line
                       this: unknown,
                       // eslint-disable-next-line
                       value: unknown,

packages/db/src/types.ts

@@ -69,6 +69,8 @@ export interface PendingMutation<
   type: OperationType
   metadata: unknown
   syncMetadata: Record<string, unknown>
+  /** Whether this mutation should be applied optimistically (defaults to true) */
+  optimistic: boolean
   createdAt: Date
   updatedAt: Date
   collection: Collection<T, any, any>
@@ -203,10 +205,14 @@ export type StandardSchemaAlias<T = unknown> = StandardSchema<T>
 
 export interface OperationConfig {
   metadata?: Record<string, unknown>
+  /** Whether to apply optimistic updates immediately. Defaults to true. */
+  optimistic?: boolean
 }
 
 export interface InsertConfig {
   metadata?: Record<string, unknown>
+  /** Whether to apply optimistic updates immediately. Defaults to true. */
+  optimistic?: boolean
 }
 
 export type UpdateMutationFnParams<