JavaScript client

@kinedb/client is the direct client of kinedb. It sends SQL to a running kinedb server over HTTP (JSON) and over a WebSocket (a binary protocol). It works in a browser, in Bun, and in Node 22 or newer.

Install

The packages live on the forge, under the kinedb organisation: https://git.kinedb.com/kinedb/-/packages. There is no npmjs.com copy.

.npmrc:

@kinedb:registry=https://git.kinedb.com/api/packages/kinedb/npm/
//git.kinedb.com/api/packages/kinedb/npm/:_authToken=<your gitea token>

Then install the package:

npm install @kinedb/client

Use

import { KineDB } from '@kinedb/client';

const db = new KineDB('http://localhost:4820');
const r  = await db.sql('SELECT 1');        // one-shot over HTTP
const h  = await db.health();

const ws = await db.connect();              // a persistent WebSocket
const rows = await ws.sql('SELECT * FROM users');
const sub  = await ws.watch('users', (n) => console.log(n));
sub.cancel();
ws.close();

With no argument the client derives its URLs from the page (defaultBaseUrl(), defaultWsUrl()), which is what a browser app behind a reverse proxy wants.

Credentials

The client holds no session. An application installs two hooks once, and every new KineDB(...) in that application picks them up:

import { setAuthHooks } from '@kinedb/client';

setAuthHooks({
  getToken: () => myStore.token,      // read on EVERY request, never cached
  onUnauthorized: () => myStore.logout(),  // runs on a 401, BEFORE the throw
});

One client can override them:

new KineDB(url, undefined, { getToken: () => otherToken });

With neither, the client sends no bearer and bounces nobody — the right default for a consumer that never logs in. GET /health stays bare in every case, because it is open by design and a liveness probe has no credentials.

setAuthHooks returns the hooks it replaced, so a test or a one-off task can put them back.

Retrying

Off by default: a server-flagged transient rejection throws at once, with err.retryable set so a caller can build its own loop.

const db = new KineDB(url, undefined, { retry: true });

With it on, the client absorbs those rejections behind a random full-jitter wait, and honours the server's own retry_ms pacing hint on a backoff response.