Client

connect and BoardClient, covering raw SQL queries, the board-rooted builder, mutation methods, and watch for lakefront/client.

import { connect } from "lakefront/client";

The wire client: connect returns a client scoped to one board, with the engine’s own query surface over HTTP, a board-rooted builder on top, and typed methods for writes and the change feed.

Functions

connect

function connect(options: ClientOptions): { board(boardId: string): BoardClient };

Returns { board(boardId): BoardClient }. A client only exists in the context of a board; there is no way to issue a query without calling board first.

const client = connect({ url: "http://127.0.0.1:8080" });
const board = client.board("acme_roadmap");

BoardClient

client.board(boardId) returns a BoardClient. It hides the CQRS split: query, select, and db go through query.execute; the mutation methods go through the mutate.* procedures and return the watermark they committed at. A board is one table, so reads are rooted at the board: nothing underneath it to name.

Reads

query

query(
  sql: string,
  options?: { params?: readonly Cell[]; minWatermark?: number },
): Promise<Result<BoardQueryOutcome, WireError>>

Raw SQL against this board: the same surface as engine.query, over the wire. The outcome mirrors engine.query’s shape exactly, plus servedBy; see BoardQueryOutcome.

const outcome = (await board.query("SELECT count(*) AS n FROM {{table}}")).unwrap();
outcome.result.rows; // columnar, like engine.query

select

select<SE extends SelectExpression<BoardSchema, "items">>(
  selections: SelectArg<BoardSchema, "items", SE>,
)

Starts a Kysely chain rooted at the board: a board is one table, so there is no table to name. .where(), .orderBy(), .execute() follow.

selectAll

selectAll();

The whole-row variant of select.

db

db: Kysely<BoardSchema>;

The raw Kysely instance, for joins and subqueries the rooted select/selectAll chains do not reach.

atLeast

atLeast(watermark: number): BoardClient

Returns a new BoardClient whose reads refuse to be served by a replica older than watermark: read-your-write. Never mutates the client it is called on.

const written = await board.insert({ id: "i1", state: "active", title: "first item" });
written.unwrap("insert failed"); // -> the watermark it committed at

const fresh = board.atLeast(written.unwrap());
await fresh.selectAll().execute();

Writes

Mutations return the watermark they committed at, or a typed failure. A rejected write is never retried automatically unless it carries an idempotencyKey: it may have landed, and the caller is the only one who knows whether replaying it is safe. A keyed mutation is safe to replay (the server answers a repeat with the original ack), and the transport retries and fails over accordingly. See the idempotency guide for the exactly-once contract that makes a keyed retry safe.

insert

insert(row: Row, options?: MutateOptions): Promise<Result<number, WireError>>

Inserts one row. Sugar over insertMany.

insertMany

insertMany(rows: readonly Row[], options?: MutateOptions): Promise<Result<number, WireError>>

update

update(id: string, patch: Row, options?: MutateOptions): Promise<Result<number, WireError>>

Patches one row by id. Sugar over updateMany.

updateMany

updateMany(
  updates: ReadonlyArray<{ readonly id: string; readonly patch: Row }>,
  options?: MutateOptions,
): Promise<Result<number, WireError>>

Many single-row patches as one atomic write; see Engine.updateMany.

delete

delete(id: string, options?: MutateOptions): Promise<Result<number, WireError>>

Deletes one row by id. Sugar over deleteMany.

deleteMany

deleteMany(ids: readonly string[], options?: MutateOptions): Promise<Result<number, WireError>>

Feed

watch

watch(
  options?: { after?: number; signal?: AbortSignal },
): AsyncGenerator<WatchEvent, void, undefined>

Follows the board’s change feed over the node’s SSE stream, as an async iterable: the same surface Engine.watch offers embedded, carried over GET /watch.

for await (const event of board.watch({ after })) {
  if (event.resync) {
    // re-read current state, then continue -- the cursor already moved
  } else {
    // event.records
  }
}

Ends when signal aborts or the server closes the stream (a token past its expiry does that; reconnect with a fresh one). A server-sent error event is thrown, so an unhandled for await propagates it to the caller. Design, retention, and what resync means for a consumer are covered in the watch guide.

Operations

lastRead

lastRead(): LastRead

What the client’s most recent read reported about where it was served from: not needed for correctness, useful for demonstrating cache affinity. See LastRead.

stats

stats(): Promise<Result<EngineStats & { nodeId: string; boards: string[] }, WireError>>

Calls node.stats.

Types

ClientOptions

Transport knobs shared with the wire-level client: exactly RpcClientOptions from lakefront/contract.

See the wire contract for the retry-eligibility rule: idempotent procedures always, mutations only when the input carries an idempotencyKey.

BoardClientOptions

ClientOptions & { readonly boardId: string }. What BoardClient.create (and, through it, connect(...).board(boardId)) takes.

BoardQueryOutcome

What query resolves to: engine.query’s outcome shape plus servedBy, naming which node served this request over HTTP.

MutateOptions

WatchEvent

type WatchEvent =
  | { readonly resync: false; readonly records: readonly ChangeRecord[] }
  | { readonly resync: true; readonly from: number };

The same discriminant ChangesPage carries (see the wire contract), minus the paging cursor the iterator manages for you. ChangeRecord is { seq: number, kind: WalKind, payload: WalPayload, actor?: string }.

LastRead

ItemRow

interface ItemRow {
  id: string;
  updated_at: number | null;
  state: string | null;
  [column: string]: Cell;
}

interface BoardSchema {
  items: ItemRow;
}

The three named fields are the TypeScript view of BASE_COLUMNS from lakefront/contract (id: VARCHAR, updated_at: TIMESTAMP, state: VARCHAR), columns every board has. Cell is string | number | boolean | null.

A TIMESTAMP reads back as epoch microseconds in UTC, so new Date(row.updated_at / 1000) gives a Date. The engine sets updated_at on every write.

The index signature allows user-defined columns. The client checks the wire types and query structure but does not know each board’s schema.

Limits

The Kysely dialect (dialect.ts) throws rather than silently downgrading behavior:

• No transactions. beginTransaction, commitTransaction, and rollbackTransaction all throw lakefront: transactions are not supported on the read path. Reads are served from a per-board replica synced per request, so there is no cross-request transaction to begin. See the transactions guide for what runs transactionally instead.
• No streaming. streamQuery throws lakefront: streaming is not supported.

Lower-level exports

Plumbing for people building their own layer over the wire contract rather than using BoardClient directly.