Client Lifecycle

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

Construction

import { createClient, Auth, type AuthProvider } from 'kalam-link';
 
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
• at least one of auth or authProvider is required

See Authentication for the full auth guide.

Auto-connect behavior

By default, the client is lazy:

• query() runs over HTTP and does not require a WebSocket connection.
• subscribe() / subscribeWithSql() will call connect() automatically when autoConnect: true (default).

To take full control, disable auto-connect:

const client = createClient({
  url: 'http://localhost:8080',
  auth: Auth.jwt('<JWT_TOKEN>'),
  autoConnect: false,
});
 
await client.connect();

pingIntervalMs

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

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(...))
• creates underlying WASM KalamClient
• wires authProvider callback into WASM (called before every connection)
• calls setDisableCompression(true) on WASM client when option is set

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

Connect and disconnect

await client.connect();
console.log(client.isConnected());
 
await client.disconnect();

Notes:

• connect() initializes if needed, then opens WebSocket.
• disconnect() also clears SDK-side subscription tracking map.

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 {
  await client.connect();
  // work
} finally {
  await client.unsubscribeAll();
  await client.disconnect();
}

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