Transaction

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

Type Parameters#

T#

T extends object = Record<string, unknown>

Properties#

autoCommit#

autoCommit: boolean;

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

collections#

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

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

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

error?#

optional error: object;

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

error#

error: Error;

message#

message: string;

id#

id: string;

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

metadata#

metadata: Record<string, unknown>;

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

mutationFn#

mutationFn: MutationFn<T>;

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

mutations#

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

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

sequenceNumber#

sequenceNumber: number;

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

state#

state: TransactionState;

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

Methods#

applyMutations()#

applyMutations(mutations): void;

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

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

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

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

completeWithoutCommit()#

completeWithoutCommit(): void;

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

Internal

Complete a transaction whose work was already applied outside commit().

Returns#

void

mutate()#

mutate(callback): Transaction<T>;

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

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

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

Parameters#

newState#

TransactionState

Returns#

void

touchCollection()#

touchCollection(releasedHold): void;

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

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.

Parameters#

releasedHold#

boolean = false

Returns#

void

when()#

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

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

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