NexaClient

Official JavaScript/TypeScript client for NexaDB - The high-performance, easy-to-use database.

Features

• TypeScript support - Full type definitions included
• Multi-database support - Manage multiple isolated databases in one instance
• 3-10x faster than HTTP/REST - Binary protocol with MessagePack encoding
• Persistent TCP connections - No HTTP overhead
• Automatic reconnection - Built-in connection management
• Connection pooling - Handle 1000+ concurrent operations
• Vector search - Built-in HNSW vector similarity search
• TOON format - 40-50% token reduction for LLM applications
• Promise-based API - Modern async/await syntax

Installation

npm install nexaclient

Quick Start

// ES Modules / TypeScript
import NexaClient from 'nexaclient';

// CommonJS
// const NexaClient = require('nexaclient');

// Create client
const db = new NexaClient({
  host: 'localhost',
  port: 6970,
  username: 'root',
  password: 'nexadb123'
});

// Connect
await db.connect();

// Create document
const user = await db.create('users', {
  name: 'John Doe',
  email: '[email protected]'
});

// Get document
const found = await db.get('users', user.document_id);

// Update document
await db.update('users', user.document_id, {
  age: 30
});

// Query documents
const results = await db.query('users', { age: { $gte: 25 } });

// Delete document
await db.delete('users', user.document_id);

// Disconnect
await db.disconnect();

TypeScript Usage

import NexaClient from 'nexaclient';

interface User {
  name: string;
  email: string;
  age?: number;
}

const db = new NexaClient({
  host: 'localhost',
  port: 6970,
  username: 'root',
  password: 'nexadb123'
});

await db.connect();

// Full type inference
const user = await db.create<User>('users', {
  name: 'John Doe',
  email: '[email protected]'
});

// Typed queries
const users = await db.query<User>('users', { age: { $gte: 25 } });

await db.disconnect();

API Reference

Constructor

const db = new NexaClient(options);

Options:

• host (string) - Server host (default: 'localhost')
• port (number) - Server port (default: 6970)
• username (string) - Username for authentication (default: 'root')
• password (string) - Password for authentication (default: 'nexadb123')
• timeout (number) - Connection timeout in ms (default: 30000)
• autoReconnect (boolean) - Auto-reconnect on disconnect (default: true)

Methods

connect()

Connect to NexaDB server.

await db.connect();

create(collection, data)

Create document in collection.

const result = await db.create('users', {
  name: 'Alice',
  email: '[email protected]'
});
// Returns: { collection: 'users', document_id: '...', message: '...' }

get(collection, key)

Get document by ID.

const user = await db.get('users', userId);
// Returns: { _id: '...', name: 'Alice', email: '...' } or null

update(collection, key, updates)

Update document.

await db.update('users', userId, {
  age: 30,
  department: 'Engineering'
});

delete(collection, key)

Delete document.

await db.delete('users', userId);

query(collection, filters, limit)

Query documents with filters.

const results = await db.query('users', {
  role: 'developer',
  age: { $gte: 25 }
}, 100);
// Returns: [{ _id: '...', name: '...', ... }, ...]

batchWrite(collection, documents)

Bulk insert documents.

await db.batchWrite('users', [
  { name: 'Alice', email: '[email protected]' },
  { name: 'Bob', email: '[email protected]' },
  { name: 'Carol', email: '[email protected]' }
]);

vectorSearch(collection, vector, limit, dimensions)

Vector similarity search (for AI/ML applications).

const results = await db.vectorSearch('embeddings', [0.1, 0.2, ...], 10, 768);
// Returns: [{ document_id: '...', similarity: 0.95, document: {...} }, ...]

ping()

Ping server (keep-alive).

const pong = await db.ping();

disconnect()

Disconnect from server.

await db.disconnect();

Events

NexaClient extends EventEmitter and emits the following events:

• connect - Connected to server
• disconnect - Disconnected from server
• error - Connection or protocol error
• message - Unsolicited message from server

db.on('connect', () => {
  console.log('Connected to NexaDB');
});

db.on('error', (err) => {
  console.error('Error:', err);
});

db.on('disconnect', () => {
  console.log('Disconnected from NexaDB');
});

Performance

NexaClient uses a custom binary protocol for maximum performance:

| Metric | HTTP/REST | NexaClient (Binary) | Improvement | |--------|-----------|---------------------|-------------| | Latency | 5-10ms | 1-2ms | 3-5x faster | | Throughput | 1K ops/sec | 5-10K ops/sec | 5-10x faster | | Bandwidth | 300KB | 62KB | 80% less |

Examples

See the examples/ directory for more usage examples:

• basic.js - Basic CRUD operations
• bulk.js - Bulk insert performance (coming soon)
• query.js - Advanced queries (coming soon)
• vectors.js - Vector search (coming soon)

Requirements

• Node.js >= 12.0.0
• NexaDB server running on localhost:6970 (or custom host/port)

NexaDB vs MongoDB

| Feature | MongoDB | NexaDB | |---------|---------|---------| | Setup | 15 min | 2 min (brew install nexadb) | | Write speed | ~50K/s | ~89K/s | | Memory | 2-4 GB | 111 MB | | Protocol | Custom binary | Custom binary | | Client | Native drivers | NexaClient (this package) |

License

MIT

Links

• NexaDB GitHub
• Documentation
• Issues

Multi-Database Support (v3.0.0)

// Create and manage multiple databases
await db.createDatabase('tenant_acme');
await db.createDatabase('tenant_globex');

// Insert data into specific database
await db.create('users', { name: 'Alice' }, { database: 'tenant_acme' });
await db.create('users', { name: 'Bob' }, { database: 'tenant_globex' });

// Query from specific database
const acmeUsers = await db.query('users', {}, { database: 'tenant_acme' });
const globexUsers = await db.query('users', {}, { database: 'tenant_globex' });

// List all databases
const databases = await db.listDatabases();

Contributing

Contributions are welcome! Please open an issue or PR on GitHub.

Support

For support, please:

• Open an issue on GitHub
• Website: https://nexadb.io
• Email: [email protected]