@groundstate/sync

Pluggable sync engine for real-time and offline collaboration over WebSocket, WebRTC, HTTP, BLE, or filesystem transports.

Installation

# npm
npm install @groundstate/sync

# yarn
yarn add @groundstate/sync

# pnpm
pnpm add @groundstate/sync

Quick Start

import { SyncEngine, WebSocketTransport, PresenceManager } from '@groundstate/sync';
import { Doc, Field } from '@groundstate/crdt';

const doc = Doc({ title: Field('') });

// Connect via WebSocket
const transport = new WebSocketTransport('wss://sync.example.com/room/abc');
const engine = new SyncEngine(doc, transport);

// Track presence
const presence = new PresenceManager(engine);
presence.setLocal({ cursor: { x: 100, y: 200 }, name: 'Alice' });
presence.on('update', (peers) => {
  console.log('Online peers:', peers);
});

// Start syncing
await engine.start();

API Highlights

Protocol

• SyncEngine -- Core sync protocol handling state vectors and op exchange
• SelectiveSync -- Sync only specific document fields or subtrees
• encodeStateVector / decodeStateVector -- State vector serialization
• missingFrom / mergeStateVectors -- Compute delta between peers

Transports

• WebSocketTransport -- Persistent connection for real-time sync
• WebRTCTransport -- Peer-to-peer sync with no server required
• HttpTransport -- Polling-based sync for serverless environments
• BLETransport -- Bluetooth Low Energy for nearby device sync
• FilesystemTransport -- Sync via shared filesystem (e.g., Dropbox)

Presence & Status

• PresenceManager -- Share ephemeral state (cursors, selections, names)
• SyncStatusTracker -- Monitor connection state and sync progress
• SyncThrottle -- Rate-limit sync messages with bandwidth awareness

Auth & Access Control

• AuthManager -- Pluggable authentication for sync connections
• jwtAuthHandler -- Built-in JWT authentication handler
• ACLManager -- Path-based access control rules (read/write/admin)
• OpValidator -- Validate incoming operations against schema and ACL

Server

• RelayServer -- Lightweight relay server for WebSocket-based sync

Documentation

See the full documentation for complete API reference.

License

MIT