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. connect() is public, but most applications only need it for eager connection or manual reconnect flows.

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

Connect

await client.connect();

connect() explicitly establishes or restores the shared WebSocket connection. It is safe to call more than once and deduplicates concurrent connection work. Existing subscription state is preserved in the underlying client so reconnecting the same instance can resume live queries.

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.