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'; username: 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)

Username branded type

types.ts defines a branded Username:


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

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

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

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';