Cell Values

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

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.

Quick Example

import { createClient, Auth } from 'kalam-link';
 
const client = createClient({ url: 'http://localhost:8080', authProvider: async () => Auth.basic('admin', 'kalamdb123') });
await client.login();
 
// queryAll() returns RowData[] — every cell is a KalamCellValue
const rows = await client.queryAll('SELECT id, name, score, avatar FROM users');
 
for (const row of rows) {
  const id     = row.id.asString();       // string | null
  const name   = row.name.asString();     // string | null
  const score  = row.score.asFloat();     // number | null
  const born   = row.born_at.asDate();    // Date | null
  const avatar = row.avatar.asFile();     // FileRef | null
  const url    = row.avatar.asFileUrl('http://localhost:8080', 'default', 'users');
  console.log(id, name, score, born?.toISOString(), url);
}
 
// Single row:
const row = await client.queryOne('SELECT * FROM users WHERE id = $1', [42]);
if (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.

const 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.

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

client.queryOne(sql, params?)

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

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

wrapRowMap(raw) / wrapRowMaps(raws) / wrapCellArray(raw)

Convert individual raw objects or arrays:

import { wrapRowMap, wrapRowMaps, wrapCellArray } from 'kalam-link';
 
const typedRow   = wrapRowMap({ id: '1', name: 'Alice' });
const typedRows  = wrapRowMaps(rawObjectArray);
const typedCells = wrapCellArray(rawPositionalRow);

RowData Type

type 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.

const name = row.name.asString();           // "Alice"
const 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).

const 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.

const id = row.snowflake_id.asBigInt();

.asFloat(): number | null

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

const 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".

const 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

const created = row.created_at.asDate(); // Date object
console.log(created?.toLocaleDateString());

.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).

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

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.

const url = row.avatar.asFileUrl('http://localhost:8080', 'default', 'users');
// e.g. "http://localhost:8080/files/default/users/f0001/photo.png?id=..."
img.src = url ?? '/placeholder.png';

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 Subscriptions

subscribeRows() wraps each row as KalamRow<T>. Use .cell(column) or .typedData for the same KalamCellValue access pattern as queryAll():

import { KalamRow } from 'kalam-link';
 
const unsub = await client.subscribeRows<UserRow>('default.users', (change) => {
  for (const row of change.rows) {
    // Option 1: .cell() for individual columns
    console.log(row.cell('name').asString(), row.cell('score').asFloat());
 
    // Option 2: .typedData for the full RowData map (cached)
    const td = row.typedData;
    console.log(td['name'].asString(), td['score'].asFloat());
 
    // FILE columns still work via .file()
    const avatar = row.file('avatar');
    if (avatar) console.log(avatar.downloadUrl());
  }
});

KalamRow.cell(column): KalamCellValue

Access a single column as a KalamCellValue. Works the same whether the row came from queryRows() or subscribeRows().

KalamRow.typedData: RowData

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

Using with Consumers

import { wrapRowMap } from 'kalam-link';
 
await client.consume({
  table: 'events',
  handler: async (msg) => {
    const row = wrapRowMap(msg.value as Record<string, unknown>);
    console.log(row.event_type.asString(), row.created_at.asDate());
  },
});

Full API Reference