Interface: Transaction<T>#
Defined in: packages/db/src/transactions.ts:208
Type Parameters#
T#
T extends object = Record<string, unknown>
Properties#
autoCommit#
autoCommit: boolean;
Defined in: packages/db/src/transactions.ts:214
createdAt#
createdAt: Date;
Defined in: packages/db/src/transactions.ts:215
error?#
optional error: object;
Defined in: packages/db/src/transactions.ts:218
error#
error: Error;
message#
message: string;
id#
id: string;
Defined in: packages/db/src/transactions.ts:209
isPersisted#
isPersisted: Deferred<Transaction<T>>;
Defined in: packages/db/src/transactions.ts:213
metadata#
metadata: Record<string, unknown>;
Defined in: packages/db/src/transactions.ts:217
mutationFn#
mutationFn: MutationFn<T>;
Defined in: packages/db/src/transactions.ts:211
mutations#
mutations: PendingMutation<T, OperationType, Collection<T, any, any, any, any>>[];
Defined in: packages/db/src/transactions.ts:212
sequenceNumber#
sequenceNumber: number;
Defined in: packages/db/src/transactions.ts:216
state#
state: TransactionState;
Defined in: packages/db/src/transactions.ts:210
Methods#
applyMutations()#
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()#
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#
// 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: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()#
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#
// 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:389
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:238
Parameters#
newState#
Returns#
void
touchCollection()#
touchCollection(): void;
Defined in: packages/db/src/transactions.ts:417
Returns#
void