Synchronize shared state

Before you start: use Mesh SDK v0.28.0 on two connected peers with an established MLS session. The code below extends the quickstart; it does not start a second protocol instance. Use edge sync when several devices need to read and edit the same current state. The SDK merges document changes when replicas communicate. Your application keeps its existing database for records outside that shared scope.

Choose a space

A space is an existing MLS session or group. For a pairwise session, pass the other device’s address as spaceId; each device therefore uses a different address for its side of the same space. For a group, pass its group ID on every member. Start the protocol and establish the encrypted session using the quickstart. The data layer is enabled by default in v0.28.0; it can be explicitly disabled with data.enabled.

Write and read a document

import { DataStore } from '@offline-protocol/mesh-sdk';

const store = new DataStore();

export async function recordInspection(peerAddress: string) {
  await store.mapSet(peerAddress, 'inspection-17', 'checks', 'housing', {
    kind: 'text',
    value: 'checked',
  });
  await store.flush(peerAddress, 'inspection-17');
  return store.docJson(peerAddress, 'inspection-17');
}

flush waits for local persistence and sends the edit to the space; nothing is stored or replicated before it. It does not mean a peer has received the edit. While the user edits, flush on a short throttle (at most about twice a second) and once more when editing stops. Attach a data_changed listener to your OfflineProtocol instance to refresh the UI after a durable change, and read the document again on the receiving device.

Model concurrent edits

Collection	Merge behaviour	Suitable data
Map	Last writer wins per key	Independent checklist fields and settings.
List	Concurrent insertions survive in deterministic order	Shared ordered entries.
Text	Character-level merging	Collaborative notes.
Counter	Increments accumulate	Counts recorded by several devices.

Map values are replaced as a whole. Put fields that must merge independently in separate keys instead of one JSON string. Use one collection type per collection name. Document and collection names are 1 to 128 bytes using letters, digits, ., _ and -. Map keys are 1 to 256 bytes.

Scope replication

setInterest(spaceId, patterns) selects document names or trailing-wildcard prefixes. ['*'] requests all documents; [] requests none. Call setInterest before start(), on every launch; interests are not persisted. From v0.28.0, React Native holds a call made before start() and applies it before the engine’s first exchange, and a refused pattern rejects start(). A narrowing applied after start() does not delete what the first exchange already pulled in. A space accepts at most 32 patterns. This reduces replicated data but is not a substitute for membership authorization: use separate spaces for different access boundaries. deleteDoc evicts this device’s copy; a peer can restore it. removeDoc propagates removal, but a concurrent edit can preserve and restore the document. Use a fresh document name for new content rather than relying on removal as a permanent tombstone.

Verify two different interruptions

Disconnect the backend while keeping peers connected. Edit on one device and observe the other receiving the change.
Disconnect the peer path. Edit different fields on both devices, flush, then reconnect and compare both documents.
Edit the same map key independently and confirm the documented conflict rule.
Restart a device and confirm its persisted state and identity survive.

Convergence does not enforce inventory limits, exclusive assignments or other business invariants. Put those rules in the application and choose an appropriate authority for conflicting decisions. See the DataStore reference for operations and the source-level replication contract for the wire format.

Completion check

Done when: edits replicate with the internet disconnected, and both replicas converge after a peer partition. Continue with production qualification.

Start here

Workflows

Examples and integrations

Operate and ship

Developer portal

Support

Choose a space

Write and read a document

Model concurrent edits

Scope replication

Verify two different interruptions

Completion check

​Choose a space

​Write and read a document

​Model concurrent edits

​Scope replication

​Verify two different interruptions

​Completion check

Choose a space

Write and read a document

Model concurrent edits

Scope replication

Verify two different interruptions

Completion check