TypeScript SDK

TypeScript/JavaScript client for the HeliosDB-Lite REST API.

Installation

The SDKs are Apache-2.0 and developed in the public HeliosDatabase/HeliosDB-SDKs repository. They are not published to package registries yet, so install from source as shown. See SDKs & Integrations and the SDK README for the full client API.

git clone https://github.com/HeliosDatabase/HeliosDB-SDKs
cd HeliosDB-SDKs/sdks/typescript && npm install && npm run build && cd -
npm install ./HeliosDB-SDKs/sdks/typescript

The locally installed package is named @heliosdb/client.

Quick Start

Every Lite /v1 route needs a JWT signed with the server’s HELIOSDB_JWT_SECRET; see Authentication for how to mint one.

import { HeliosDB } from '@heliosdb/client';

const db = new HeliosDB({
  url: 'http://localhost:8080',
  jwtToken: process.env.HELIOSDB_TOKEN,
});

// Query the main branch (POST /v1/branches/main/query)
const result = await db.query('SELECT * FROM users WHERE id = $1', [1]);
console.log(result.toObjects());

Branching

// POST /v1/branches
await db.createBranch('dev', { fromBranch: 'main' });

// Query a branch
await db.query('SELECT count(*) FROM users', [], { branch: 'dev' });

Branches can also be managed in SQL: CREATE DATABASE BRANCH dev FROM main AS OF NOW.

Vector Search and Agent Memory

The SDK has vector-store and agent-memory helpers. The matching Lite REST endpoint groups are planned, so these helpers return a not-implemented error against Lite today. Run vector search in SQL instead; see Vector Search.

See the REST API Reference for the routes Lite serves.