mergendb

MergenDB Node.js & TypeScript SDK (v1.0.0 Production Release)

The official zero-dependency Node.js and TypeScript client SDK for MergenDB — engineered for high-throughput columnar analytics, embedded edge backends, and unified AI vector embedding similarity search.

The v1.0.0 Milestone & Architectural Evolution

MergenDB Node.js SDK v1.0.0 is built to bring enterprise-grade analytical SQL and neural vector search into the JavaScript/TypeScript ecosystem without pulling in heavy native bindings, node-gyp builds, or gigabytes of external binaries.

What We Achieved in v1.0.0:

• AI-Native Vector Operations: Seamlessly store and query VECTOR columns with JavaScript Array<number> or Float32Array.
• Native Vector Search Method (table.vectorSearch): Execute nearest-neighbor searches using Cosine, Euclidean (L2), Dot Product, or Manhattan distance.
• Sub-Millisecond Hybrid Queries: Combine relational filters (filter: "category = 'AI'") with vector similarity in a single network round-trip.
• Zero External Runtime Dependencies: Built strictly on Node.js core modules (http, https, fs, path, url). Zero node_modules required in production.
• Tagged Template Literal SQL (db.sql): Safe, parameterized analytical SQL queries with intuitive template strings.
• Zero-Memory Streaming I/O: Stream multi-gigabyte CSV, JSON, and SQL dumps directly to disk or network sockets with bounded memory buffers.
• Strict Zero-Emoji Policy: Clean, professional terminal interface built with deterministic status tags ([+], [-], [*], [!]).

Installation

npm install mergendb

Or using yarn / pnpm:

yarn add mergendb
# or
pnpm add mergendb

Comprehensive MergenQL & Node.js Usage Guide

1. Connection & Local Auto-Start

import { MergenDB } from 'mergendb';

// Connect to MergenDB server (or automatically spawn local headless daemon)
const db = new MergenDB({
  host: '127.0.0.1',
  port: 8765,
  autoStart: true // auto-spawns background database daemon if not running
});

await db.ping();
console.log('[+] Connected to MergenDB v1.0.0');

2. Creating Tables with Vector & Relational Columns

const telemetry = db.table('iot_knowledge_base');

await telemetry.create([
  { name: 'doc_id', type: 'INT32' },
  { name: 'title', type: 'STRING' },
  { name: 'category', type: 'STRING' },
  { name: 'embedding', type: 'VECTOR' }
]);

// Insert documents with float vectors
await telemetry.insert([
  { doc_id: 1, title: 'Attention Is All You Need', category: 'AI', embedding: [0.95, 0.1, 0.05] },
  { doc_id: 2, title: 'General Relativity', category: 'Physics', embedding: [0.82, 0.2, 0.15] },
  { doc_id: 3, title: 'French Culinary Arts', category: 'Cooking', embedding: [0.05, 0.9, 0.1] }
]);

3. Native Vector Similarity Search

Perform top-K nearest-neighbor similarity searches using the intuitive vectorSearch API:

const results = await telemetry.vectorSearch('embedding', [1.0, 0.0, 0.0], {
  topK: 2,
  filter: "category = 'AI'",
  metric: 'cosine' // 'cosine', 'l2', 'dot', 'manhattan'
});

for (const row of results) {
  console.log(`[+] Document: ${row.title} | Score: ${row.score.toFixed(4)}`);
}

4. Tagged Template SQL with Vector Similarity

Execute standard SQL with native mathematical vector functions directly in Node.js:

const minScore = 0.8;
const targetVector = [1.0, 0.0, 0.0];

const queryRes = await db.sql`
  SELECT doc_id, title, cosine_similarity(embedding, ${targetVector}) AS score
  FROM iot_knowledge_base
  WHERE category = 'AI'
  ORDER BY score DESC
  LIMIT 5;
`;

console.log(queryRes.toObjects());

5. CLI Usage in Node.js Projects

The Node.js package includes a global and local CLI runner (mergendb or npx mergendb):

# Check database server health
npx mergendb status

# Run SQL query from terminal
npx mergendb query "SELECT title, score FROM iot_knowledge_base"

# Benchmark hardware and scan throughput
npx mergendb benchmark

TypeScript Definitions

Full TypeScript definitions are bundled in the package (index.d.ts), providing complete autocompletion and type inference for TableHandle, DatabaseHandle, QueryResult, and query builder interfaces.

License

Distributed under the MIT License. See LICENSE for details.