Skip to content

transaction.md

Latest commit

 

History

History
419 lines (268 loc) · 7.8 KB

transaction.md

File metadata and controls

419 lines (268 loc) · 7.8 KB
id Transaction
title Transaction

Class: Transaction<T>

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

Type Parameters

• T extends object = Record<string, unknown>

Constructors

new Transaction()

new Transaction<T>(config): Transaction<T>

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

Parameters

config

TransactionConfig<T>

Returns

Transaction<T>

Properties

autoCommit

autoCommit: boolean;

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

createdAt

createdAt: Date;

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

error?

optional error: object;

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

error

error: Error;

message

message: string;

id

id: string;

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

isPersisted

isPersisted: Deferred<Transaction<T>>;

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

metadata

metadata: Record<string, unknown>;

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

mutationFn

mutationFn: MutationFn<T>;

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

mutations

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

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

sequenceNumber

sequenceNumber: number;

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

state

state: TransactionState;

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

Methods

applyMutations()

applyMutations(mutations): void

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

Parameters

mutations

PendingMutation<any, OperationType, Collection<any, any, any, any, any>>[]

Returns

void

commit()

commit(): Promise<Transaction<T>>

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

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

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

Execute collection operations within this transaction

Parameters

callback

() => void

Function containing collection operations to group together

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

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

rollback()

rollback(config?): Transaction<T>

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

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

Parameters

newState

TransactionState

Returns

void

touchCollection()

touchCollection(): void

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

Returns

void