Types & Enums

@kalamdb/client exports the app-facing runtime enums and rich TypeScript types.

Runtime enums

import { MessageType, ChangeType } from '@kalamdb/client';

enum MessageType {
  SubscriptionAck = 'subscription_ack',
  InitialDataBatch = 'initial_data_batch',
  Change = 'change',
  Error = 'error',
}
 
enum ChangeType {
  Insert = 'insert',
  Update = 'update',
  Delete = 'delete',
}

Auth types

type AuthCredentials =
  | { type: 'basic'; user: string; password: string }
  | { type: 'jwt'; token: string }
  | { type: 'none' };

ClientOptions (construction)

createClient({ ... }) accepts a ClientOptions object. Common fields:

• url: string — server base URL
• authProvider: () => Promise<AuthCredentials> — required auth source for the high-level client
• authProviderMaxAttempts?: number — retry attempts for transient auth-provider failures
• authProviderInitialBackoffMs?: number — initial auth-provider retry backoff
• authProviderMaxBackoffMs?: number — max auth-provider retry backoff
• wsLazyConnect?: boolean — default true; defer the WebSocket until the first subscription/live call
• pingIntervalMs?: number — default 5000; application-level keepalive interval
• disableCompression?: boolean — dev-only debugging (?compress=false)
• wasmUrl?: string | BufferSource — override WASM loading
• onConnect?, onDisconnect?, onError?, onReceive?, onSend? — connection lifecycle callbacks
• logLevel?, logListener? — SDK logging controls

There is no high-level auth or autoConnect option on createClient(...).

createConsumerClient({ ... }) from @kalamdb/consumer accepts the same base options plus consumerWasmUrl?: string | BufferSource for worker-only WASM resolution.

Query response model

interface QueryResponse {
  status: 'success' | 'error';
  results?: QueryResult[];
  took?: number;
  error?: ErrorDetail;
}
 
interface QueryResult {
  schema?: SchemaField[];
  rows?: unknown[][];
  named_rows?: Record<string, unknown>[];
  row_count: number;
  message?: string;
}

Prefer named_rows when present. Helper methods queryOne()/queryAll() wrap those rows as RowData, while queryRows() wraps them as FILE-aware KalamRow<T> values.

Subscription and consumer types

• ServerMessage
• SubscriptionOptions
• SubscriptionCallback

The topic worker types moved into @kalamdb/consumer:

• ConsumeRequest
• ConsumeResponse
• ConsumeMessage
• ConsumeContext
• ConsumerHandle
• AckResponse

ServerMessage from generated declarations includes:

• auth events (auth_success, auth_error)
• subscription events (subscription_ack, initial_data_batch, change, error)

UserId branded type

types.ts defines a branded UserId:

type UserId = string & { readonly __brand: unique symbol };
function UserId(value: string): UserId;

Use this in service pipelines when you want stricter domain typing.

KalamDataType

KalamDataType mirrors the server’s canonical column type enum and schema metadata. The SDK supports both scalar and parameterized variants:

Use KalamCellValue accessors for row reads and @kalamdb/orm for Drizzle column generation from this metadata.

Row helper methods

Use client helpers instead of manual parsing:

const one = await client.queryOne('SELECT * FROM app.users WHERE id = $1', ['u1']);
const all = await client.queryAll('SELECT * FROM app.users');
 
// FILE-aware wrappers
const rows = await client.queryRows<{ id: string; avatar: unknown }>(
  'SELECT id, avatar FROM app.users',
  'app.users',
);
const avatar = rows[0]?.file('avatar');

KalamCellValue & RowData

Every cell in a RowData row is wrapped in a KalamCellValue — a typed accessor class that mirrors the Rust KalamCellValue newtype.

import { KalamCellValue, wrapRowMap } from '@kalamdb/client';
import type { RowData } from '@kalamdb/client';
 
const row: RowData = wrapRowMap({ id: '1', score: 9.5, active: true });
 
row.id.asString();    // "1"
row.score.asFloat();  // 9.5
row.active.asBool();  // true
row.avatar.asFile();  // FileRef | null
row.total.asDecimal(); // exact string | null

See Cell Values (KalamCellValue) for the full API including all accessor methods and FILE column support.

Type-only imports

Prefer import type for large type sets in app code:

import type { QueryResponse, ServerMessage } from '@kalamdb/client';
import type { ConsumeRequest } from '@kalamdb/consumer';