How to Perform Transactions in Firestore

1import { getFirestore, doc, runTransaction } from 'firebase/firestore'
2
3const db = getFirestore()
4
5// Atomically increment a counter
6async function incrementCounter(counterId: string) {
7  const counterRef = doc(db, 'counters', counterId)
8
9  const newCount = await runTransaction(db, async (transaction) => {
10    // Step 1: Read the current value
11    const counterDoc = await transaction.get(counterRef)
12    if (!counterDoc.exists()) {
13      throw new Error('Counter document does not exist')
14    }
15
16    // Step 2: Calculate the new value
17    const currentCount = counterDoc.data().count
18    const updatedCount = currentCount + 1
19
20    // Step 3: Write the new value
21    transaction.update(counterRef, { count: updatedCount })
22
23    return updatedCount
24  })
25
26  console.log('Counter updated to:', newCount)
27  return newCount
28}

1async function transferCredits(
2  fromUserId: string,
3  toUserId: string,
4  amount: number
5) {
6  const fromRef = doc(db, 'users', fromUserId)
7  const toRef = doc(db, 'users', toUserId)
8
9  await runTransaction(db, async (transaction) => {
10    // Read both documents first
11    const fromDoc = await transaction.get(fromRef)
12    const toDoc = await transaction.get(toRef)
13
14    if (!fromDoc.exists() || !toDoc.exists()) {
15      throw new Error('One or both users do not exist')
16    }
17
18    const fromBalance = fromDoc.data().credits
19    if (fromBalance < amount) {
20      throw new Error(`Insufficient credits: has ${fromBalance}, needs ${amount}`)
21    }
22
23    // Write both updates
24    transaction.update(fromRef, { credits: fromBalance - amount })
25    transaction.update(toRef, { credits: toDoc.data().credits + amount })
26  })
27
28  console.log(`Transferred ${amount} credits from ${fromUserId} to ${toUserId}`)
29}

1async function safeTransfer(
2  fromId: string,
3  toId: string,
4  amount: number
5) {
6  try {
7    await transferCredits(fromId, toId, amount)
8    return { success: true }
9  } catch (error: any) {
10    if (error.message.includes('Insufficient credits')) {
11      // Business logic error — do not retry
12      return { success: false, reason: 'insufficient_balance' }
13    }
14    if (error.code === 'failed-precondition') {
15      // Transaction failed after max retries due to contention
16      return { success: false, reason: 'too_much_contention' }
17    }
18    if (error.code === 'unavailable') {
19      // Client is offline — transactions require connectivity
20      return { success: false, reason: 'offline' }
21    }
22    throw error // Unknown error
23  }
24}

1import { writeBatch, doc, serverTimestamp } from 'firebase/firestore'
2
3// Batch write: atomic writes WITHOUT reads
4async function publishPost(postId: string, tags: string[]) {
5  const batch = writeBatch(db)
6
7  // Update the post status
8  batch.update(doc(db, 'posts', postId), {
9    status: 'published',
10    publishedAt: serverTimestamp(),
11  })
12
13  // Create tag documents
14  for (const tag of tags) {
15    batch.set(doc(db, 'tags', tag), {
16      name: tag,
17      lastUsed: serverTimestamp(),
18    }, { merge: true })
19  }
20
21  // All writes succeed or all fail
22  await batch.commit()
23}
24
25// Transaction: atomic read-then-write
26// Use when the write depends on current values
27// Example: incrementing a counter, transferring balance
28
29// Batch: atomic writes only
30// Use when you already know what to write
31// Example: publishing a post + updating tags

1// Cloud Function using Admin SDK transaction
2import { getFirestore } from 'firebase-admin/firestore'
3
4const db = getFirestore()
5
6export async function processOrder(orderId: string) {
7  const orderRef = db.doc(`orders/${orderId}`)
8  const inventoryRef = db.doc(`products/${orderId}`)
9
10  await db.runTransaction(async (transaction) => {
11    const orderDoc = await transaction.get(orderRef)
12    const inventoryDoc = await transaction.get(inventoryRef)
13
14    if (!orderDoc.exists || !inventoryDoc.exists) {
15      throw new Error('Order or product not found')
16    }
17
18    const quantity = orderDoc.data()!.quantity
19    const stock = inventoryDoc.data()!.stock
20
21    if (stock < quantity) {
22      throw new Error('Insufficient stock')
23    }
24
25    transaction.update(inventoryRef, { stock: stock - quantity })
26    transaction.update(orderRef, { status: 'confirmed' })
27  }, { maxAttempts: 5 })
28}