Snapshot Metadata, Pending Writes, Cache vs Server Sources, and User-Experience Semantics

Learning outcomes

1. AtlasMart problem: the green “Saved” badge lies

An AtlasMart customer edits an order note while the network is unavailable. The UI updates instantly and displays “Saved.” That is a product bug: the SDK has accepted a local write, but the backend has not yet acknowledged it. Realtime metadata exists precisely so the UI can distinguish optimistic local state from server-confirmed state.

2. Metadata changes are events only when you ask for them

By default, a listener does not fire merely because metadata changed. If the document data remains the same but hasPendingWrites flips from true to false, or fromCache flips as the client catches up with the server, use { includeMetadataChanges:true }. The same option can be passed to docChanges() when interpreting query-level change details.

import { initializeApp } from "https://www.gstatic.com/firebasejs/12.19.0/firebase-app.js";import { getAuth, connectAuthEmulator, signInAnonymously } from "https://www.gstatic.com/firebasejs/12.19.0/firebase-auth.js";import {  getFirestore, connectFirestoreEmulator, collection, doc, query, where, orderBy, limit,  onSnapshot, setDoc, updateDoc, serverTimestamp, disableNetwork, enableNetwork} from "https://www.gstatic.com/firebasejs/12.19.0/firebase-firestore.js";const app = initializeApp({ projectId:"demo-atlasmart-firestore", apiKey:"demo-key", appId:"demo-app" });const db = getFirestore(app); connectFirestoreEmulator(db, "127.0.0.1", 8080);const auth = getAuth(app); connectAuthEmulator(auth, "http://127.0.0.1:9099", { disableWarnings:true });const credential = await signInAnonymously(auth);const uid = credential.user.uid;console.log("uid", uid);const ref = doc(db, `profiles/${uid}/orders/o-meta-1`);await setDoc(ref, { status:"created", customerNote:"", clientTouchedAt:serverTimestamp() });let seq = 0;const stop = onSnapshot(ref, { includeMetadataChanges:true }, snap => {  const m = snap.metadata;  const ux = m.hasPendingWrites ? "saving" : (m.fromCache ? "cached" : "synced");  console.log(JSON.stringify({ seq:++seq, at:performance.now().toFixed(1), ux, fromCache:m.fromCache, pending:m.hasPendingWrites, data:snap.data() }));});await disableNetwork(db);await updateDoc(ref, { customerNote:"ring once", clientTouchedAt:serverTimestamp() });await new Promise(r => setTimeout(r,1000));await enableNetwork(db);// Observe until pending=false; exact callback count/timing is intentionally not asserted.window.stopMeta = stop;

3. What fromCache does—and does not—mean

fromCache=true means the snapshot was produced from cached data rather than guaranteed up-to-date server data. It may be perfectly correct and recent; it may also be stale or incomplete relative to current server state. fromCache=false means the listener has caught up with the backend for its query at that point. Neither flag says who is authorized—that is still enforced by Rules/IAM—and neither replaces application-level versioning for business workflows.

In a cold browser with the default Web memory cache, the first online callback can come from the server without an observable cache-first phase. In a client with persistent cached state, a cache snapshot can arrive first. Therefore test invariants, not a hard-coded “exactly two callbacks” sequence.

4. User-experience state machine

START  -> LOADING: no snapshot yet  -> CACHED: snapshot.fromCache && !snapshot.hasPendingWrites  -> SAVING_OFFLINE_OR_PENDING: snapshot.hasPendingWrites  -> SYNCED: !snapshot.fromCache && !snapshot.hasPendingWrites  -> ERROR: listener error callback fired; stop presenting the stream as liveUI rule: never label "server saved" solely because document data changed locally.

A production screen may add a separate connectivity indicator, but network reachability and Firestore synchronization are not identical. A browser can be “online” while authentication, Rules, or backend access fails. Use the listener/error metadata you actually have.

5. Cache/server source selection

The current Web API exposes listener source controls in SnapshotListenOptions; the default listens using both cache and server behavior. A cache-only listen can be useful for explicitly local UI, but it cannot become server-current by magic. Keep source choice in the screen contract: if checkout requires server-confirmed stock, a cache-only view is not authoritative enough.

6. Controlled failure injection

1. Start the emulator and listener.
2. Disable Firestore networking via SDK; edit the customer note; verify a pending snapshot.
3. Re-enable networking; verify the write is eventually acknowledged or rejected.
4. Temporarily change Rules to deny the client update, restart/import a clean emulator state, and repeat. Verify that optimistic local state does not become permanent server state and that the application reports the error.
5. Restore Rules and reset the emulator. Do not carry altered Rules into later exercises.

Production judgment

Metadata-aware UX prevents false claims of durability, but it also introduces state complexity. Log state transitions with correlation/session IDs rather than every raw snapshot in production. Track “time pending,” terminal error codes, and reconnect frequency. Sensitive screens should disclose cached/offline state where stale values could mislead decisions.

Knowledge check

1. Does hasPendingWrites=false imply fromCache=false?
2. Why enable includeMetadataChanges?
3. Can a fromCache=true snapshot still be useful?
4. Why should tests avoid asserting an exact number of metadata callbacks?
5. Is synchronization metadata a substitute for business workflow status?

Summary and next step

Metadata lets the UI tell the truth about optimistic, cached, and server-current state. Lesson 3 scales the same mechanics across many clients and examines fan-out, reconnect billing, query selectivity, and bandwidth.

Authoritative references

• Get realtime updates with Cloud Firestore — document/query listeners, initial snapshots, docChanges(), detach/error behavior.
• Access data offline — cache behavior, fromCache, metadata-change events, network transitions.
• JavaScript SnapshotMetadata — hasPendingWrites and fromCache semantics.
• JavaScript SnapshotListenOptions — metadata updates and listen-source options.
• Understand Cloud Firestore billing — Standard listener reads, reconnect charging, index-entry reads, Rules-dependent reads, and bandwidth.
• Firestore Enterprise pricing — initial read units and separate realtime-update units.
• Enterprise Core realtime listeners — Core listener support and Pipeline listener boundary.
• Enterprise Native Core/Pipeline overview — Core realtime/offline support versus Pipeline query operations.
• MongoDB-compatibility change streams — separate Preview change-stream model; do not equate it with Web SDK onSnapshot.
• Firebase release notes — current CLI/SDK versions used by this lab.