# Transaction

# Interface: Transaction\<T\>

Defined in: [packages/db/src/transactions.ts:208](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L208)

## Type Parameters

### T

`T` *extends* `object` = `Record`\<`string`, `unknown`\>

## Properties

### autoCommit

```ts
autoCommit: boolean;
```

Defined in: [packages/db/src/transactions.ts:214](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L214)

***

### createdAt

```ts
createdAt: Date;
```

Defined in: [packages/db/src/transactions.ts:215](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L215)

***

### error?

```ts
optional error: object;
```

Defined in: [packages/db/src/transactions.ts:218](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L218)

#### error

```ts
error: Error;
```

#### message

```ts
message: string;
```

***

### id

```ts
id: string;
```

Defined in: [packages/db/src/transactions.ts:209](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L209)

***

### isPersisted

```ts
isPersisted: Deferred<Transaction<T>>;
```

Defined in: [packages/db/src/transactions.ts:213](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L213)

***

### metadata

```ts
metadata: Record<string, unknown>;
```

Defined in: [packages/db/src/transactions.ts:217](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L217)

***

### mutationFn

```ts
mutationFn: MutationFn<T>;
```

Defined in: [packages/db/src/transactions.ts:211](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L211)

***

### mutations

```ts
mutations: PendingMutation<T, OperationType, Collection<T, any, any, any, any>>[];
```

Defined in: [packages/db/src/transactions.ts:212](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L212)

***

### sequenceNumber

```ts
sequenceNumber: number;
```

Defined in: [packages/db/src/transactions.ts:216](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L216)

***

### state

```ts
state: TransactionState;
```

Defined in: [packages/db/src/transactions.ts:210](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L210)

## Methods

### applyMutations()

```ts
applyMutations(mutations): void;
```

Defined in: [packages/db/src/transactions.ts:327](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L327)

Apply new mutations to this transaction, intelligently merging with existing mutations

When mutations operate on the same item (same globalKey), they are merged according to
the following rules:

- **insert + update** → insert (merge changes, keep empty original)
- **insert + delete** → removed (mutations cancel each other out)
- **update + delete** → delete (delete dominates)
- **update + update** → update (union changes, keep first original)
- **same type** → replace with latest

This merging reduces over-the-wire churn and keeps the optimistic local view
aligned with user intent.

#### Parameters

##### mutations

[`PendingMutation`](PendingMutation.md)\<`any`, [`OperationType`](../type-aliases/OperationType.md), [`Collection`](Collection.md)\<`any`, `any`, `any`, `any`, `any`\>\>[]

Array of new mutations to apply

#### Returns

`void`

***

### commit()

```ts
commit(): Promise<Transaction<T>>;
```

Defined in: [packages/db/src/transactions.ts:472](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L472)

Commit the transaction and execute the mutation function

#### Returns

`Promise`\<`Transaction`\<`T`\>\>

Promise that resolves to this transaction when complete

#### Examples

```ts
// Manual commit (when autoCommit is false)
const tx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await api.saveChanges(transaction.mutations)
  }
})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
})

await tx.commit() // Manually commit
```

```ts
// Handle commit errors
try {
  const tx = createTransaction({
    mutationFn: async () => { throw new Error("API failed") }
  })

  tx.mutate(() => {
    collection.insert({ id: "1", text: "Item" })
  })

  await tx.commit()
} catch (error) {
  console.log('Commit failed, transaction rolled back:', error)
}
```

```ts
// Check transaction state after commit
await tx.commit()
console.log(tx.state) // "completed" or "failed"
```

***

### compareCreatedAt()

```ts
compareCreatedAt(other): number;
```

Defined in: [packages/db/src/transactions.ts:526](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L526)

Compare two transactions by their createdAt time and sequence number in order
to sort them in the order they were created.

#### Parameters

##### other

`Transaction`\<`any`\>

The other transaction to compare to

#### Returns

`number`

-1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time

***

### mutate()

```ts
mutate(callback): Transaction<T>;
```

Defined in: [packages/db/src/transactions.ts:287](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L287)

Execute collection operations within this transaction

#### Parameters

##### callback

() => `void`

Function containing collection operations to group together. If the
callback returns a Promise, the transaction context will remain active until the promise
settles, allowing optimistic writes after `await` boundaries.

#### Returns

`Transaction`\<`T`\>

This transaction for chaining

#### Examples

```ts
// Group multiple operations
const tx = createTransaction({ mutationFn: async () => {
  // Send to API
}})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
  collection.update("2", draft => { draft.completed = true })
  collection.delete("3")
})

await tx.isPersisted.promise
```

```ts
// Handle mutate errors
try {
  tx.mutate(() => {
    collection.insert({ id: "invalid" }) // This might throw
  })
} catch (error) {
  console.log('Mutation failed:', error)
}
```

```ts
// Manual commit control
const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })

tx.mutate(() => {
  collection.insert({ id: "1", text: "Item" })
})

// Commit later when ready
await tx.commit()
```

***

### rollback()

```ts
rollback(config?): Transaction<T>;
```

Defined in: [packages/db/src/transactions.ts:389](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L389)

Rollback the transaction and any conflicting transactions

#### Parameters

##### config?

Configuration for rollback behavior

###### isSecondaryRollback?

`boolean`

#### Returns

`Transaction`\<`T`\>

This transaction for chaining

#### Examples

```ts
// Manual rollback
const tx = createTransaction({ mutationFn: async () => {
  // Send to API
}})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
})

// Rollback if needed
if (shouldCancel) {
  tx.rollback()
}
```

```ts
// Handle rollback cascade (automatic)
const tx1 = createTransaction({ mutationFn: async () => {} })
const tx2 = createTransaction({ mutationFn: async () => {} })

tx1.mutate(() => collection.update("1", draft => { draft.value = "A" }))
tx2.mutate(() => collection.update("1", draft => { draft.value = "B" })) // Same item

tx1.rollback() // This will also rollback tx2 due to conflict
```

```ts
// Handle rollback in error scenarios
try {
  await tx.isPersisted.promise
} catch (error) {
  console.log('Transaction was rolled back:', error)
  // Transaction automatically rolled back on mutation function failure
}
```

***

### setState()

```ts
setState(newState): void;
```

Defined in: [packages/db/src/transactions.ts:238](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L238)

#### Parameters

##### newState

[`TransactionState`](../type-aliases/TransactionState.md)

#### Returns

`void`

***

### touchCollection()

```ts
touchCollection(): void;
```

Defined in: [packages/db/src/transactions.ts:417](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L417)

#### Returns

`void`