Client Lifecycle

This page documents the lifecycle methods implemented in src/client.ts.

Construction

import { createClient, Auth, type AuthProvider } from '@kalamdb/client';
 
const authProvider: AuthProvider = async () => {
  const token = await myApp.getOrRefreshJwt();
  return Auth.jwt(token);
};
 
const client = createClient({
  url: 'http://localhost:8080',
  authProvider,
});

Validation at construction time:

• url is required
• authProvider is required

See Authentication for the full auth guide.

WebSocket connection behavior

The SDK manages the WebSocket connection lifecycle automatically. There is no need to call connect() manually.

• query() runs over HTTP and does not require a WebSocket connection.
• subscribe(), subscribeWithSql(), subscribeRows(), live(), and liveTableRows() automatically establish the WebSocket connection on first use.

wsLazyConnect (default: true)

By default, the WebSocket connection is lazy: it is deferred until the first subscribe(), subscribeWithSql(), or live() call. This avoids unnecessary connections when the client is only used for HTTP queries.

Set wsLazyConnect: false to establish the connection eagerly during initialization:

const client = createClient({
  url: 'http://localhost:8080',
  authProvider: async () => Auth.jwt('<JWT_TOKEN>'),
  wsLazyConnect: false, // connect immediately
});

pingIntervalMs

Use pingIntervalMs to tune the WebSocket ping interval (default 5000).

const client = createClient({
  url: 'http://localhost:8080',
  authProvider,
  pingIntervalMs: 15_000,
});

disableCompression

By default the server sends gzip-compressed binary WebSocket frames. During development you can disable compression to inspect raw JSON frames in browser DevTools or wscat:

const client = createClient({
  url: 'http://localhost:8080',
  authProvider,
  disableCompression: true, // appends ?compress=false to the WS URL
});

When enabled the client appends ?compress=false to the WebSocket URL and the server responds with plain-text JSON frames for every message.

Do not use in production. Compression significantly reduces bandwidth for subscription payloads. Only enable for local debugging.

Initialization behavior

initialize():

• loads WASM runtime (init(...))
• resolves initial credentials from authProvider
• creates underlying WASM KalamClient
• wires authProvider callback into WASM for WebSocket auth resolution and reconnects
• calls setDisableCompression(true) on WASM client when option is set
• if wsLazyConnect: false, establishes the WebSocket connection immediately

You usually don’t call it manually; most methods initialize lazily.

Disconnect

await client.disconnect();

Notes:

• disconnect() closes the WebSocket and clears SDK-side subscription tracking.
• After disconnecting, the next subscribe() call will re-establish the connection.

Full teardown with shutdown()

await client.shutdown();

Use shutdown() when you want to free the underlying WASM client and fully reset local SDK state. This is the stronger cleanup option for long-running Node.js processes, test suites, and explicit resource-management flows.

Reconnection controls

client.setAutoReconnect(true);
client.setReconnectDelay(1000, 30000);
client.setMaxReconnectAttempts(10); // 0 means infinite
 
console.log(client.getReconnectAttempts());
console.log(client.isReconnecting());

setReconnectDelay(initial, max) is passed as BigInt to WASM.

Subscription state helpers

client.getSubscriptionCount();
client.getSubscriptions();
client.isSubscribedTo('SELECT * FROM app.messages');
client.getLastSeqId('<subscription-id>');

These are SDK-level convenience methods around subscription bookkeeping.

Cleanup pattern

try {
  // work
} finally {
  await client.unsubscribeAll();
  await client.disconnect();
}

Use this pattern in long-running services to avoid leaked subscriptions.