@kinedb/client (0.0.0-g9fdbe1e5326f)

Published 2026-09-11 10:06:17 +00:00 by skadefro

Set up this registry in your project .npmrc file:

@kinedb:registry=https://git.kinedb.com/api/packages/kinedb/npm/

To install the package using npm, run the following command:

npm install @kinedb/client@0.0.0-g9fdbe1e5326f

or add it to the package.json file:

"@kinedb/client": "0.0.0-g9fdbe1e5326f"

For more information on the npm registry, see the documentation.

The direct client of kinedb — JSON over HTTP, binary TLV over WebSocket.

@kinedb/client

The direct client of kinedb: JSON over HTTP, binary TLV over WebSocket. It speaks to a running kinedb-server.

This package used to be the file web/src/data/kinedb.js inside the console app, and every other project copied it by hand (B836).

The two shapes of every kinedb SDK

kinedb ships each SDK twice, in every language. The names are fixed, and the API surface is identical, so an application changes ONE import line and nothing else.

role	Rust crate	npm	status
wire types + TLV/frame codec	`kinedb-protocol`	`@kinedb/protocol`	not split out yet
direct client (remote server)	(none yet)	`@kinedb/client`	this package
embedded engine + sync	`kinedb`	`@kinedb/embedded`	reserved, not built

import { KineDB } from '@kinedb/client';     // talks to a remote kinedb-server
import { KineDB } from '@kinedb/embedded';   // talks to a local engine that syncs

@kinedb/embedded will bundle the kinedb engine. The SDK talks to that local embedded database, and the embedded database replicates to a real kinedb elsewhere. It does not exist yet; the name is reserved so no application has to be rewritten when it lands.

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>

Tags are commits, like docker — not version numbers

kinedb has not released an SDK, so no package carries a version number that promises compatibility. A build is named by the commit that produced it:

npm install @kinedb/client@a1b2c3d        # the short commit sha
npm install @kinedb/client@pr-740         # the head of a pull request

Nothing is published to latest. The version field reads 0.0.0-g<short-sha> only because npm refuses a manifest without a semver string; the sha in the prerelease slot is the real identity. Read the tag, ignore the number.

Publishing: bun scripts/sdk-publish.ts sdk/js/client from the repo root. It refuses a dirty tree, because a hash tag must name a commit that actually holds the published bytes.

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.

Test

cd sdk/js/client && bun test src/

The wire format this file mirrors is the Rust one: crates/kinedb-protocol/src/{frame,tlv,codec,messages}.rs. That is the truth; this package follows it.

Details

npm

2026-09-11 10:06:17 +00:00

0

UNLICENSED

g9fdbe1e5326f

22 KiB

Assets (1)

client-0.0.0-g9fdbe1e5326f.tgz 22 KiB

Versions (10) View all

0.0.0-g80bf37b85187

2026-09-11