@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