CRDTs

Chapter 01 — The Foundation

Edit anywhere, offline.
Merge in any order. Converge.

A CRDT — Conflict-free Replicated Data Type — is a data structure many replicas can update independently, even while disconnected, then merge automatically with no central coordinator and no conflicts. The guarantee is strong eventual consistency: once every replica has seen the same set of updates, they are byte-for-byte identical — regardless of the order in which those updates arrived.

The Cosmic Connection

Advaita — the many replicas, one reality

Chapter 02 — Why It Works

The merge obeys three laws

The entire guarantee rests on the merge function having three algebraic properties. With all three, the reachable states form a mathematical join-semilattice and convergence is forced — no locks, no consensus, no server arbitrating who wins.

The canonical example — a G-Counter

A grow-only counter keeps one slot per replica; each replica only ever increments its own slot. The value is the sum of slots, and the merge is element-wise max — which is commutative, associative, and idempotent for free:

// A G-Counter: one slot per replica — you only ever increment YOUR slot.
class GCounter {
  constructor(id, peers) {
    this.id = id;
    this.p = {};                 // replicaId → count
    peers.forEach(r => this.p[r] = 0);
  }

  inc() { this.p[this.id]++; }   // local, offline-safe

  value() {                      // sum across all slots
    return Object.values(this.p).reduce((a, b) => a + b, 0);
  }

  // merge = element-wise MAX — commutative, associative, idempotent
  merge(other) {
    for (const r in other.p)
      this.p[r] = Math.max(this.p[r], other.p[r]);
  }
}

Chapter 03 — The Zoo

Two styles, a handful of types

There are two ways to build a CRDT, and a small zoo of standard shapes built on top of them.

The set that survives concurrent edits — an OR-Set

A naive set can't tell "I removed this" from "you re-added it concurrently". An OR-Set tags every add and only tombstones the tags it has actually observed — so add and remove commute:

// OR-Set (Observed-Remove Set): every add carries a unique tag.
// remove() only tombstones the tags it has SEEN — never future ones.
add(elem) {
  this.adds.push({ elem, tag: uid() });   // e.g. "x@3:A"
}

remove(elem) {
  for (const a of this.adds)
    if (a.elem === elem) this.removed.add(a.tag);  // tag-level tombstone
}

// present iff some add-tag is not in 'removed' — so add ⟂ remove
has(elem) {
  return this.adds.some(
    a => a.elem === elem && !this.removed.has(a.tag));
}

Chapter 04 — Live Visualization

Two replicas, one total

A G-Counter on two replicas. Each increments its own slot while offline, so they disagree — then a single merge (element-wise max) converges both to the same total, no matter who counted what.

Chapter 05 — The Convergence Dance

Diverge, exchange, merge, converge

Cheat-sheet — what each type converges on

CRDT vs OT — two roads to multiplayer

Chapter 06 — Deep Dive

The nuances that senior devs know

This is where the surface-level explainers stop. Here's what actually matters when you ship convergent state.

Chapter 07 — Dharma & Convergence

The Karma of the merge

// Each replica acts alone, of its own will…
replicaA.inc();   // your action, recorded only in your slot
replicaB.inc();   // her action, recorded only in hers

// …yet the merge judges no order and loses no act.
a.merge(b);     // === b.merge(a) — commutative: the law is impartial
a.merge(b);     // again? no change — idempotent: nothing counts twice

// all paths reach the one reading. moksha = convergence.

Chapter 08 — Test Yourself

CRDT Trivia

Three questions. No coordination allowed. Your karma is watching.