TanStackDB v0
Auto
Framework
Version
Menu
Getting Started
Guides
Collections
Community
API Reference

Transaction

Interface: Transaction<T>

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

Type Parameters

T

T extends object = Record<string, unknown>

Properties

autoCommit
ts
autoCommit: boolean;

autoCommit: boolean;

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

createdAt
ts
createdAt: Date;

createdAt: Date;

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

error?
ts
optional error: object;

optional error: object;

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

error
ts
error: Error;

error: Error;

message
ts
message: string;

message: string;

id
ts
id: string;

id: string;

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

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

isPersisted: Deferred<Transaction<T>>;

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

metadata
ts
metadata: Record<string, unknown>;

metadata: Record<string, unknown>;

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

mutationFn
ts
mutationFn: MutationFn<T>;

mutationFn: MutationFn<T>;

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

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

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

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

sequenceNumber
ts
sequenceNumber: number;

sequenceNumber: number;

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

state
ts
state: TransactionState;

state: TransactionState;

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

Methods

applyMutations()
ts
applyMutations(mutations): void;

applyMutations(mutations): void;

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

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()
ts
commit(): Promise<Transaction<T>>;

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

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

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

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

// 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"

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

compareCreatedAt()
ts
compareCreatedAt(other): number;

compareCreatedAt(other): number;

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

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>;

mutate(callback): Transaction<T>;

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

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

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

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

// 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>;

rollback(config?): Transaction<T>;

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

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

// 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

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

// 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;

setState(newState): void;

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

Parameters
newState

TransactionState

Returns

void

touchCollection()
ts
touchCollection(): void;

touchCollection(): void;

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

Returns

void

Edit on GitHub
Home