Conflict Resolution

Two people edit the same task while offline. One marks it done, the other renames it. When they reconnect, what happens?

Per-field last-writer-wins

GoSync treats every field of every document as its own small register that remembers its value and when it was written. When two versions meet, each field keeps its newest value independently. You don't need updated_at fields; GoSync tracks this for you.

titledone
Original"Draft report"false
Device A (offline)"Final report"
Device B (offline)true
After sync (everywhere)"Final report"true

Both edits survive, because they touched different fields. Only when two devices change the same field does one value win: the later one.

What "later" means: hybrid logical clocks

Device clocks are unreliable. Phones drift, and laptops can be minutes off. GoSync orders writes with a hybrid logical clock (HLC), which combines wall-clock time with a counter:

  • It never goes backwards, even if the device's clock does.
  • A device that has seen a change always orders its next write after it. If you read the title another device just set and then edit it, your edit wins, even if your clock is behind.
  • Each device estimates the server's time when it connects, to correct for clock skew.
  • The server rejects writes stamped more than 5 minutes in its future, so a device with a wrong clock can't win every conflict.
  • Ties are impossible: every timestamp includes a unique device ID.

Guarantees

  • Convergence: every device and the server end up with exactly the same data, regardless of the order changes arrive in, duplicates or retries.
  • No lost offline work: writes made offline are kept in a local outbox (which survives restarts) until the server confirms them.
  • Deletes are writes too: a delete wins over older edits, and a later set revives the document.
  • Long offline periods are safe: deleted documents are eventually cleaned up on the server. A device that was offline the whole time still learns about the delete, and its stale edits can't bring the document back.

Reacting to changes

watch and subscribe fire for local edits, edits from other tabs, and edits merged in from the server, so your UI always shows the merged result:

javascript
db.subscribe('todos', ({ ids }) => {
  console.log('changed:', ids);
});

If the server rejects a write (for example, a permission rule), the device undoes it locally and you're told:

javascript
db.onError((err) => toast.error(err.message));

When last-writer-wins isn't enough

Per-field LWW is ideal for records: tasks, settings, inventory, forms, CRM entries. It isn't designed for two people typing in the same paragraph at the same time, where one person's text would win. For collaborative text editing, use a text CRDT such as Yjs for that field.


Next: API reference โ†’