Increment, arrayUnion / arrayRemove, Server Timestamp, Compare / Precondition Patterns, and Conflict Reduction

Learning outcomes

1. The AtlasMart problem: stop doing read → modify → write for simple field math

An analytics worker wants to add one view to catalogItems/p-1001.viewCount. If ten workers each read 100, compute 101, and write 101, nine increments are lost. The application never needed the old value for a business decision; it only needed an atomic “add one.” A field transform lets the backend apply that operation at commit time.

2. Atomic transforms remove one race—but only the race they express

import { doc, updateDoc, increment, arrayUnion, arrayRemove, serverTimestamp } from "firebase/firestore";const ref=doc(db,"profiles",user.uid);await updateDoc(ref, {  loginCount: increment(1),  favoriteSkus: arrayUnion("P-1001"),  updatedAt: serverTimestamp()});await updateDoc(ref, { favoriteSkus: arrayRemove("P-0007") });

These transforms are part of a single document write and do not require your application to read the prior values. That shortens the race window and usually reduces reads. But increment(-1) on stock is not a substitute for “decrement only if stock is positive.” The transform knows arithmetic, not your invariant.

3. Compare-and-set with a server precondition

Trusted Node/server clients expose document-version preconditions. AtlasMart can read a product snapshot, present a review screen to an operator, then update only if the document has not changed since that read. This is useful for explicit compare-and-set workflows that do not need a whole transaction callback.

const ref = db.doc("catalogItems/p-1001");const snap = await ref.get();if (!snap.exists) throw new Error("missing-product");const expected = snap.updateTime;try {  await ref.update(    { moderationState: "approved", moderatedAt: FieldValue.serverTimestamp() },    { lastUpdateTime: expected }  );  console.log("compare-and-set committed");} catch (error) {  console.log("precondition failed or other write error", error.code);}

For create-if-absent on the server, DocumentReference.create() provides an existence precondition. Browser/mobile APIs do not expose the same generic lastUpdateTime write-precondition surface; their transaction implementation uses version preconditions internally. When an untrusted client needs a conditional decision based on current data, use a transaction plus Security Rules rather than inventing a client-only compare-and-set token.

4. Server timestamp is authoritative for the Firestore commit, not for the universe

serverTimestamp() avoids trusting a client clock. It represents a server-generated timestamp resolved when the write commits. That is useful for updatedAt, ordering within Firestore data and audit metadata. It does not prove an external payment happened at exactly the same instant, nor does it make two separate systems one transaction.

5. Arrays are convenient, not an unbounded relationship store

arrayUnion and arrayRemove are useful for bounded profile preferences or tags. They are a poor fit for “all order IDs ever placed by this customer” or a million followers. Large arrays increase document size and index-entry fan-out and create a shared hot document. Use subcollections/root collections for growing relationships.

// Anti-pattern for a high-volume order history:await updateDoc(doc(db,"profiles",uid), {  everyOrderIdEver: arrayUnion(newOrderId)});// Better model: orders/{orderId} with customerId, or profiles/{uid}/orders/{orderId}.

6. Conflict-reduction decision table

7. Reproducible AtlasMart lab

{  "name": "atlasmart-firestore-ch09",  "private": true,  "type": "module",  "engines": { "node": ">=22" },  "dependencies": {    "firebase-admin": "14.4.0"  },  "devDependencies": {    "firebase-tools": "15.30.0"  }}

{  "firestore": {    "rules": "firestore.rules",    "indexes": "firestore.indexes.json"  },  "emulators": {    "firestore": { "port": 8080 },    "auth": { "port": 9099 },    "ui": { "enabled": true, "port": 4000 }  }}

rules_version = '2';service cloud.firestore {  match /databases/{database}/documents {    match /catalogItems/{productId} { allow read: if true; allow write: if false; }    match /profiles/{uid} { allow read, write: if request.auth != null && request.auth.uid == uid; }    match /orders/{orderId} { allow read: if request.auth != null && resource.data.customerId == request.auth.uid; allow write: if false; }    match /{document=**} { allow read, write: if false; }  }}

mkdir atlasmart-firestore-ch09 && cd atlasmart-firestore-ch09npm init -ynpm install firebase-admin@14.4.0npm install --save-dev firebase-tools@15.30.0# Save firebase.json, firestore.rules and firestore.indexes.json from this lesson.printf '{"indexes":[],"fieldOverrides":[]}' > firestore.indexes.jsonnpx firebase-tools@15.30.0 emulators:start --project demo-atlasmart-firestore --only firestore,auth

const ref=db.doc("metrics/catalog");await ref.set({views:0,labels:[],schemaVersion:1});// Launch independent atomic increments.await Promise.all(Array.from({length:50},()=>ref.update({views:FieldValue.increment(1)})));console.log("atomic increment result", (await ref.get()).get("views"));// Demonstrate version precondition failure deterministically.const before=await ref.get();await ref.update({noise:FieldValue.increment(1)}); // changes updateTimetry {  await ref.update({reviewed:true},{lastUpdateTime:before.updateTime});  throw new Error("unexpected-precondition-success");} catch (e) {  console.log("expected stale precondition", e.code);}

The expected logical evidence is views=50 after fifty successful atomic increments and a rejected stale precondition after the intervening update. Exact error strings can vary by emulator/client version; assert the failure class/state rather than hard-coding prose.

Production judgment

Prefer transforms when the operation itself fully expresses the desired state transition. Prefer preconditions when one document must still be the exact version you inspected. Prefer transactions when correctness depends on fresh values across one or more documents. None of these primitives cures an inherently hot key; Lesson 4 spreads write pressure across shards while preserving idempotency at the application level.

Knowledge check

1. Why can increment avoid lost updates?
2. Does increment(-1) prevent negative stock?
3. What does a lastUpdateTime precondition prove?
4. Why is arrayUnion unsuitable for unbounded order history?
5. What does serverTimestamp establish?

Summary and next step

Transforms and preconditions shrink conflict surfaces by expressing updates directly. When one logical value is still written far too frequently, the next step is not “retry harder”; it is to distribute the write load.

Authoritative references

• Transactions and batched writes — atomicity, retry rules, offline boundary, batch behavior and failure conditions.
• Transaction serializability and isolation — Standard/Enterprise concurrency defaults, mobile/web optimistic emulation, server locking and contention errors.
• Usage and limits — transaction time/request/field-transform and Security Rules access-call limits.
• Distributed counters — shard-based write distribution and read/cost tradeoffs.
• Firestore best practices — hotspot, transaction size and scale guidance.
• Enterprise Native Core/Pipeline overview — operation-family boundaries.
• Pipeline DML — Preview update/delete semantics and non-transactional partial-success boundary.
• Firebase JavaScript SDK release notes — 12.19.0 baseline.
• Firebase Admin Node.js release notes — 14.4.0, @google-cloud/firestore 9.1.0 and Node.js 22+ baseline.
• Firebase CLI release notes — 15.30.0 baseline.