@keradb/node-sdk

Official Node.js / TypeScript SDK for KeraDB — a lightweight, embedded NoSQL document database with vector search.

Installation

npm install @keradb/node-sdk

Prerequisites

The native KeraDB shared library must be built first:

# From the root of the keradb repository
cargo build --release

Platform library locations (auto-detected by the SDK):

| Platform | Library | |----------|---------| | Windows | target/release/keradb.dll | | macOS | target/release/libkeradb.dylib | | Linux | target/release/libkeradb.so |

Quick Start

import KeraDB from '@keradb/node-sdk';

const client = new KeraDB('mydb.ndb');
const users  = client.db.collection('users');

// Insert
const { insertedId } = await users.insertOne({ name: 'Alice', age: 30 });

// Find
const alice = await users.findOne({ _id: insertedId });

// Update
await users.updateOne({ _id: insertedId }, { $set: { age: 31 } });

// Delete
await users.deleteOne({ _id: insertedId });

client.close();

JavaScript (CommonJS)

const KeraDB = require('@keradb/node-sdk').default;

const client = new KeraDB('mydb.ndb');
const users  = client.db.collection('users');

(async () => {
  const { insertedId } = await users.insertOne({ name: 'Alice', age: 30 });
  const doc = await users.findOne({ _id: insertedId });
  console.log('Found:', doc.name, doc.age);

  const all = await users.find().toArray();
  console.log('Total:', await users.countDocuments());

  client.sync();
  client.close();
})();

API Reference

new KeraDB(path, create?)

Opens (or creates) a .ndb database file.

const client = new KeraDB('mydb.ndb');            // create if not exists
const client = new KeraDB('existing.ndb', false); // open existing only

| Method | Returns | Description | |--------|---------|-------------| | client.db | Database | Access the database object | | client.sync() | boolean | Flush in-memory state to disk | | client.close() | void | Release the native handle |

Database

const db = client.db;

const col  = db.collection('users')         // Collection<Document>
const names = await db.listCollectionNames() // string[]
const cols  = await db.listCollections()     // { name, count }[]

Collection<T>

Insert

await col.insertOne({ name: 'Alice', age: 30 })
// → { acknowledged: true, insertedId: 'uuid...' }

await col.insertMany([{ name: 'Bob' }, { name: 'Carol' }])
// → { acknowledged: true, insertedIds: [...], insertedCount: 2 }

Find

await col.findOne({ _id: 'uuid...' })           // fast id lookup
await col.findOne({ age: { $gte: 30 } })        // filter scan
await col.find({ active: true }).toArray()
await col.find().skip(10).limit(5).toArray()
await col.countDocuments()
await col.countDocuments({ active: true })

Update

Supported operators: $set, $unset, $inc, $push

await col.updateOne({ _id: id }, { $set: { age: 31 } })
await col.updateOne({ _id: id }, { $inc: { score: 5 } })
await col.updateMany({ active: false }, { $unset: { session: '' } })

Delete

await col.deleteOne({ _id: id })
await col.deleteMany({ active: false })
await col.drop()

Filter Operators

| Operator | Description | |----------|-------------| | { field: value } | Equality | | $eq, $ne | Equal / not-equal | | $gt, $gte, $lt, $lte | Numeric comparison | | $in, $nin | Membership | | $exists | Field presence | | $regex | Regular expression match | | $and, $or | Logical composition |

TypeScript Generics

interface User {
  _id: string;
  name: string;
  age: number;
}

const users = client.db.collection<User>('users');
const u = await users.findOne({ name: 'Alice' }); // typed as User | null

Benchmarks

Measured on Node.js v22.22.2, Windows 11, Intel i7-13700HX (24 cores), 128 GB RAM. 300 measured iterations per benchmark (30 warmup). SQLite uses better-sqlite3.

Single Document Operations

| Operation | KeraDB | SQLite | Speedup | Winner | |-----------|--------|--------|---------|--------| | Single insert | 88 µs · 11,294 ops/s | 5,511 µs · 181 ops/s | 62× | KeraDB | | Find by _id | 24 µs · 41,794 ops/s | 121 µs · 8,248 ops/s | 5× | KeraDB | | Update ($set) | 85 µs · 11,800 ops/s | 5,047 µs · 198 ops/s | 60× | KeraDB | | Mixed 80/20 read-write | 44 µs · 22,910 ops/s | 1,159 µs · 863 ops/s | 27× | KeraDB |

KeraDB wins all single-document operations by a large margin.

Bulk Insert

| Batch size | KeraDB | SQLite (transaction) | Winner | |------------|--------|----------------------|--------| | 100 docs | 13 ms | 21 ms | KeraDB | | 500 docs | 49 ms | 28 ms | SQLite | | 1,000 docs | 95 ms | 27 ms | SQLite |

SQLite wins bulk inserts at 500+ docs because transactions batch all disk I/O into a single commit. KeraDB writes each document individually, so it pays per-write overhead at scale.

Rule of thumb: Use KeraDB for real-time, high-frequency single-document workloads. Use SQLite transactions when bulk-loading large datasets in one shot.

Run benchmarks yourself:

npm run benchmark

Testing

npm test                    # all tests (69 total)
npm run test:unit           # pure logic — no native library required
npm run test:integration    # requires compiled native library

Scripts

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript → dist/ | | npm test | Full test suite (unit + integration) | | npm run test:unit | Unit tests only | | npm run test:integration | Integration tests only | | npm run benchmark | KeraDB vs SQLite benchmark suite |

Platform Support

| Platform | Architecture | Status | |----------|-------------|--------| | Windows | x64 | Tested | | Linux | x64, ARM64 | Supported | | macOS | x64, Apple Silicon | Supported |

Node.js: ≥ 14.0.0 (tested on v22)

License

MIT — see LICENSE