SDK overview

Web apps, Node scripts and editor plugins use it to read, query, watch and change records and files in one collection.

Where to start

How the SDK works

Your app talks to a replica of the collection: a copy that applies changes in the order the collection’s log confirms them. The SDK gives you that replica’s view, plus your own writes that are still waiting.

• Reads are local. get, query and live answer from the replica’s view. They include your pending writes.
• Writes are intents. Each write returns at once with a receipt in the pending state. It becomes confirmed when the log accepts it, or rejected with a reason.
• Nothing is lost silently. Concurrent edits to the same field are merged, and the losing value is kept as a conflict you can review. A file-backed replica can also put a local edit on hold instead of overwriting it.

Pending writes and sync status covers receipts, holds and conflicts.

Getting a client

Every client comes from connect(), given a connector that says how to reach a replica:

Application shape

Keep domain code on MdbaseClient. It then runs unchanged against any connector.

import type { MdbaseClient } from "@mdbase-dev/sdk";

// Accept the client, not a connector, so the same code runs against
// a real collection and against MemoryReplica in tests.
export async function listOpenTasks(db: MdbaseClient) {
  const page = await db.query({
    types: ["task"],
    where: 'status == "open"',
    order_by: [{ field: "due", direction: "asc" }],
    limit: 50,
  });
  return page.records;
}

Package map

The package needs Node 20 or later outside the browser. It is what apps use instead of the @mdbase-dev/connect beta.