TanStack
DB v0v0
Documentation
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
Partners
Code Rabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
Sentry
Prisma
Strapi
Unkey
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.