LakeSync — Declare what data goes where

Installation

npm install lakesync

Or with other package managers:

pnpm add lakesync
# or
bun add lakesync

Quick Start (createClient)

The fastest way to get started — createClient opens a database, registers schemas, creates a transport, and starts auto-sync in one call:

import { createClient } from "lakesync/client";

const client = await createClient({
  name: "my-app",
  clientId: "client-1",
  schemas: [
    {
      table: "todos",
      columns: [
        { name: "title", type: "string" },
        { name: "completed", type: "number" },
      ],
    },
  ],
  gateway: {
    url: "https://your-gateway.example.com",
    gatewayId: "gw-1",
    token: "your-jwt-token",
  },
});

// Insert, update, delete via the tracker
await client.coordinator.tracker.insert("todos", "todo-1", {
  title: "Build something great",
  completed: 0,
});

// When done
await client.destroy();

createClient returns a LakeSyncClient with coordinator, db, transport, and a destroy() method.

Manual Setup

For more control (custom transports, local development, WebSocket), construct the pieces yourself.

1. Open a Local Database

import { LocalDB } from "lakesync/client";

const dbResult = await LocalDB.open({ name: "my-app" });
if (!dbResult.ok) throw dbResult.error;
const db = dbResult.value;

2. Register a Schema

Use registerSchema to create the table and store schema metadata:

import { registerSchema } from "lakesync/client";

await registerSchema(db, {
  table: "todos",
  columns: [
    { name: "title", type: "string" },
    { name: "completed", type: "number" },
  ],
});

3. Set Up a Transport

For local development, use LocalTransport to sync in-process:

import { LocalTransport } from "lakesync/client";
import { SyncGateway } from "lakesync/gateway";

const gateway = new SyncGateway({
  gatewayId: "gw-1",
  maxBufferBytes: 1_048_576,
  maxBufferAgeMs: 30_000,
});
const transport = new LocalTransport(gateway);

For production, use HttpTransport to connect to a remote gateway:

import { HttpTransport } from "lakesync/client";

const transport = new HttpTransport({
  baseUrl: "https://your-gateway.example.com",
  gatewayId: "gw-1",
  token: "your-jwt-token",
});

For real-time sync, use WebSocketTransport instead:

import { WebSocketTransport } from "lakesync/client";

const transport = new WebSocketTransport({
  url: "wss://your-gateway.example.com/sync/gw-1/ws",
  token: "your-jwt-token",
});

4. Create a Coordinator and Sync

import { SyncCoordinator } from "lakesync/client";

const coordinator = new SyncCoordinator(db, transport);
coordinator.startAutoSync();

5. Insert Data

The coordinator exposes a tracker for CRUD operations. Each mutation requires a separate rowId argument:

await coordinator.tracker.insert("todos", "todo-1", {
  title: "Build something great",
  completed: 0,
});

await coordinator.tracker.update("todos", "todo-1", {
  completed: 1,
});

await coordinator.tracker.delete("todos", "todo-1");

Next Steps

Architecture — Understand HLCs, deltas, and conflict resolution
Real-Time Sync — Sub-second sync via WebSocket broadcasting
React Hooks — useQuery, useMutation, useSyncStatus for React apps
Actions — Execute imperative operations against external systems
Core API — Explore the core package exports
Client SDK — LocalDB, SyncCoordinator, and transports

Getting Started