Transaction

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

Type Parameters

T

T extends object = Record<string, unknown>

Properties

autoCommit

autoCommit: boolean;

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

collections

readonly collections: Set<Collection<any, any, any, any, any>>;

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

Every Collection that has tracked this transaction. Settlement recomputes each of them, including one whose mutations merged away.

createdAt

createdAt: Date;

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

error?

optional error: object;

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

error

error: Error;

message

message: string;

id

id: string;

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

isPersisted

isPersisted: Deferred<Transaction<T>>;

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

Deferred that settles when this transaction settles.

Await when('settled') instead. This legacy 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. An adapter can also register commit work during the mutation function; settlement waits for that work.

Deprecated

Use when('settled') instead. This alias will be removed in the 1.0 RC.

metadata

metadata: Record<string, unknown>;

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

mutationFn

mutationFn: MutationFn<T>;

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

mutations

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

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

sequenceNumber

sequenceNumber: number;

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

state

state: TransactionState;

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

Methods

applyMutations()

applyMutations(mutations): void;

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

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)
• delete + insert → removed if restored, otherwise update
• 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:767

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:847

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:496

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. If this callback throws, its mutations are removed before the error reaches the caller; mutations from earlier successful calls remain.

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.when('settled')

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

Rollback the transaction and any conflicting transactions

Parameters

config?

Configuration for rollback behavior

error?

Error

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.when('settled')
} 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:438

Parameters

newState

TransactionState

Returns

void

touchCollection()

touchCollection(): void;

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

Tell every Collection that tracked this transaction that it changed. A failure in one Collection must not leave the others showing this transaction's settled optimistic state, so each one recomputes before the first error is thrown. A settled transaction then empties its set of tracking Collections. Its mutations still name their Collection.

Returns

void

when()

when(_state): Promise<Transaction<T>>;

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

Wait for this transaction to complete successfully or fail.

The promise resolves with this transaction on success and rejects with the original error on failure (or undefined for a rollback without an error). For non-empty commits, this boundary is the mutation function's completion; it does not inherently prove backend acknowledgement or read-back unless the mutation function or an adapter-registered commit work item waits for it.

Parameters

_state

"settled"

Returns

Promise<Transaction<T>>