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.
title | done | |
|---|---|---|
| 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
setrevives 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:
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:
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 โ