High-Performance Embedded Document Database

Built in Rust. Wrapped for Node.js. Zero configuration, in-process, single file, pure ACID.

Oblivinx3x is a MongoDB-compatible embedded database providing ACID transactions, MVCC concurrency control, and a state-of-the-art Hybrid B+/LSM storage architecture — all executing right inside your Node.js process.

Quick Start

Install and start using Oblivinx3x in under a minute. No Rust toolchain needed.

# Install via npm
npm install oblivinx3x

import { Oblivinx3x } from 'oblivinx3x';

// Open or create a database
const db = new Oblivinx3x('data.ovn', {
  compression: 'lz4',
  bufferPool: '256MB'
});

const users = db.collection('users');

// Insert
await users.insertOne({
  name: 'Alice',
  role: 'admin',
  age: 28
});

// Query
const admins = await users.find({ role: 'admin' });

// Close
await db.close();

Features Overview

Database API

The Oblivinx3x class is the main entry point. It manages database lifecycle, collections, transactions, and advanced features.

Constructor

new Oblivinx3x(path: string, options?: OvnConfig)

OvnConfig Options

Methods

Collection API

MongoDB-compatible CRUD interface with generic type support.

Insert

await users.insertOne({ name: 'Alice' });
await users.insertMany([{ name: 'Bob' }, { name: 'Carol' }]);

Query

await users.find({ age: { $gte: 18 } }, { sort: { name: 1 }, limit: 10 });
await users.findOne({ email: 'alice@example.com' });
await users.countDocuments({ active: true });
await users.exists({ role: 'admin' }); // NEW: boolean shorthand

Update

await users.updateOne({ name: 'Alice' }, { $set: { age: 29 } });
await users.updateMany({ active: false }, { $set: { active: true } });
await users.findOneAndUpdate({ name: 'Alice' }, { $inc: { loginCount: 1 } }); // NEW

Delete

await users.deleteOne({ name: 'Alice' });
await users.deleteMany({ expired: true });
await users.findOneAndDelete({ temp: true }); // NEW

Index Management

await users.createIndex({ age: 1 }, { unique: true });
await users.createIndex({ title: 'text', content: 'text' }); // Full-text
await users.dropIndex('age_1');
await users.hideIndex('temp_idx'); // Hide without dropping
await users.unhideIndex('temp_idx');

Transactions (MVCC)

Full ACID transactions with Snapshot Isolation. Readers never block writers. Savepoints enable partial rollback.

const txn = await db.beginTransaction();
try {
  await txn.update('accounts', { _id: 'alice' }, { $inc: { bal: -100 } });
  await txn.update('accounts', { _id: 'bob' },   { $inc: { bal: 100 } });

  // Savepoint for partial rollback
  await txn.savepoint('before_risky');
  await txn.insert('logs', { msg: 'risky op' });

  await txn.commit();
} catch (err) {
  await txn.rollback(); // Idempotent — safe in finally blocks
  throw err;
}

Transaction API

Query Builder

Fluent, chainable API for building complex queries.

const results = await users.find()
  .where({ age: { $gte: 18 } })
  .project({ name: 1, email: 1 })
  .sort({ name: 1 })
  .limit(20)
  .skip(10)
  .toArray();

// Streaming cursor for large datasets
const cursor = users.find().where({ active: true }).cursor({ batchSize: 100 });
for await (const user of cursor) {
  console.log(user.name);
}

Filter Operators

Full MongoDB Query Language (MQL) filter support.

Update Operators

Aggregation Pipeline

MongoDB-compatible multi-stage pipeline with 18+ stages and 9 accumulator types.

Supported Stages

Accumulators

$sum $avg $min $max $first $last $push $addToSet $count

const stats = await orders.aggregate([
  { $match: { status: 'completed' } },
  { $group: {
      _id: '$region',
      total: { $sum: '$amount' },
      avgOrder: { $avg: '$amount' }
  }},
  { $sort: { total: -1 } },
  { $limit: 5 }
]);

Secondary Indexes & AHIT

Secondary indexes are backed by the Adaptive Hybrid Index Tree (AHIT) — a self-optimizing structure that keeps hot entries in RAM and cold entries on disk.

AHIT Mechanics

Index Types

Full-Text Search

Inverted index with tokenization, English stemming, and TF-IDF scoring.

// Create full-text index
await articles.createIndex({ title: 'text', content: 'text' });

// Search with $text operator
const results = await articles.find({
  $text: { $search: 'database performance' }
});

Pipeline

Unicode word segmentation → Lowercase → Suffix stemming (-ing, -tion, -ness, -ment, -ly, -es, -ed, -s) → Token → Posting list with position tracking → TF-IDF scoring

Vector Search

Approximate/exact nearest neighbor search using cosine similarity on vector embeddings.

// Create vector index
await embeddings.createVectorIndex('vector', {
  dimensions: 1536,
  metric: 'cosine'
});

// Search
const similar = await embeddings.vectorSearch(
  [0.1, 0.2, /* ... 1536 dims */],
  10, // limit
  { category: 'science' } // optional filter
);

Geospatial

R-Tree based 2D spatial indexing for GeoJSON Point, LineString, Polygon, or [lng, lat] arrays.

// Create 2dsphere index
await restaurants.createGeoIndex('location');

// $geoWithin — bounding box
const nearby = await restaurants.find({
  location: {
    $geoWithin: {
      $centerSphere: [[-73.935, 40.731], 5 / 3963.2] // 5 mile radius
    }
  }
});

Autocomplete

Case-insensitive prefix search on indexed string fields.

const suggestions = await users.autocomplete('name', 'ali', 5);
// Returns: Alice, Ali, Alina, etc.

Storage Architecture

Blob Storage

Store large binary files (images, videos, documents) directly in the storage engine. Blobs are chunked into 256KB pages for efficient streaming.

const fs = await import('node:fs/promises');
const buffer = await fs.readFile('video.mp4');
const blobId = await db.putBlob(buffer);
console.log(`Saved blob: ${blobId}`);

const data = await db.getBlob(blobId);
if (data) await fs.writeFile('output.mp4', data);

Views

Logical views are stored queries that always read live data. Materialized views precompute results for faster reads.

// Logical view
await db.createView('active_users', {
  source: 'users',
  pipeline: [
    { $match: { active: true } },
    { $project: { name: 1, email: 1 } }
  ]
});

// Materialized view with scheduled refresh
await db.createView('daily_stats', {
  source: 'orders',
  pipeline: [{ $group: { _id: '$date', total: { $sum: 1 } } }],
  materializedOptions: { refresh: 'scheduled', schedule: '0 0 * * *' }
});

Relations & Foreign Keys

Define foreign-key-like relationships between collections with configurable referential integrity.

await db.defineRelation({
  from: 'posts.user_id',
  to: 'users._id',
  type: 'many-to-one',
  onDelete: 'cascade',     // Delete posts when user is deleted
  onUpdate: 'restrict',    // Prevent updating referenced user._id
  indexed: true            // Auto-create index on posts.user_id
});

// Set integrity mode: 'off' | 'soft' | 'strict'
await db.setReferentialIntegrity('strict');

Triggers

Execute JavaScript handlers on document events: beforeInsert, afterInsert, beforeUpdate, afterUpdate, beforeDelete, afterDelete.

await db.createTrigger('users', 'beforeInsert', async (doc, ctx) => {
  if (!doc.email) throw new Error('email is required');
  doc.createdAt = Date.now();
  return doc;
});

Document Versioning (Time Travel)

Natively track full document history, compute granular diffs, and perform non-destructive rollbacks.

// 1. Enable tracking
await users.enableVersioning({ 
  mode: 'diff', 
  maxVersions: 50 
});

// 2. Operations are saved as versions
await users.updateOne({ _id: 'u1' }, { $set: { role: 'admin' } });

// 3. View history and diffs
const history = await users.listVersions('u1');
const diff = await users.diffVersions('u1', 1, 2);

// 4. Rollback safely (creates a new version!)
await users.rollbackToVersion('u1', 1);

Versioning API

Change Streams

Real-time event streaming using MPSC channels. Events include Insert, Update, Replace, Delete, and Invalidate.

// Database-level watch
const dbStream = db.watch();
dbStream.on('change', (event) => {
  console.log(event.opType, event.namespace, event.fullDocument);
});

// Collection-level watch (filtered)
const colStream = users.watch();
colStream.on('change', (event) => {
  console.log('User changed:', event.opType);
});

Pragmas

Runtime configuration directives that persist across sessions in the Metadata Segment.

await db.pragma('foreign_keys', true);
await db.pragma('synchronous', 'full');
await db.pragma('cache_size', '1GB');
const mode = await db.pragma('synchronous'); // Read

Available Pragmas

foreign_keys synchronous auto_vacuum cache_size page_size journal_mode referential_integrity cross_db_transactions wal_checkpoint optimize integrity_check max_savepoint_depth materialized_view_size

Attached Databases

Attach additional .ovn files with aliases for cross-database queries.

await db.attach('analytics.ovn', 'analytics');
// Query attached database collections via aliased namespace
await db.detach('analytics');
const attached = await db.listAttached();

Access Control & ACL

Built-in security primitives for multi-tenant environments.

import { SecurityContext, checkPermission } from 'oblivinx3x';

const sec = new SecurityContext({
  permissions: new Map([
    ['users', new Set(['read', 'write'])],
    ['admin_logs', new Set(['read'])]
  ]),
  rateLimit: { reads: 100, writes: 50 },
  inputValidation: { maxDocumentDepth: 20, maxDocumentSize: 16 * 1024 * 1024 }
});

// Check permission
if (checkPermission(sec.permissions, 'users', 'read')) {
  // Allowed
}

Field-Level ACL

Control read/write access per field. Use filterDocumentByACL for reads and sanitizeDocumentByACL for writes.

Audit Logging

Immutable append-only log of database operations for compliance and debugging.

import { AuditLogger } from 'oblivinx3x';

const auditor = new AuditLogger({
  enabled: true,
  events: ['insert', 'update', 'delete']
});

auditor.log({
  operation: 'insert',
  collection: 'users',
  documentId: 'uuid-123',
  sessionId: 'sess-abc'
});

Input Validation

Protect against NoSQL injection and oversized payloads.

import { sanitizeInput, validateDepth, validateSize } from 'oblivinx3x';

// Validate document depth (default max: 20)
validateDepth(doc, 20);

// Validate document size (default max: 16MB)
validateSize(doc, 16 * 1024 * 1024);

// Full sanitization
sanitizeInput(doc, {
  maxDocumentDepth: 20,
  maxDocumentSize: 16 * 1024 * 1024,
  allowedFields: new Map([['users', ['name', 'email', 'age']]])
}, 'users');

Rate Limiter

Token bucket algorithm for per-collection read/write rate limiting.

import { RateLimiter, RateLimitedError } from 'oblivinx3x';

const limiter = new RateLimiter();
limiter.configure({ reads: 100, writes: 50 });

try {
  limiter.assertAllowed('users', 'write');
  await users.insertOne({ name: 'Alice' });
} catch (err) {
  if (err instanceof RateLimitedError) {
    console.log('Rate limit exceeded — try again later');
  }
}

Utilities & ID Generation

ID Strategies

import { generateId } from 'oblivinx3x';

// UUID v4 — random, globally unique
const uuid = generateId('uuid');

// Snowflake — time-ordered, distributed-friendly
const snowflake = generateId('snowflake', {
  snowflake: { workerId: 1, datacenterId: 0 }
});

// Auto-increment — per-collection monotonic
const inc = generateId('increment', { collection: 'users' });

Safe Serialization

import { safeSerialize, safeDeserialize, withRetry } from 'oblivinx3x';

// JSON with depth guard and circular reference detection
const json = safeSerialize(doc, 20);
const parsed = safeDeserialize(json);

// Retry with exponential backoff
const result = await withRetry(
  () => users.insertOne(doc),
  { maxAttempts: 3, backoffMs: 50 }
);

Export & Backup

// Export as JSON object
const data = await db.export();
console.log(data.users); // Array of documents

// Backup to JSON file (auto-checkpoints first)
await db.backup('backup-2026-04-10.json');

Explain & Diagnostics

// Explain a find query
const plan = await db.explain('users', { age: { $gt: 18 } });
console.log(plan.index);       // 'age_1' or null
console.log(plan.scanType);    // 'indexScan' | 'collectionScan' | 'coveredScan'
console.log(plan.estimatedCost);
console.log(plan.fallbackReason);

// Explain aggregation pipeline
const aggPlan = await db.explainAggregate('orders', [
  { $match: { status: 'completed' } },
  { $group: { _id: '$region', total: { $sum: 1 } } }
]);

OBE Format (Binary Encoding)

Oblivinx Binary Encoding — the compact binary format for document storage.

Document Structure

4-byte total length → 16-byte UUID → 8-byte txid → 1-byte tombstone flag → Varint field count → Encoded fields

Value Types (16 tags)

Background Workers

Automated maintenance tasks running on configurable intervals.

Error Codes