xdb-engine

Official Node.js / TypeScript client for XDB Engine — an AI-powered distributed analytical database written in Rust.

Server-side only. Supported runtimes: Node.js ≥ 14 · Bun · Deno (via npm:)

Installation

npm install xdb-engine
# or
yarn add xdb-engine
# or
bun add xdb-engine

Quick Start

import { createClient } from 'xdb-engine';

const db = createClient('xdb://admin:admin123@localhost:7777');
await db.connect();

// SELECT — returns typed rows
const { rows } = await db.query(
  'SELECT * FROM orders WHERE status = $1 AND amount > $2',
  ['pending', 100]
);

// INSERT / DDL
await db.execute('CREATE TABLE logs (id INT AUTO_INCREMENT PRIMARY KEY, msg TEXT)');
await db.execute('INSERT INTO logs (msg) VALUES ($1)', ['hello world']);

// Convenience helpers
const user  = await db.first('SELECT * FROM users WHERE id = $1', [1]);
const count = await db.scalar<number>('SELECT COUNT(*) FROM users');
const all   = await db.all('SELECT name, email FROM users');

await db.end();

Connection Pool

For production, limit concurrent sockets with a pool:

import { createPool } from 'xdb-engine';

const pool = createPool('xdb://admin:admin123@localhost:7777', { size: 20 });

const results = await Promise.all(
  ids.map(id => pool.all('SELECT * FROM orders WHERE user_id = $1', [id]))
);

await pool.end();

API Reference

createClient(connectionString) → XDBClient

Connection string format: xdb://user:token@host:port

XDBClient methods

| Method | Returns | Description | |---|---|---| | connect() | this | Ping the server; chainable | | query<T>(sql, params?) | QueryResult<T> | Execute any SQL | | execute(sql, params?) | QueryResult | Alias for query() — DML/DDL | | all<T>(sql, params?) | T[] | All rows | | first<T>(sql, params?) | T \| null | First row or null | | scalar<T>(sql, params?) | T \| null | First column of first row | | ping() | void | Verify server is reachable | | admin(cmd) | string | Admin commands e.g. 'STATS' | | end() | void | No-op (stateless protocol) |

QueryResult<T>

interface QueryResult<T> {
  rows:     T[];
  fields:   { name: string; dataType: string; nullable: boolean }[];
  rowCount: number;
  command:  string;   // 'SELECT' | 'OK' | 'STATS'
  message?: string;   // server confirmation for DML/DDL
}

XDBConfig

interface XDBConfig {
  host?:                string;  // default: 'localhost'
  port?:                number;  // default: 7777
  user?:                string;
  token?:               string;  // auth token
  password?:            string;  // alias for token
  connectionTimeoutMs?: number;  // default: 30 000
  retries?:             number;  // default: 0
  retryDelayMs?:        number;  // default: 200
}

SQL Parameters

$1, $2, … placeholders are safely quoted on the client:

await db.query(
  'SELECT * FROM products WHERE category = $1 AND price < $2',
  ['electronics', 500]
);

Supported types: string, number, bigint, boolean, Date, Buffer, null.

Server Setup

./xdb-server --config config/node.toml

[node]
listen_addr = "127.0.0.1:7777"

[security]
auth_token = "your-secret-token"

const db = createClient('xdb://admin:[email protected]:7777');

License

MIT © 2026 XtroEdge