@c4a/nebula-client

Pure JavaScript NebulaGraph client over Thrift binary protocol. Zero native dependencies.

Works with Bun and Node.js (>=18).

Why

The official community client @nebula-contrib/nebula-nodejs requires a native C++ addon compiled via node-gyp. This breaks under Bun (ABI incompatibility) and adds friction for cross-platform deployment.

This package reimplements the Thrift binary protocol and GraphService RPC layer entirely in JavaScript using BigInt and standard node:net sockets. No native compilation needed.

Install

npm install @c4a/nebula-client
# or
bun add @c4a/nebula-client

Usage

import { createClient } from "@c4a/nebula-client";

const client = createClient({
  servers: ["127.0.0.1:9669"],
  userName: "root",
  password: "nebula",
  space: "my_space",
  poolSize: 2,
});

// Wait for ready (optional — execute() queues automatically)
client.on("ready", () => {
  console.log("Connected to NebulaGraph");
});

// Execute nGQL queries
const result = await client.execute("SHOW SPACES");
console.log(result.data);
// { Name: ["my_space", "other_space"] }

// Insert data
await client.execute(
  'INSERT VERTEX person(name, age) VALUES "alice": ("Alice", 30)'
);

// Query
const query = await client.execute(
  'GO FROM "alice" OVER knows YIELD properties($$).name AS name'
);
console.log(query.data);
// { name: ["Bob", "Charlie"] }

// Clean up
await client.close();

API

createClient(options): Client

Create a connection-pooled client.

Option	Type	Default	Description
servers	(string | {host, port})[]	required	NebulaGraph graphd addresses ("host:port")
userName	string	required	Username
password	string	required	Password
space	string	required	Graph space to USE after auth
poolSize	number	5	Connections per server
bufferSize	number	2000	Max queued tasks
executeTimeout	number	10000	Query timeout (ms)
pingInterval	number	60000	Keepalive interval (ms)

client.execute(nGQL: string): Promise<ParsedResponse>

Execute an nGQL statement. Returns parsed response with columnar data format:

{
  error_code: number;        // 0 = success
  error_msg?: string;
  data?: Record<string, unknown[]>;  // Columnar: { col1: [...], col2: [...] }
  metrics: {
    execute: number;         // Wall-clock ms
    traverse: number;        // Parse ms
    connectionId?: string;
  };
}

client.close(): Promise<void>

Close all connections.

Events

The client emits standard lifecycle events:

• ready — A connection is authenticated and ready
• error — Connection or query error
• connected — TCP connection established
• authorized — Authentication succeeded

Drop-in Replacement

This package is API-compatible with @nebula-contrib/nebula-nodejs for common usage patterns:

- import { createClient } from "@nebula-contrib/nebula-nodejs";
+ import { createClient } from "@c4a/nebula-client";

The createClient function accepts the same options and client.execute() returns the same columnar data format.

Differences

Feature	nebula-nodejs	@c4a/nebula-client
Native addon	Required (C++)	None
Bun support	No (ABI mismatch)	Yes
i64 handling	node-int64 + native	BigInt
Dependencies	lodash, q, bindings, node-int64	None

Utility Functions

bytesToLongLongString(buffer: Uint8Array | number[]): string

Convert 8 bytes (little-endian) to signed 64-bit integer string. Compatible with the native addon's BytesToLongLongString.

hash64(key: string): [string, string]

MurmurHash3 x64 128-bit hash. Returns [high64, low64] as decimal strings. Compatible with the native addon's Hash64.

License

MIT