TypeScript Client

npm install @grove-js/crdt

npm install react

// Core: client, store, merge, clock, stream, presence
import { CRDTClient, CRDTStore, HybridClock, PresenceManager } from "@grove-js/crdt";

// Plugin interfaces (for custom implementations)
import type { Transport, StreamTransport, AuthProvider, StorageAdapter } from "@grove-js/crdt";

// React hooks
import {
    CRDTProvider, useDocument, useCollection,
    usePresence, useDocumentPresence,
} from "@grove-js/crdt/react";

import { CRDTClient } from "@grove-js/crdt";

const client = new CRDTClient({
    baseURL: "https://api.example.com/sync",
    nodeID: "browser-1",
    tables: ["documents", "comments"],
    headers: {
        Authorization: "Bearer <token>",
    },
});

// Pull changes from the server.
const { changes, latestHLC } = await client.pull();

// Push local changes to the server.
const pushResult = await client.push(pendingChanges);

// Create an SSE stream instance.
const stream = client.stream({ reconnectDelay: 5000 });

interface Transport {
    pull(req: PullRequest): Promise<PullResponse>;
    push(req: PushRequest): Promise<PushResponse>;
    updatePresence?(update: PresenceUpdate): Promise<void>;  // Optional
    getPresence?(topic: string): Promise<PresenceState[]>;   // Optional
}

import type { Transport } from "@grove-js/crdt";

const wsTransport: Transport = {
    async pull(req) { /* ... send via WebSocket ... */ },
    async push(req) { /* ... send via WebSocket ... */ },
};

const client = new CRDTClient({
    nodeID: "browser-1",
    transport: wsTransport,
});

interface StreamTransport extends Transport {
    subscribe(config: StreamConfig): StreamSubscription;
}

interface AuthProvider {
    getHeaders(): Record<string, string> | Promise<Record<string, string>>;
}

// Built-in static implementation
import { StaticAuthProvider } from "@grove-js/crdt";
const auth = new StaticAuthProvider({ Authorization: "Bearer <token>" });

// Custom JWT refresh
const jwtAuth: AuthProvider = {
    async getHeaders() {
        const token = await refreshTokenIfNeeded();
        return { Authorization: `Bearer ${token}` };
    },
};

const client = new CRDTClient({
    baseURL: "/api/sync",
    nodeID: "browser-1",
    auth: jwtAuth,
});

interface StorageAdapter {
    loadState(): Promise<Map<string, Map<string, DocumentState>>>;
    saveDocument(table: string, pk: string, doc: DocumentState): Promise<void>;
    deleteDocument(table: string, pk: string): Promise<void>;
    loadPendingChanges(): Promise<ChangeRecord[]>;
    savePendingChanges(changes: ChangeRecord[]): Promise<void>;
}

import { CRDTStore, HybridClock } from "@grove-js/crdt";

const clock = new HybridClock("browser-1");
const store = new CRDTStore("browser-1", clock);

// Apply remote changes from a pull.
store.applyChanges(changes);

// Read a document.
const doc = store.getDocument<Document>("documents", "doc-1");
// { id: "doc-1", title: "Hello", viewCount: 42, tags: ["go", "crdt"] }

// Read a collection.
const docs = store.getCollection<Document>("documents");

// Make local changes.
store.setField("documents", "doc-1", "title", "Updated Title");
store.incrementCounter("documents", "doc-1", "viewCount", 1);
store.addToSet("documents", "doc-1", "tags", "typescript");

// Get pending changes for push.
const pending = store.getPendingChanges();
await client.push(pending);
store.clearPendingChanges();

// Subscribe to all changes.
const unsub = store.subscribe(() => {
    console.log("State changed");
});

// Subscribe to a specific document.
const unsub = store.subscribeDocument("documents", "doc-1", () => {
    console.log("Document changed");
});

// Subscribe to an entire table.
const unsub = store.subscribeCollection("documents", () => {
    console.log("Collection changed");
});

import { mergeLWW, mergeCounter, counterValue, mergeSet, setElements } from "@grove-js/crdt";

// LWW merge: higher HLC wins.
const winner = mergeLWW(localValue, remoteValue);

// Counter merge: per-node max.
const merged = mergeCounter(localCounter, remoteCounter);
const value = counterValue(merged); // sum(inc) - sum(dec)

// Set merge: add-wins union.
const mergedSet = mergeSet(localSet, remoteSet);
const elements = setElements(mergedSet); // active elements

import { HybridClock, hlcCompare, hlcAfter } from "@grove-js/crdt";

const clock = new HybridClock("browser-1");

// Generate a new HLC.
const hlc = clock.now();
// { ts: 1706000000000000000, c: 0, node: "browser-1" }

// Update from a remote HLC.
clock.update(remoteHLC);

// Compare two HLCs.
const cmp = hlcCompare(a, b); // -1, 0, or 1
const isAfter = hlcAfter(a, b); // boolean

import { CRDTStream } from "@grove-js/crdt";

const stream = new CRDTStream(
    "https://api.example.com/sync",
    { tables: ["documents"], reconnectDelay: 5000 },
    { Authorization: "Bearer <token>" }
);

stream.on((event) => {
    if (event.type === "change") {
        store.applyChanges([event.data]);
    } else if (event.type === "changes") {
        store.applyChanges(event.data);
    }
});

stream.connect();

import {
    CRDTProvider,
    useDocument,
    useCollection,
    useLWW,
    useCounter,
    useSet,
    useSyncStatus,
    useStream,
} from "@grove-js/crdt/react";

function App() {
    return (
        <CRDTProvider config={{
            baseURL: "https://api.example.com/sync",
            nodeID: "browser-1",
            tables: ["documents"],
            headers: { Authorization: "Bearer <token>" },
        }}>
            <DocumentList />
        </CRDTProvider>
    );
}

function DocumentEditor({ id }: { id: string }) {
    const { data, loading, update, remove } = useDocument<Document>("documents", id);

    if (loading) return <div>Loading...</div>;
    if (!data) return <div>Not found</div>;

    return (
        <div>
            <input
                value={data.title}
                onChange={(e) => update("title", e.target.value)}
            />
            <button onClick={remove}>Delete</button>
        </div>
    );
}

function DocumentList() {
    const { items, loading, create } = useCollection<Document>("documents");

    return (
        <div>
            {items.map((doc) => (
                <DocumentEditor key={doc.id} id={doc.id} />
            ))}
            <button onClick={() => create("new-id", { title: "Untitled" })}>
                New Document
            </button>
        </div>
    );
}

function TitleEditor({ docId }: { docId: string }) {
    const { value, set } = useLWW<string>("documents", docId, "title");

    return (
        <input value={value ?? ""} onChange={(e) => set(e.target.value)} />
    );
}

function ViewCounter({ docId }: { docId: string }) {
    const { value, increment } = useCounter("documents", docId, "viewCount");

    return (
        <div>
            <span>Views: {value}</span>
            <button onClick={() => increment(1)}>+1</button>
        </div>
    );
}

function TagEditor({ docId }: { docId: string }) {
    const { elements, add, remove, has } = useSet<string>("documents", docId, "tags");

    return (
        <div>
            {elements.map((tag) => (
                <span key={tag}>
                    {tag} <button onClick={() => remove(tag)}>x</button>
                </span>
            ))}
            <button onClick={() => add("new-tag")}>Add Tag</button>
        </div>
    );
}

function SyncIndicator() {
    const { status, lastSyncTime, pendingCount, sync } = useSyncStatus();

    return (
        <div>
            <span>Status: {status}</span>
            <span>Pending: {pendingCount}</span>
            <button onClick={sync} disabled={status === "syncing"}>
                Sync Now
            </button>
        </div>
    );
}

function StreamControl() {
    const { connected, disconnect, reconnect } = useStream();

    return (
        <div>
            <span>{connected ? "Connected" : "Disconnected"}</span>
            <button onClick={connected ? disconnect : reconnect}>
                {connected ? "Disconnect" : "Reconnect"}
            </button>
        </div>
    );
}

import { usePresence } from "@grove-js/crdt/react";

interface UserPresence {
    name: string;
    cursor: { x: number; y: number } | null;
    isTyping: boolean;
}

function CollaborativeEditor({ roomId }: { roomId: string }) {
    const { others, updateMyPresence, leave } = usePresence<UserPresence>(roomId);

    return (
        <div>
            {others.map((peer) => (
                <div key={peer.node_id}>
                    {peer.data.name} {peer.data.isTyping ? "is typing..." : ""}
                </div>
            ))}

            <textarea
                onKeyDown={() => updateMyPresence({ isTyping: true })}
                onBlur={() => updateMyPresence({ isTyping: false, cursor: null })}
            />
        </div>
    );
}

import { useDocumentPresence } from "@grove-js/crdt/react";

function DocumentEditor({ docId }: { docId: string }) {
    const { others, updateMyPresence } = useDocumentPresence<{
        name: string;
        color: string;
    }>("documents", docId);

    useEffect(() => {
        updateMyPresence({ name: "Alice", color: "#3b82f6" });
    }, []);

    return (
        <div>
            <div className="active-users">
                {others.map((p) => (
                    <span key={p.node_id} style={{ color: p.data.color }}>
                        {p.data.name}
                    </span>
                ))}
            </div>
            {/* ... editor content ... */}
        </div>
    );
}

// Insert an item into a list at a position.
store.insertIntoList("boards", "board-1", "tasks", "Buy groceries", { after: "task-2" });

// Insert at the beginning of the list.
store.insertIntoList("boards", "board-1", "tasks", "First task", { position: "start" });

// Delete an item from a list by its node ID.
store.deleteFromList("boards", "board-1", "tasks", "task-node-id");

// Move an item to a new position.
store.moveInList("boards", "board-1", "tasks", "task-node-id", { after: "task-5" });

// Set a field at a path (uses LWW merge by default).
store.setDocumentField("profiles", "user-1", "data", "address.city", "New York");

// Set a nested field.
store.setDocumentField("profiles", "user-1", "data", "preferences.theme", "dark");

// Delete a field at a path.
store.deleteDocumentField("profiles", "user-1", "data", "address.zip");

// Increment a counter at a path.
store.incrementDocumentCounter("profiles", "user-1", "data", "stats.loginCount", 1);

// Add to a set at a path.
store.addToDocumentSet("profiles", "user-1", "data", "roles", "editor");

import { useList, useNestedDocument } from "@grove-js/crdt/react";

function TaskList({ boardId }: { boardId: string }) {
    const { items, insert, remove, move } = useList<string>("boards", boardId, "tasks");

    return (
        <ul>
            {items.map((item, index) => (
                <li key={item.id} draggable>
                    {item.value}
                    <button onClick={() => remove(item.id)}>x</button>
                </li>
            ))}
            <button onClick={() => insert("New task", { position: "end" })}>
                Add Task
            </button>
        </ul>
    );
}

function ProfileEditor({ userId }: { userId: string }) {
    const { get, set, remove, paths } = useNestedDocument("profiles", userId, "data");

    return (
        <div>
            <input
                value={get("address.city") ?? ""}
                onChange={(e) => set("address.city", e.target.value)}
                placeholder="City"
            />
            <input
                value={get("address.zip") ?? ""}
                onChange={(e) => set("address.zip", e.target.value)}
                placeholder="ZIP"
            />
        </div>
    );
}

// Chainable BatchWriter API.
store.batch("documents", "doc-1")
    .setField("title", "Updated Title")
    .incrementCounter("viewCount", 1)
    .addToSet("tags", "featured")
    .commit();

// Multiple field updates in one batch.
store.batch("profiles", "user-1")
    .setField("name", "Alice Smith")
    .setField("email", "alice@example.com")
    .setField("status", "active")
    .commit();

// Perform mutations.
store.setField("documents", "doc-1", "title", "Draft");
store.setField("documents", "doc-1", "title", "Final");

// Undo the last mutation.
store.undo();
// title is now "Draft"

// Redo the undone mutation.
store.redo();
// title is now "Final"

// Check capabilities.
console.log(store.canUndo); // boolean
console.log(store.canRedo); // boolean

import { useUndo } from "@grove-js/crdt/react";

function UndoControls() {
    const { undo, redo, canUndo, canRedo } = useUndo();

    return (
        <div>
            <button onClick={undo} disabled={!canUndo}>Undo</button>
            <button onClick={redo} disabled={!canRedo}>Redo</button>
        </div>
    );
}

// Export the entire store state.
const snapshot = store.exportState();
// Returns: { tables: { documents: { "doc-1": DocumentState, ... }, ... } }

// Export a single table.
const docsSnapshot = store.exportTable("documents");

// Import state into a store (merges with existing state).
store.importState(snapshot);

import { IndexedDBStorage } from "@grove-js/crdt";

const storage = new IndexedDBStorage({
    dbName: "my-app-crdt",
    dbVersion: 1,
});

// Pass to CRDTStore.
const store = new CRDTStore("browser-1", clock, { storage });

// Or pass via CRDTProvider.
<CRDTProvider config={{
    baseURL: "/api/sync",
    nodeID: "browser-1",
    tables: ["documents"],
    storage: new IndexedDBStorage({ dbName: "my-app-crdt" }),
}}>
    <App />
</CRDTProvider>

import { RoomClient } from "@grove-js/crdt";

const rooms = new RoomClient({
    baseURL: "/api/sync",
    nodeID: "browser-1",
});

// Create a room.
await rooms.create("design-session", { maxParticipants: 10 });

// Join with participant data.
await rooms.join("design-session", {
    name: "Alice",
    color: "#3b82f6",
    cursor: { type: "canvas", x: 0, y: 0 },
});

// List rooms.
const roomList = await rooms.list();

// Leave a room.
await rooms.leave("design-session");

import { useRoom, useDocumentRoom, useRoomList } from "@grove-js/crdt/react";

function RoomBrowser() {
    const { rooms, loading } = useRoomList();

    return (
        <ul>
            {rooms.map((room) => (
                <li key={room.id}>
                    {room.id} ({room.participantCount}/{room.maxParticipants})
                </li>
            ))}
        </ul>
    );
}

function DocumentRoom({ docId }: { docId: string }) {
    const { participants, join, leave, updateMyData } = useDocumentRoom("documents", docId);

    useEffect(() => {
        join({ name: "Alice", color: "#3b82f6" });
        return () => { leave(); };
    }, []);

    return (
        <div>
            {participants.map((p) => (
                <span key={p.nodeId} style={{ color: p.data.color }}>
                    {p.data.name}
                </span>
            ))}
        </div>
    );
}

import type { StorePlugin } from "@grove-js/crdt";

interface StorePlugin {
    name: string;
    onInit?(store: CRDTStore): void;
    onBeforeMutation?(mutation: Mutation): Mutation | null;
    onAfterMutation?(mutation: Mutation, prevState: DocumentState): void;
    onBeforeSync?(changes: ChangeRecord[]): ChangeRecord[];
    onAfterSync?(result: SyncResult): void;
    onConflict?(field: string, local: FieldState, remote: FieldState, resolved: FieldState): void;
    destroy?(): void;
}

// Register a plugin on the store.
store.use(myPlugin);

// Or via CRDTProvider config.
<CRDTProvider config={{
    baseURL: "/api/sync",
    nodeID: "browser-1",
    tables: ["documents"],
    plugins: [validationPlugin, loggingPlugin],
}}>
    <App />
</CRDTProvider>

const validationPlugin: StorePlugin = {
    name: "validation",
    onBeforeMutation(mutation) {
        if (mutation.field === "title" && typeof mutation.value === "string") {
            if (mutation.value.length > 200) {
                console.warn("Title too long, truncating");
                return { ...mutation, value: mutation.value.slice(0, 200) };
            }
        }
        return mutation;
    },
};

const conflictLogger: StorePlugin = {
    name: "conflict-logger",
    onConflict(field, local, remote, resolved) {
        console.log(`Conflict on "${field}":`, {
            localHLC: local.hlc,
            remoteHLC: remote.hlc,
            winner: resolved === remote ? "remote" : "local",
        });
    },
};

import { usePlugin } from "@grove-js/crdt/react";

function PluginStatus() {
    const plugin = usePlugin("validation");
    // Access plugin instance for runtime configuration
    return <div>Plugin: {plugin?.name ?? "not loaded"}</div>;
}

import { useConflicts } from "@grove-js/crdt/react";

function ConflictBanner() {
    const { conflicts, clearConflicts } = useConflicts();

    if (conflicts.length === 0) return null;

    return (
        <div className="conflict-banner">
            <p>{conflicts.length} conflict(s) resolved automatically</p>
            <ul>
                {conflicts.map((c, i) => (
                    <li key={i}>
                        {c.table}/{c.pk}: field "{c.field}" — {c.resolution} won
                    </li>
                ))}
            </ul>
            <button onClick={clearConflicts}>Dismiss</button>
        </div>
    );
}

import {
    CRDTErrorCode,
    NetworkError,
    ValidationError,
    SyncError,
    PluginError,
} from "@grove-js/crdt";

try {
    await client.push(changes);
} catch (err) {
    if (err instanceof NetworkError) {
        console.error("Network issue:", err.message, err.statusCode);
    } else if (err instanceof SyncError) {
        console.error("Sync conflict:", err.code, err.details);
    } else if (err instanceof ValidationError) {
        console.error("Validation failed:", err.field, err.constraint);
    } else if (err instanceof PluginError) {
        console.error("Plugin error:", err.pluginName, err.message);
    }
}

import { CRDTProvider, useDocument, useCollection, useSyncStatus } from "@grove-js/crdt/react";

interface Document {
    id: string;
    title: string;
    viewCount: number;
    tags: string[];
}

function App() {
    return (
        <CRDTProvider config={{
            baseURL: "/api/sync",
            nodeID: `browser-${crypto.randomUUID()}`,
            tables: ["documents"],
        }}>
            <SyncBar />
            <DocumentList />
        </CRDTProvider>
    );
}

function SyncBar() {
    const { status, pendingCount, sync } = useSyncStatus();
    return (
        <header>
            <span>{status} | {pendingCount} pending</span>
            <button onClick={sync}>Sync</button>
        </header>
    );
}

function DocumentList() {
    const { items, create } = useCollection<Document>("documents");
    return (
        <div>
            {items.map((doc) => (
                <DocumentCard key={doc.id} id={doc.id} />
            ))}
            <button onClick={() => create(crypto.randomUUID(), { title: "Untitled" })}>
                New
            </button>
        </div>
    );
}

function DocumentCard({ id }: { id: string }) {
    const { data, update, remove } = useDocument<Document>("documents", id);
    if (!data) return null;

    return (
        <div>
            <input
                value={data.title}
                onChange={(e) => update("title", e.target.value)}
            />
            <span>Views: {data.viewCount}</span>
            <button onClick={remove}>Delete</button>
        </div>
    );
}