Firebase Realtime Database Explained — Structure, Sync, and Real-World Patterns

// This is what your Firebase Realtime Database actually looks like in the console.
// Notice: flat references instead of nested objects. Users and posts are siblings,
// not parent-child. Each user stores post IDs, not full post objects.
{
  "users": {
    "uid_alice": {
      "displayName": "Alice Mbeki",
      "email": "alice@example.com",
      "joinedAt": 1718000000000,
      // Storing only the post KEY here, not the whole post.
      // Reading Alice's profile won't drag down 500 posts.
      "postIds": {
        "-NxK8mQpostA": true,
        "-NxK8mQpostB": true
      }
    },
    "uid_bob": {
      "displayName": "Bob Okafor",
      "email": "bob@example.com",
      "joinedAt": 1718003600000,
      "postIds": {
        "-NxK8mQpostC": true
      }
    }
  },

  "posts": {
    // Firebase push() generates this key. It's time-ordered, so latest is always last.
    "-NxK8mQpostA": {
      "authorId": "uid_alice",       // Reference to /users/uid_alice
      "title": "Getting started with Firebase",
      "body": "Here is what I learned on day one...",
      "publishedAt": 1718000100000,
      "likesCount": 12
    },
    "-NxK8mQpostB": {
      "authorId": "uid_alice",
      "title": "Firebase security rules deep dive",
      "body": "Rules are not just permissions, they are your server...",
      "publishedAt": 1718050000000,
      "likesCount": 47
    },
    "-NxK8mQpostC": {
      "authorId": "uid_bob",
      "title": "Structuring realtime data for scale",
      "body": "Flat is almost always better than nested...",
      "publishedAt": 1718060000000,
      "likesCount": 8
    }
  },

  // Separating like tracking avoids rewriting the entire post on every like.
  // This node only changes when someone likes or unlikes — nothing else reads it.
  "postLikes": {
    "-NxK8mQpostA": {
      "uid_bob": true,
      "uid_carol": true
    },
    "-NxK8mQpostB": {
      "uid_bob": true
    }
  }
}

import { initializeApp } from 'firebase/app';
import {
  getDatabase,
  ref,
  get,
  set,
  push,
  update,
  remove,
  onValue,
  onChildAdded,
  off,
  serverTimestamp
} from 'firebase/database';

// ── SETUP ──────────────────────────────────────────────────────────────────
const firebaseApp = initializeApp({
  apiKey: 'YOUR_API_KEY',
  authDomain: 'your-app.firebaseapp.com',
  databaseURL: 'https://your-app-default-rtdb.firebaseio.com',
  projectId: 'your-app'
});

const database = getDatabase(firebaseApp);

// ── ONE-TIME READ ───────────────────────────────────────────────────────────
// Use get() when you need data once — like prefetching a user profile on login.
async function loadUserProfile(userId) {
  const userRef = ref(database, `users/${userId}`);

  // get() returns a DataSnapshot. It resolves once, then the connection closes.
  const snapshot = await get(userRef);

  if (!snapshot.exists()) {
    console.log('No profile found for user:', userId);
    return null;
  }

  // .val() unpacks the snapshot into a plain JS object.
  const profile = snapshot.val();
  console.log('Loaded profile:', profile);
  return profile;
}

// ── WRITE: set() vs push() ──────────────────────────────────────────────────
// set() OVERWRITES the entire node at the path. Use for known keys like user IDs.
async function createUserProfile(userId, displayName, email) {
  const userRef = ref(database, `users/${userId}`);

  await set(userRef, {
    displayName,
    email,
    joinedAt: Date.now(),
    postIds: {}           // start with empty post list
  });

  console.log(`Profile created for ${displayName}`);
}

// push() generates a unique, time-ordered key for you. Perfect for lists.
async function publishPost(authorId, title, body) {
  const postsRef = ref(database, 'posts');

  // push() returns a reference to the new node BEFORE the write completes.
  const newPostRef = push(postsRef);
  const newPostKey = newPostRef.key; // e.g. "-NxK8mQpostD"

  // update() writes only the specified fields — it does NOT erase siblings.
  // We use it here to write to two places atomically-ish (not truly atomic —
  // see the Gotchas section about transactions).
  const updates = {};
  updates[`posts/${newPostKey}`] = {
    authorId,
    title,
    body,
    publishedAt: Date.now(),
    likesCount: 0
  };
  // Also record this post ID under the author's profile.
  updates[`users/${authorId}/postIds/${newPostKey}`] = true;

  // Passing updates to the ROOT ref writes both paths in one call.
  await update(ref(database), updates);
  console.log('Post published with key:', newPostKey);
  return newPostKey;
}

// ── LIVE LISTENER: onChildAdded for a chat feed ─────────────────────────────
// onChildAdded fires for every existing child on first attach,
// then once more each time a new child is added. Much cheaper than onValue
// for long lists because you never re-process old messages.
function subscribeToChatMessages(roomId, onNewMessage) {
  const messagesRef = ref(database, `chats/${roomId}/messages`);

  // onChildAdded returns an unsubscribe function — STORE IT so you can clean up.
  const unsubscribe = onChildAdded(messagesRef, (snapshot) => {
    const message = snapshot.val();
    const messageKey = snapshot.key;

    console.log(`[${messageKey}] ${message.senderName}: ${message.text}`);
    onNewMessage({ key: messageKey, ...message });
  });

  // Return the unsubscribe so the caller can stop listening when done.
  return unsubscribe;
}

// ── LIVE LISTENER: onValue for a single value ───────────────────────────────
// Good for a live counter or status indicator that changes frequently.
function watchOnlineUserCount(onCountChange) {
  const onlineCountRef = ref(database, 'meta/onlineUserCount');

  const unsubscribe = onValue(onlineCountRef, (snapshot) => {
    const count = snapshot.val() ?? 0;
    console.log('Online users right now:', count);
    onCountChange(count);
  });

  return unsubscribe;
}

// ── CLEANUP EXAMPLE (React-style) ──────────────────────────────────────────
// In a React component you'd do this inside useEffect:
//
// useEffect(() => {
//   const stopListening = subscribeToChatMessages(roomId, setMessages);
//   return () => stopListening();  // fires on unmount — no memory leak
// }, [roomId]);

// ── DELETE ──────────────────────────────────────────────────────────────────
async function deletePost(postKey, authorId) {
  const updates = {};
  updates[`posts/${postKey}`] = null;                          // null = delete in Firebase
  updates[`users/${authorId}/postIds/${postKey}`] = null;      // clean up the reference too
  updates[`postLikes/${postKey}`] = null;                      // remove orphaned likes

  await update(ref(database), updates);
  console.log('Post and all its references deleted:', postKey);
}

// Deploy these rules with: firebase deploy --only database
// Or paste directly into Firebase Console > Realtime Database > Rules
{
  "rules": {

    // ── PUBLIC READ, NO WRITE ─────────────────────────────────────────────
    "products": {
      // Anyone (even unauthenticated visitors) can read the product catalogue.
      ".read": true,

      // Only authenticated admins can add or change products.
      // We store admin status in /admins/{uid} as a boolean.
      ".write": "auth !== null && root.child('admins').child(auth.uid).val() === true"
    },

    // ── OWNER-ONLY WRITE ──────────────────────────────────────────────────
    "users": {
      "$userId": {   // $userId is a wildcard that matches any key under /users/

        // Any logged-in user can read any profile (e.g. to show names in a chat).
        ".read": "auth !== null",

        // Only the profile's owner can write to it.
        ".write": "auth !== null && auth.uid === $userId",

        // Validate the shape of the data being written.
        // newData = what the node WILL contain after this write.
        ".validate": "newData.hasChildren(['displayName', 'email', 'joinedAt'])",

        "displayName": {
          // Must be a string between 2 and 50 characters.
          ".validate": "newData.isString() && newData.val().length >= 2 && newData.val().length <= 50"
        },
        "email": {
          // Must be a string (Firebase Auth already validated the format).
          ".validate": "newData.isString()"
        },
        "joinedAt": {
          // Must be a number (Unix timestamp in ms). Cannot be changed after creation.
          // data.exists() is true only if this field already exists in the DB.
          ".validate": "newData.isNumber() && !data.exists()"
        }
      }
    },

    // ── POSTS — AUTHENTICATED CREATE, OWNER DELETE ────────────────────────
    "posts": {
      // Any logged-in user can read all posts.
      ".read": "auth !== null",

      "$postId": {
        // Creating a post: user must be logged in AND the authorId they're writing
        // must match their own uid — you can't impersonate someone else.
        ".write": "auth !== null && (
                    !data.exists() && newData.child('authorId').val() === auth.uid ||
                    data.exists() && data.child('authorId').val() === auth.uid
                  )",

        ".validate": "newData.hasChildren(['authorId', 'title', 'body', 'publishedAt'])",

        "title": {
          ".validate": "newData.isString() && newData.val().length > 0 && newData.val().length <= 200"
        },
        "body": {
          ".validate": "newData.isString() && newData.val().length > 0"
        },
        "likesCount": {
          // Must be a non-negative integer.
          ".validate": "newData.isNumber() && newData.val() >= 0"
        }
      }
    },

    // ── DENY EVERYTHING ELSE ──────────────────────────────────────────────
    // Firebase's default is deny. You don't need to explicitly write this,
    // but being explicit makes your intent clear to future maintainers.
    "$other": {
      ".read": false,
      ".write": false
    }
  }
}

import {
  getDatabase,
  ref,
  runTransaction,
  onDisconnect,
  set,
  serverTimestamp,
  onValue
} from 'firebase/database';

const database = getDatabase();

// ── TRANSACTION: Safe like counter ──────────────────────────────────────────
// This guarantees correctness even if 1000 users like the post simultaneously.
async function togglePostLike(postId, currentUserId) {
  const likesCountRef = ref(database, `posts/${postId}/likesCount`);
  const userLikeRef  = ref(database, `postLikes/${postId}/${currentUserId}`);

  // First, check if this user already liked it (one-time read).
  const { get } = await import('firebase/database');
  const alreadyLiked = (await get(userLikeRef)).exists();

  // runTransaction receives the CURRENT value from the server.
  // If two clients run this at the same instant, Firebase serialises them.
  const { committed, snapshot } = await runTransaction(likesCountRef, (currentCount) => {
    if (currentCount === null) return 0; // handle uninitialised node

    // Return the new value you want to write.
    return alreadyLiked ? currentCount - 1 : currentCount + 1;
  });

  if (committed) {
    // Now update the postLikes index to reflect the change.
    await set(userLikeRef, alreadyLiked ? null : true);
    console.log(`Like ${alreadyLiked ? 'removed' : 'added'}. New count: ${snapshot.val()}`);
  } else {
    console.warn('Transaction aborted — another write won the race, Firebase will retry.');
  }
}

// ── PRESENCE SYSTEM: Know who's online right now ────────────────────────────
// onDisconnect() tells the server what to write when THIS client disconnects.
// This is one of Firebase RTDB's killer features — impossible to replicate
// cheaply with REST APIs.
async function registerUserPresence(userId, displayName) {
  const userPresenceRef = ref(database, `presence/${userId}`);

  // Tell the server: if I disconnect for any reason (browser close, network drop,
  // app crash), delete my presence entry automatically.
  await onDisconnect(userPresenceRef).remove();

  // Now write the 'I am online' marker. The onDisconnect handler is registered
  // server-side first, so even if the network dies between these two lines,
  // the cleanup will still fire.
  await set(userPresenceRef, {
    displayName,
    onlineSince: serverTimestamp(), // server fills this in, not the client clock
    status: 'online'
  });

  console.log(`${displayName} is now marked as online.`);
}

// ── WATCHING THE ONLINE USERS LIST ─────────────────────────────────────────
function watchOnlineUsers(onUpdate) {
  const presenceRef = ref(database, 'presence');

  const unsubscribe = onValue(presenceRef, (snapshot) => {
    const presenceData = snapshot.val() ?? {};

    // Convert the object into an array for easier rendering.
    const onlineUsers = Object.entries(presenceData).map(([uid, info]) => ({
      uid,
      ...info
    }));

    console.log(`${onlineUsers.length} user(s) currently online:`);
    onlineUsers.forEach(u => console.log(`  - ${u.displayName} (since ${new Date(u.onlineSince).toLocaleTimeString()})`))

    onUpdate(onlineUsers);
  });

  return unsubscribe;
}

// ── SIMULATED USAGE ─────────────────────────────────────────────────────────
// In a real app these would be called from auth state listeners and component lifecycle.
registerUserPresence('uid_alice', 'Alice Mbeki');
registerUserPresence('uid_bob', 'Bob Okafor');
watchOnlineUsers((users) => { /* update UI */ });
togglePostLike('-NxK8mQpostA', 'uid_bob');