Types & Enums

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

Runtime enums

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

1enum MessageType {2  SubscriptionAck = 'subscription_ack',3  InitialDataBatch = 'initial_data_batch',4  Change = 'change',5  Error = 'error',6}7 8enum ChangeType {9  Insert = 'insert',10  Update = 'update',11  Delete = 'delete',12}

Auth types

1type AuthCredentials =2  | { type: 'basic'; user: string; password: string }3  | { type: 'jwt'; token: string }4  | { 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

1interface QueryResponse {2  status: 'success' | 'error';3  results?: QueryResult[];4  took?: number;5  error?: ErrorDetail;6}7 8interface QueryResult {9  schema?: SchemaField[];10  rows?: unknown[][];11  named_rows?: Record<string, unknown>[];12  row_count: number;13  message?: string;14}

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:

1type UserId = string & { readonly __brand: unique symbol };2function 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:

1const one = await client.queryOne('SELECT * FROM app.users WHERE id = $1', ['u1']);2const all = await client.queryAll('SELECT * FROM app.users');3 4// FILE-aware wrappers5const rows = await client.queryRows<{ id: string; avatar: unknown }>(6  'SELECT id, avatar FROM app.users',7  'app.users',8);9const 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.

1import { KalamCellValue, wrapRowMap } from '@kalamdb/client';2import type { RowData } from '@kalamdb/client';3 4const row: RowData = wrapRowMap({ id: '1', score: 9.5, active: true });5 6row.id.asString();    // "1"7row.score.asFloat();  // 9.58row.active.asBool();  // true9row.avatar.asFile();  // FileRef | null10row.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:

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