Cell Values

KalamCellValue is the SDK’s typed wrapper around every individual cell value returned in a query result or subscription event.

Instead of receiving plain Record<string, unknown> rows (where you must guess the type and cast manually), you get RowData = Record<string, KalamCellValue> rows with named accessor methods that mirror the Rust implementation.

Topic consumer payloads stay raw JSON until you explicitly wrap them with wrapRowMap().

Quick Example

1import { createClient, Auth } from '@kalamdb/client';2 3const client = createClient({ url: 'http://localhost:2900', authProvider: async () => Auth.basic('admin', 'kalamdb123') });4 5// queryAll() returns RowData[] — every cell is a KalamCellValue6const rows = await client.queryAll('SELECT id, name, score, avatar FROM users');7 8for (const row of rows) {9  const id     = row.id.asString();       // string | null10  const name   = row.name.asString();     // string | null11  const score  = row.score.asFloat();     // number | null12  const born   = row.born_at.asDate();    // Date | null13  const uuid   = row.public_id.asUuid();   // string | null14  const amount = row.total.asDecimal();    // exact string | null15  const avatar = row.avatar.asFile();     // FileRef | null16  const url    = row.avatar.asFileUrl('http://localhost:2900', 'default', 'users');17  console.log(id, name, score, born?.toISOString(), url);18}19 20// Single row:21const row = await client.queryOne('SELECT * FROM users WHERE id = $1', [42]);22if (row) console.log(row.name.asString());

Creating a KalamCellValue

KalamCellValue.from(raw)

Wrap any raw JS value as a KalamCellValue. Pass null / undefined for SQL NULL.

1const cell = KalamCellValue.from(someRawValue);

client.queryAll(sql, params?)

Execute a SQL query and return all rows with every cell pre-wrapped as KalamCellValue. This is the recommended method for typed cell access.

1const rows = await client.queryAll('SELECT * FROM orders');2for (const row of rows) {3  console.log(row.status.asString(), row.total.asFloat());4}

client.queryOne(sql, params?)

Single-row variant of queryAll() — returns the first row, or null.

1const row = await client.queryOne('SELECT * FROM users WHERE id = $1', [42]);2console.log(row?.name.asString());

wrapRowMap(raw)

Convert a raw object row into RowData when you are handling row-shaped JSON outside queryOne() / queryAll():

1import { wrapRowMap } from '@kalamdb/client';2 3const typedRow = wrapRowMap({ id: '1', name: 'Alice' });

RowData Type

1type RowData = Record<string, KalamCellValue>;

Use RowData as the type annotation for typed result rows throughout your application.

Type Guards

Typed Accessors

.asString(): string | null

Returns the value as a string, or null for SQL NULL.
Handles { "Utf8": "..." } Rust-side string envelopes automatically.

1const name = row.name.asString();           // "Alice"2const nullCell = row.deleted_at.asString(); // null

.asInt(): number | null

Returns the value as an integer (Math.trunc-ed), or null.
Parses string-encoded integers ("42" → 42).

1const count = row.item_count.asInt(); // 7

.asBigInt(): bigint | null

Returns the value as a native bigint. Use this for Int64 / UInt64 columns that may exceed Number.MAX_SAFE_INTEGER.

1const id = row.snowflake_id.asBigInt();

.asSeqId(): SeqId | null

Returns the value as a SeqId wrapper when the cell contains a KalamDB sequence ID such as _seq.

1const seq = row._seq.asSeqId();2console.log(seq?.timestampMillis());

.asFloat(): number | null

Returns the value as a floating-point number, or null.
Parses string-encoded floats ("3.14" → 3.14).

1const price = row.price.asFloat(); // 19.99

.asBool(): boolean | null

Returns the value as a boolean, or null.
Handles string-encoded booleans: "true", "false", "1", "0".

1const active = row.is_active.asBool(); // true

.asDate(): Date | null

Returns the value as a Date, or null for SQL NULL / unparseable values.

Handles:

• Unix milliseconds (number): 1704067200000 → Date
• ISO 8601 strings: "2024-01-01T00:00:00Z" → Date
• Numeric timestamp strings: "1704067200000" → Date

1const created = row.created_at.asDate(); // Date object2console.log(created?.toLocaleDateString());

.asDateOnly(): Date | null

Returns a UTC midnight Date for KalamDB DATE columns. Handles Date32 day offsets from the wire and ISO date strings.

1const invoiceDate = row.invoice_date.asDateOnly();2console.log(invoiceDate?.toISOString().slice(0, 10));

.asTimeString(): string | null

Returns a KalamDB TIME value as HH:mm:ss or HH:mm:ss.ffffff. Handles the server wire value of microseconds since midnight.

1const startsAt = row.starts_at.asTimeString();

.asUuid(): string | null

Validates and lowercases UUID values.

1const id = row.public_id.asUuid();

.asDecimal(): string | null

Returns DECIMAL(p,s) values as exact strings. This avoids precision loss from coercing fixed-point values into JavaScript numbers.

1const total = row.total.asDecimal();

.asBytes(): Uint8Array | null

Returns BYTES values as Uint8Array. The accessor accepts the server’s byte array wire format and base64 strings when interoperating with older tooling.

1const payload = row.payload.asBytes();

.asEmbedding(): number[] | null

Returns EMBEDDING(n) vectors as a number array.

1const vector = row.doc_embedding.asEmbedding();

.asObject(): Record<string, JsonValue> | null

Returns the raw value as a plain object, or null.

.asArray(): JsonValue[] | null

Returns the raw value as an array, or null.

FILE Column Support

.asFile(): FileRef | null

Parse a FILE column value and return a FileRef instance (or null).

1const ref = row.attachment.asFile();2if (ref) {3  console.log(ref.name, ref.mime, ref.formatSize());4  console.log(ref.isImage()); // true for image/* MIME types5}

See FILE Columns & Uploads for the full FileRef API.

.asFileUrl(baseUrl, namespace, table): string | null

Convenience method — parse a FILE column and return the download URL in one call.

1const url = row.avatar.asFileUrl('http://localhost:2900', 'default', 'users');2// e.g. "http://localhost:2900/v1/files/default/users/f0001/12345-photo.png"3img.src = url ?? '/placeholder.png';

The generated URL uses KalamDB’s stored filename path, so it is safe to fetch directly with the caller’s bearer token.

Serialisation

.asJson(): JsonValue

Returns the underlying raw JSON value. This is the preferred JSON accessor.

.toJson(): JsonValue

Compatibility alias of .asJson().

Returns the underlying raw JSON value. Use this when you need to pass the value to code that expects plain JSON (e.g. FileRef.from(cell.asJson())).

.toString(): string

Human-readable display:

• SQL NULL → "NULL"
• strings → value as-is
• objects / arrays → compact JSON
• other → String(value)

Using with Live Rows

live() callbacks receive rows as RowData, where each column is already a KalamCellValue. Use the same typed accessors as query results:

1import type { RowData } from '@kalamdb/client';2 3const stop = await client.live<RowData>('SELECT * FROM default.users', (rows) => {4  for (const row of rows) {5    console.log(row.name.asString(), row.score.asFloat());6 7    // FILE columns still work via KalamCellValue helpers.8    const avatar = row.avatar?.asFile();9    if (avatar) console.log(avatar.downloadUrl());10  }11});

KalamRow.cell(column): KalamCellValue

Access a single column as a KalamCellValue. KalamRow is used by queryRows(); live rows expose the same cell values directly on RowData.

KalamRow.typedData: RowData

All column values wrapped as KalamCellValue in a Record<string, KalamCellValue>. Cached on first access for performance.

Using with Consumers

1import { Auth, wrapRowMap } from '@kalamdb/client';2import { createConsumerClient } from '@kalamdb/consumer';3 4const worker = createConsumerClient({5  url: 'http://localhost:2900',6  authProvider: async () => Auth.basic('worker', 'Secret123!'),7});8 9await worker.consumer({ topic: 'events', group_id: 'events-reader', auto_ack: true }).run(async (ctx) => {10  const row = wrapRowMap(ctx.message.value as Record<string, unknown>);11  console.log(row.event_type.asString(), row.created_at.asDate());12});

Full API Reference