TypeScript SDK Packages

KalamDB has separate TypeScript packages for separate jobs. Pick one package path, copy the first example, then move to the package docs when you need more detail.

Which Package Should I Use?

Job	Install	Start here
Query SQL, login, upload files, subscribe to rows	`@kalamdb/client`	Setup & Quick Start
Use Drizzle tables or generate `schema.ts`	`@kalamdb/client @kalamdb/orm drizzle-orm`	Drizzle ORM & Generator
Consume topics, ACK messages, run agents	`@kalamdb/client @kalamdb/consumer`	Topic Consumers & ACK
Build React hooks and UI helpers	planned `@kalamdb/react` package	use `@kalamdb/client` directly for now

Fast Start: App Client

Use @kalamdb/client in browser apps, Next.js apps, scripts, and API services.


npm i @kalamdb/client

Copy this smoke test:


import { Auth, createClient } from '@kalamdb/client';
 
const client = createClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),
});
 
const result = await client.query('SELECT CURRENT_USER()');
console.log(result.status, result.results?.[0]);
 
await client.disconnect();

Use it for:

query(), queryOne(), queryAll(), and queryRows()
login() and refreshToken()
live() and subscribeWithSql()
queryWithFiles() for FILE uploads

Fast Start: ORM Package

Use @kalamdb/orm when you want typed tables and Drizzle-style queries. It sits on top of @kalamdb/client; it is not a second connection layer.


npm i @kalamdb/client @kalamdb/orm drizzle-orm

Generate a schema from a running KalamDB server:


npx kalamdb-orm \
  --url http://localhost:8080 \
  --user admin \
  --password AdminPass123! \
  --namespace app \
  --out src/db/schema.ts

Query with the generated table:


import { Auth, createClient } from '@kalamdb/client';
import { kalamDriver } from '@kalamdb/orm';
import { messages } from './db/schema';
 
const client = createClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('admin', 'AdminPass123!'),
});
 
const db = kalamDriver(client);
const rows = await db.select().from(messages).limit(20);
console.log(rows);

Fast Start: Consumer Package

Use @kalamdb/consumer only in workers or agents that consume topics. Keep this code out of browser bundles.


npm i @kalamdb/client @kalamdb/consumer

Copy this worker skeleton:


import { Auth } from '@kalamdb/client';
import { createConsumerClient } from '@kalamdb/consumer';
 
const worker = createConsumerClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.basic('worker', 'Secret123!'),
});
 
const handle = worker.consumer({
  topic: 'orders.events',
  group_id: 'billing-worker',
  auto_ack: false,
  batch_size: 10,
});
 
await handle.run(async (ctx) => {
  await processOrder(ctx.message.payload);
  await ctx.ack();
});

Read next: Topic Consumers & ACK and Agent Runtime.

How Packages Work Together

Use this split in real projects:

UI code imports @kalamdb/client.
Typed table code imports @kalamdb/orm plus the app client.
Worker code imports @kalamdb/consumer.
Future React helpers should live in a separate React-focused package instead of growing the base client.

Common Paths

I want to…	Read
Run the first query	Setup & Quick Start
Subscribe to rows for a UI	Realtime Subscriptions
Generate typed tables	Drizzle ORM & Generator
Build a topic worker	Topic Consumers & ACK
Build a retrying agent	Agent Runtime
Copy full example flows	Examples and Cookbook

TypeScript SDK Packages

Which Package Should I Use?

Fast Start: App Client

Fast Start: ORM Package

Fast Start: Consumer Package

How Packages Work Together

Common Paths

Getting Started

Documentation

Resources

Community