TypeScript SDK

Build typed HelixDB requests for Node.js applications

Guide

The published @helix-db/helix-db 3.0.4 package targets Node.js 20 or newer and emits the same operation-tree AST as the Rust, Go, and Python SDKs.

The package is ESM and requires Node.js 20 or newer.

Install

npm install @helix-db/helix-db@3.0.4

The package is ESM. Set "type": "module" or compile to ESM.

Define a query

import {
  Predicate,
  defineParams,
  g,
  param,
  readBatch,
} from "@helix-db/helix-db";

export const findUsersParams = defineParams({
  tenantId: param.string(),
  limit: param.i64(),
});

export function findUsers() {
  return readBatch()
    .varAs(
      "users",
      g()
        .nWithLabel("User")
        .where(Predicate.eq("tenantId", findUsersParams.tenantId))
        .limit(findUsersParams.limit)
        .valueMap(["$id", "name", "tenantId"]),
    )
    .returning(["users"]);
}

Execute

import { Client } from "@helix-db/helix-db";

const request = findUsers().toQueryRequest(
  findUsersParams,
  { tenantId: "acme", limit: 25n },
  { queryName: "find_users" },
);

const result = await Client.server("http://localhost:6969")
  .query(request)
  .send();

Use withApiKey("hx_...") for Helix Cloud.

Integer safety

The SDK preserves 64-bit integers as bigint. Use stringifyJson or the request’s serialization methods instead of JSON.stringify when a value can contain bigint.

Embedded runtime

Install the SDK and embedded runtime with npm install @helix-db/helix-db @helix-db/helix-db-embedded. See Embedded database for storage, cache, and handle configuration.

Verify

npm --prefix sdks/typescript test

Next steps

Query tutorial

Build reads, writes, and parameters.

Embedded database

Open HelixDB directly inside your process.