@rajeev02/sync

Offline-first sync engine with CRDT-based conflict resolution, Hybrid Logical Clock causal ordering, persistent operation log, and multi-device convergence.

Powered by a Rust core (rajeev-sync-core) compiled to native (iOS/Android via UniFFI) and WASM (Web).

Platform Support

| Platform | Engine | Binding | | -------------------- | ------------ | --------------- | | iOS 16+ | Rust → UniFFI | Swift | | Android 7+ (API 24) | Rust → UniFFI | Kotlin | | Web | Rust → WASM | wasm-bindgen | | watchOS 9+ / Wear OS | Rust → UniFFI | Native | | Android Auto | Rust → UniFFI | Kotlin |

Installation

npm install @rajeev02/sync

Quick Start

import { SyncStorage } from '@rajeev02/sync';

// Each device gets a unique node ID
const storage = new SyncStorage(':memory:', 'device-phone-01');

// Insert documents
const docId = storage.insert('tasks', JSON.stringify({
  title: 'Buy groceries',
  done: false,
}));

// Update fields
storage.update('tasks', docId, 'done', 'true');

// Query
const tasks = storage.query('tasks', 10);

// Get unsynced operations for server push
const ops = storage.getUnsyncedOps(100);

// After server confirms receipt
storage.markSynced(ops.map(op => op.id));

CRDT Documents

import { CrdtDocument, lwwMerge, HLC } from '@rajeev02/sync';

// Create documents on two devices
const docA = CrdtDocument.create('doc-001', 'tasks', 'device-A');
const docB = CrdtDocument.create('doc-001', 'tasks', 'device-B');

// Both edit the same field
docA.setField('title', 'Buy pasta');
docB.setField('title', 'Buy rice');

// Merge — later HLC wins deterministically
docA.merge(docB);
docB.merge(docA);
// Both converge to the same value ✅

API Reference

| Method | Description | |--------|-------------| | SyncStorage(dbPath, nodeId) | Create sync storage instance | | insert(collection, dataJson) | Insert document, returns UUID | | update(collection, docId, field, value) | Update single field | | delete(collection, docId) | Soft-delete document | | get(collection, docId) | Get document as JSON | | query(collection, limit) | Query documents in collection | | getUnsyncedOps(limit) | Get unsynced ops for server push | | markSynced(opIds) | Mark ops as synced | | purgeOldOps(hours) | Remove old synced ops | | getStats() | Storage statistics | | CrdtDocument.create(id, collection, nodeId) | Create CRDT document | | HLC(nodeId) | Create Hybrid Logical Clock | | compareHLC(a, b) | Compare two HLC timestamps | | lwwMerge(local, remote) | Last-Writer-Wins merge |

License

MIT © Rajeev Kumar Joshi