Client Lifecycle

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

Construction

1import { createClient, Auth, type AuthProvider } from '@kalamdb/client';2 3const authProvider: AuthProvider = async () => {4  const token = await myApp.getOrRefreshJwt();5  return Auth.jwt(token);6};7 8const client = createClient({9  url: 'http://localhost:2900',10  authProvider,11  onConnect: () => {12    console.log('realtime socket ready');13  },14  onConnectionError: (error) => {15    console.error('cannot reach KalamDB:', error.message);16  },17});

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.
• live(), liveTable(), and liveEvents() automatically establish the WebSocket connection on first use.

Connect

1await 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.

Lifecycle handlers

createClient() and the KalamDBClient instance support three connection-lifecycle hooks:

• onConnect(callback) fires when the shared realtime connection becomes healthy.
• onConnectionError(callback) fires for connection and auth/bootstrap failures.
• onError(callback) remains as a compatibility alias for connection-error handling.

1const client = createClient({2  url: 'http://localhost:2900',3  authProvider,4  onConnect: () => {5    console.log('connected to KalamDB');6  },7  onConnectionError: (error) => {8    console.error(9      `[${error.recoverable ? 'retryable' : 'fatal'}] ${error.message}`,10    );11  },12});13 14client.onConnect(() => {15  console.log('socket restored or connected');16});17 18client.onConnectionError((error) => {19  console.error('connection/auth problem:', error.message);20});

Use onConnectionError for new code. onError still works, but it exists mainly so older code does not break.

If you do not register either handler, the SDK now logs connection/auth failures to the console by default instead of failing silently.

What reaches onConnectionError

The callback is used for both WebSocket connection failures and pre-connect failures that happen before the socket opens:

• invalid or malformed server URLs
• auth provider resolution failures
• login or token refresh failures used during connection/bootstrap
• unreachable server / refused connection cases

The event shape comes from the shared WASM client and includes:

• message: normalized error message
• recoverable: true when the failure can reasonably be retried, false for fatal configuration/auth issues

wsLazyConnect (default: true)

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

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

1const client = createClient({2  url: 'http://localhost:2900',3  authProvider: async () => Auth.jwt('<JWT_TOKEN>'),4  wsLazyConnect: false, // connect immediately5});

pingIntervalMs

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

1const client = createClient({2  url: 'http://localhost:2900',3  authProvider,4  pingIntervalMs: 15_000,5});

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:

1const client = createClient({2  url: 'http://localhost:2900',3  authProvider,4  disableCompression: true, // appends ?compress=false to the WS URL5});

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

If eager initialization hits a connection/auth/bootstrap failure, the SDK emits onConnectionError before rethrowing.

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

Disconnect

1await 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()

1await 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

1client.setAutoReconnect(true);2client.setReconnectDelay(1000, 30000);3client.setMaxReconnectAttempts(10); // 0 means infinite4 5console.log(client.getReconnectAttempts());6console.log(client.isReconnecting());

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

Subscription state helpers

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

These are SDK-level convenience methods around subscription bookkeeping.

Cleanup pattern

1try {2  // work3} finally {4  await client.unsubscribeAll();5  await client.disconnect();6}

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