Fix type issue with mutations in transaction

.changeset/twelve-pans-act.md

@@ -0,0 +1,6 @@
+---
+"@tanstack/electric-db-collection": patch
+"@tanstack/db": patch
+---
+
+Improve type of mutations in transactions

packages/db/src/types.ts

@@ -139,7 +139,26 @@ export type NonEmptyArray<T> = [T, ...Array<T>]
 export type TransactionWithMutations<
   T extends object = Record<string, unknown>,
   TOperation extends OperationType = OperationType,
-> = Transaction<T> & {
+> = Omit<Transaction<T>, `mutations`> & {
+  /**
+   * We must omit the `mutations` property from `Transaction<T>` before intersecting
+   * because TypeScript intersects property types when the same property appears on
+   * both sides of an intersection.
+   *
+   * Without `Omit`:
+   * - `Transaction<T>` has `mutations: Array<PendingMutation<T>>`
+   * - The intersection would create: `Array<PendingMutation<T>> & NonEmptyArray<PendingMutation<T, TOperation>>`
+   * - When mapping over this array, TypeScript widens `TOperation` from the specific literal
+   *   (e.g., `"delete"`) to the union `OperationType` (`"insert" | "update" | "delete"`)
+   * - This causes `PendingMutation<T, OperationType>` to evaluate the conditional type
+   *   `original: TOperation extends 'insert' ? {} : T` as `{} | T` instead of just `T`
+   *
+   * With `Omit`:
+   * - We remove `mutations` from `Transaction<T>` first
+   * - Then add back `mutations: NonEmptyArray<PendingMutation<T, TOperation>>`
+   * - TypeScript can properly narrow `TOperation` to the specific literal type
+   * - This ensures `mutation.original` is correctly typed as `T` (not `{} | T`) when mapping
+   */
   mutations: NonEmptyArray<PendingMutation<T, TOperation>>
 }
 

packages/electric-db-collection/tests/electric.test-d.ts

@@ -141,6 +141,88 @@ describe(`Electric collection type resolution tests`, () => {
     >()
   })
 
+  it(`should correctly type mutations in transaction handlers when mapping over mutations array`, () => {
+    const schema = z.object({
+      id: z.string(),
+      title: z.string(),
+      completed: z.boolean(),
+    })
+
+    type TodoType = z.infer<typeof schema>
+
+    const options = electricCollectionOptions({
+      id: `todos`,
+      schema,
+      getKey: (item) => item.id,
+      shapeOptions: {
+        url: `/api/todos`,
+        params: { table: `todos` },
+      },
+      onDelete: (params) => {
+        // Direct index access should be correctly typed
+        expectTypeOf(
+          params.transaction.mutations[0].original
+        ).toEqualTypeOf<TodoType>()
+
+        // Non-null assertion on second element should be correctly typed
+        expectTypeOf(
+          params.transaction.mutations[1]!.original
+        ).toEqualTypeOf<TodoType>()
+
+        // When mapping over mutations, each mutation.original should be correctly typed
+        params.transaction.mutations.map((mutation) => {
+          expectTypeOf(mutation.original).toEqualTypeOf<TodoType>()
+          return mutation.original.id
+        })
+
+        return Promise.resolve({ txid: 1 })
+      },
+      onInsert: (params) => {
+        // Direct index access should be correctly typed
+        expectTypeOf(
+          params.transaction.mutations[0].modified
+        ).toEqualTypeOf<TodoType>()
+
+        // When mapping over mutations, each mutation.modified should be correctly typed
+        params.transaction.mutations.map((mutation) => {
+          expectTypeOf(mutation.modified).toEqualTypeOf<TodoType>()
+          return mutation.modified.id
+        })
+
+        return Promise.resolve({ txid: 1 })
+      },
+      onUpdate: (params) => {
+        // Direct index access should be correctly typed
+        expectTypeOf(
+          params.transaction.mutations[0].original
+        ).toEqualTypeOf<TodoType>()
+        expectTypeOf(
+          params.transaction.mutations[0].modified
+        ).toEqualTypeOf<TodoType>()
+
+        // When mapping over mutations, each mutation should be correctly typed
+        params.transaction.mutations.map((mutation) => {
+          expectTypeOf(mutation.original).toEqualTypeOf<TodoType>()
+          expectTypeOf(mutation.modified).toEqualTypeOf<TodoType>()
+          return mutation.modified.id
+        })
+
+        return Promise.resolve({ txid: 1 })
+      },
+    })
+
+    // Verify that the handlers are properly typed
+    expectTypeOf(options.onDelete).parameters.toEqualTypeOf<
+      [DeleteMutationFnParams<TodoType>]
+    >()
+    expectTypeOf(options.onInsert).parameters.toEqualTypeOf<
+      [InsertMutationFnParams<TodoType>]
+    >()
+    expectTypeOf(options.onUpdate).parameters.toEqualTypeOf<
+      [UpdateMutationFnParams<TodoType>]
+    >()
+  })
+
   it(`should infer types from Zod schema through electric collection options to live query`, () => {
     // Define a Zod schema for a user with basic field types
     const userSchema = z.object({