@nolag/sync

@nolag/sync

Real-time data sync SDK for NoLag — document CRUD, conflict resolution, and version tracking.

How It Works with NoLag

NoLag is a real-time messaging platform that handles WebSocket connections, message routing, persistence, and scaling. This SDK wraps the low-level @nolag/js-sdk and gives you a purpose-built sync API — create, update, and delete documents across clients with automatic conflict detection and version tracking — without managing topics or subscriptions yourself.

Getting Your Token

1. Sign up at nolag.app
2. Create a new project in the portal
3. Choose the Sync blueprint when creating an app — this pre-configures the changes topic and settings your sync system needs
4. Go to the app's Tokens page and generate an actor token
5. Use that token when connecting with this SDK

Each token identifies a unique collaborator (actor) in NoLag. The blueprint handles all the infrastructure setup — you just build your app.

Install

npm install @nolag/js-sdk @nolag/sync

Quick Start

import { NoLagSync } from "@nolag/sync";

const sync = new NoLagSync("YOUR_ACTOR_TOKEN", {
  username: "Alice",
});

await sync.connect();

const collection = sync.joinCollection("tasks");

// Create a document
collection.createDocument("task-1", {
  title: "Ship feature",
  status: "in-progress",
  assignee: "Alice",
});

// Update a document
collection.updateDocument("task-1", { status: "done" });

// Listen for changes from other clients
collection.on("documentCreated", (change) => {
  console.log(`New doc: ${change.documentId}`);
});

collection.on("documentUpdated", (change) => {
  const doc = collection.getDocument(change.documentId);
  console.log(`Updated:`, doc.data);
});

// Handle conflicts
collection.on("conflict", (conflict) => {
  console.log("Conflict on", conflict.documentId);
  // Resolve manually or let last-write-wins
});

API Reference

NoLagSync

Constructor

const sync = new NoLagSync(token: string, options?: NoLagSyncOptions);

Options:

Option	Type	Default	Description
userId	string	auto-generated	Unique user ID
username	string	—	Display name
metadata	Record<string, unknown>	—	Custom data
collections	string[]	—	Auto-join these collections on connect
debug	boolean	false	Enable debug logging
reconnect	boolean	true	Auto-reconnect on disconnect

Methods

Method	Returns	Description
connect()	Promise<void>	Connect to NoLag
disconnect()	void	Disconnect
joinCollection(name)	SyncRoom	Join a collection
leaveCollection(name)	void	Leave a collection
getCollections()	SyncRoom[]	Get all joined collections
getOnlineCollaborators()	SyncCollaborator[]	Get online collaborators

Events

Event	Payload	Description
connected	—	Connected
disconnected	—	Disconnected
reconnected	—	Reconnected
error	Error	Error
collaboratorOnline	SyncCollaborator	Collaborator came online
collaboratorOffline	SyncCollaborator	Collaborator went offline

SyncRoom

Methods

Method	Returns	Description
createDocument(id, data)	SyncDocument	Create a document
updateDocument(id, fields)	SyncDocument | null	Update document fields
deleteDocument(id)	SyncDocument | null	Delete a document
getDocument(id)	SyncDocument | undefined	Get a document
getDocuments()	SyncDocument[]	Get all documents

Events

Event	Payload	Description
documentCreated	SyncChange	Document created
documentUpdated	SyncChange	Document updated
documentDeleted	SyncChange	Document deleted
localChange	SyncChange	Your change confirmed
conflict	SyncConflict	Conflicting changes detected
synced	—	All changes synced
collaboratorJoined	SyncCollaborator	Collaborator joined
collaboratorLeft	SyncCollaborator	Collaborator left
replayStart / replayEnd	—	Document replay

Types

interface SyncDocument {
  id: string;
  data: Record<string, unknown>;
  version: number;
  updatedBy: string;
  updatedAt: number;
  createdAt: number;
  deleted: boolean;
}

interface SyncChange {
  id: string;
  documentId: string;
  type: "create" | "update" | "delete";
  fields?: Record<string, unknown>;
  version: number;
  updatedBy: string;
  timestamp: number;
  optimistic: boolean;
  isReplay: boolean;
}

interface SyncConflict {
  documentId: string;
  localChange: SyncChange;
  remoteChange: SyncChange;
  resolved: boolean;
}

License

MIT