Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

Transaction.md

436 lines8.9 KB

Interface: Transaction<T>

Defined in: packages/db/src/transactions.ts:209

Type Parameters

T

T extends object = Record<string, unknown>

Properties

autoCommit

autoCommit: boolean;

Defined in: packages/db/src/transactions.ts:227


createdAt

createdAt: Date;

Defined in: packages/db/src/transactions.ts:228


error?

optional error: object;

Defined in: packages/db/src/transactions.ts:231

error

error: Error;

message

message: string;

id

id: string;

Defined in: packages/db/src/transactions.ts:210


isPersisted

isPersisted: Deferred<Transaction<T>>;

Defined in: packages/db/src/transactions.ts:226

Deferred that settles when this transaction settles.

Await isPersisted.promise, not isPersisted itself. The promise resolves when the transaction completes successfully and rejects if the transaction fails or is rolled back.

For non-empty commits, the mutation function is the normal settlement boundary. This does not inherently prove that a backend has uploaded, confirmed, or read back the write unless the mutation function waits for that backend observation before returning.


metadata

metadata: Record<string, unknown>;

Defined in: packages/db/src/transactions.ts:230


mutationFn

mutationFn: MutationFn<T>;

Defined in: packages/db/src/transactions.ts:212


mutations

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

Defined in: packages/db/src/transactions.ts:213


sequenceNumber

sequenceNumber: number;

Defined in: packages/db/src/transactions.ts:229


state

state: TransactionState;

Defined in: packages/db/src/transactions.ts:211

Methods

applyMutations()

applyMutations(mutations): void;

Defined in: packages/db/src/transactions.ts:348

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<any, OperationType, Collection<any, any, any, any, any>>[]

Array of new mutations to apply

Returns

void


commit()

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

Defined in: packages/db/src/transactions.ts:505

Commit the transaction and execute the mutation function

Returns

Promise<Transaction<T>>

Promise that resolves to this transaction when complete

Examples

// 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
// 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)
}
// Check transaction state after commit
await tx.commit()
console.log(tx.state) // "completed" or "failed"

compareCreatedAt()

compareCreatedAt(other): number;

Defined in: packages/db/src/transactions.ts:559

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()

mutate(callback): Transaction<T>;

Defined in: packages/db/src/transactions.ts:308

Execute collection operations within this transaction

Parameters

callback

() => void

Synchronous function containing collection operations to group together. The transaction context is active only for the synchronous duration of this callback. Async work should happen in mutationFn; collection operations after await boundaries inside this callback will not be part of this transaction. For manual transactions, call mutate multiple times before committing to add more synchronous operations to the same transaction.

Returns

Transaction<T>

This transaction for chaining

Examples

// 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
// Handle mutate errors
try {
  tx.mutate(() => {
    collection.insert({ id: "invalid" }) // This might throw
  })
} catch (error) {
  console.log('Mutation failed:', error)
}
// Manual commit control
const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })

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

// Add more synchronous mutations to the same transaction
tx.mutate(() => {
  collection.update("1", draft => { draft.text = "Updated item" })
})

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

rollback()

rollback(config?): Transaction<T>;

Defined in: packages/db/src/transactions.ts:422

Rollback the transaction and any conflicting transactions

Parameters

config?

Configuration for rollback behavior

isSecondaryRollback?

boolean

Returns

Transaction<T>

This transaction for chaining

Examples

// 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()
}
// 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
// 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()

setState(newState): void;

Defined in: packages/db/src/transactions.ts:251

Parameters

newState

TransactionState

Returns

void


touchCollection()

touchCollection(): void;

Defined in: packages/db/src/transactions.ts:450

Returns

void