TypeScript Live Queries

Use client.live() to receive the current rows of a KalamDB query. The SDK loads the initial snapshot and reconciles later inserts, updates, and deletes by primary key. Replace your displayed list on each callback; do not append the whole callback array.

For React, start with the React inbox example. For typed Drizzle tables outside React, use the ORM live-table example. The Dart/Flutter and Rust examples use the same table.

Prepare the live-query example

Start a server using the server quick start. Run this schema as an account allowed to create tables, in the SQL Studio or your schema migration:

1CREATE SCHEMA IF NOT EXISTS app;2CREATE TABLE IF NOT EXISTS app.live_messages (3  id TEXT PRIMARY KEY,4  room TEXT NOT NULL,5  body TEXT NOT NULL6) WITH (TYPE = 'USER');

This is a private inbox: use the same authenticated user for the subscriber and the test writes. A room filter does not make a USER table shared between users. Collaborative rooms need a SHARED table and access policies.

Run a TypeScript live query

In a Node.js TypeScript project:

1npm install @kalamdb/client2npm install --save-dev tsx typescript @types/node3export KALAMDB_URL=http://localhost:29004export KALAMDB_USERNAME=your-user5export KALAMDB_PASSWORD=your-password6npx tsx inbox.ts

Save the following as inbox.ts before running the last command. Credentials here are for a local terminal; browser apps should use their signed-in user’s token through an auth provider.

1import { Auth, createClient } from '@kalamdb/client';2 3type Message = { id: string; room: string; body: string };4 5async function main() {6  const username = process.env.KALAMDB_USERNAME;7  const password = process.env.KALAMDB_PASSWORD;8  if (!username || !password) throw new Error('Set KALAMDB_USERNAME and KALAMDB_PASSWORD');9 10  const client = createClient({11    url: process.env.KALAMDB_URL ?? 'http://localhost:2900',12    authProvider: async () => Auth.basic(username, password),13    onDisconnect: (reason) => console.warn('Disconnected:', reason.message),14    onConnectionError: (error) => console.error('Connection:', error.message),15  });16  let stop: (() => Promise<void>) | undefined;17  let finish!: () => void;18  const shutdown = new Promise<void>((resolve) => { finish = resolve; });19  const onSignal = () => finish();20  process.once('SIGINT', onSignal);21  process.once('SIGTERM', onSignal);22 23  try {24    console.log('Loading inbox…');25    await client.connect();26    stop = await client.live<Message>(27      "SELECT id, room, body FROM app.live_messages WHERE room = 'main'",28      (rows) => {29        console.log(rows.length === 0 ? 'Inbox is empty' : `${rows.length} messages`);30        console.table(rows);31      },32      {33        getKey: 'id',34        mapRow: (row) => ({35          id: row.id.asString()!,36          room: row.room.asString()!,37          body: row.body.asString()!,38        }),39        onError: (event) => {40          console.error(`Subscription [${event.code}]: ${event.message}`);41          process.exitCode = 1;42          finish(); // Correct the cause before running again.43        },44      },45    );46    await shutdown;47  } finally {48    process.off('SIGINT', onSignal);49    process.off('SIGTERM', onSignal);50    try { await stop?.(); }51    finally { await client.disconnect(); }52  }53}54 55void main().catch((error) => {56  console.error('Inbox stopped:', error);57  process.exitCode = 1;58});

The outer catch handles connection and startup failures. onError handles server subscription errors reported after startup. Connection callbacks report transport problems. This CLI deliberately stops on a subscription error; a UI can retain its last rows with a visible stale/error state and offer a fresh subscription after the cause is resolved.

Verify inserts, updates, and deletes

While the example is running, execute these statements one at a time through another connection using the same identity:

1INSERT INTO app.live_messages (id, room, body)2VALUES ('demo-1', 'main', 'Hello from another connection');3 4UPDATE app.live_messages SET body = 'Edited in realtime' WHERE id = 'demo-1';5 6DELETE FROM app.live_messages WHERE id = 'demo-1';

On a fresh table, expect an empty inbox, then one message, then the edited body without a duplicate, then an empty inbox again. Press Ctrl+C to unsubscribe and disconnect. Re-running the app starts a fresh snapshot, so existing rows appear too.

Choose rows, typed tables, or events

With no mapRow, fields are KalamCellValue objects: use asString(), asBool(), and other cell accessors. Include the primary key in your SELECT. Use getKey: ['first_key', 'second_key'] for declared key columns; a JavaScript key function uses the TypeScript reconciliation path.

Limits, reconnects, and recovery

• Direct client.live() SQL supports SELECT ... FROM ... WHERE .... Keep joins, aggregates, ORDER BY, and LIMIT out of this subscription SQL.
• batchSize controls snapshot chunks. lastRows restricts the initial history. Direct client.live()’s limit bounds the retained row set; it does not promise a SQL-sorted top-N window.
• ORM and React orderBy / limit are local presentation controls. They retain the matching set so a removed visible row can be replaced. Narrow the filter for large datasets.
• The SDK manages connection recovery. Do not create another subscription on every disconnect notification. If you explicitly retry, close the previous subscription first.
• Do not restore a cursor into an empty UI cache and assume it reloads all rows. A durable resume needs matching cached data, query/identity, and checkpoint; an ordinary screen can start fresh without from.
• Replay is bounded. A delivery gap or expired cursor needs recovery, not a claim that the displayed rows are current. See reconnection and resume and the WebSocket recovery contract.

To check failures, temporarily use a missing table or invalid credentials. Expect a visible error instead of an empty-success state. Fix the cause and restart. Disconnect the network to exercise connection callbacks; after recovery, compare the list with a normal SELECT before treating it as current.

Only the owner of a shared client should disconnect it. A component should stop its own subscription; the React hook handles that on unmount.