NebulaDB Documentation

Welcome to the NebulaDB documentation. This guide will help you get started with NebulaDB and explore its features.

Table of Contents

  1. Introduction
  2. Installation
  3. Core Concepts
  4. Performance Optimizations
  5. API Reference
  6. Adapters
  7. Plugins
  8. Examples
  9. Advanced Usage

Introduction

NebulaDB is a high-performance, reactive, TypeScript-first, schema-optional, embeddable NoSQL database that runs in the browser, Node.js, and Edge environments. It features advanced indexing, optimized query processing, modular adapters for persistence, reactive live queries, extensibility via plugins, and blazing-fast in-memory operations with adaptive concurrency control.

Key Features

Installation

# Install core package
npm install @nebula/core

# Install adapters as needed
npm install @nebula/adapter-memory
npm install @nebula/adapter-localstorage
npm install @nebula/adapter-indexeddb
npm install @nebula/adapter-filesystem

# Install plugins as needed
npm install @nebula/plugin-encryption
npm install @nebula/plugin-validation
npm install @nebula/plugin-versioning

Core Concepts

Database

The database is the main entry point to NebulaDB. It manages collections and provides methods for persistence.

import { createDb } from '@nebula/core';
import { MemoryAdapter } from '@nebula/adapter-memory';

const db = createDb({
  adapter: new MemoryAdapter(),
  // Enable performance optimizations
  queryCache: { enabled: true, maxSize: 100 },
  compression: { enabled: true, threshold: 1024 },
  concurrency: { enabled: true, initialConcurrency: 4 }
});

Collections

Collections are containers for documents. They provide methods for CRUD operations.

// Create a collection with indexes for better performance
const users = db.collection('users', {
  indexes: [
    { name: 'id_idx', fields: ['id'], type: 'unique' },
    { name: 'age_idx', fields: ['age'], type: 'single' }
  ]
});

Documents

Documents are JSON objects with a unique id field.

const user = {
  id: '1',
  name: 'Alice',
  age: 30,
  email: 'alice@example.com'
};

Queries

Queries are used to filter documents in a collection. NebulaDB supports a MongoDB-like query syntax.

// Find users over 25
const results = await users.find({ age: { $gt: 25 } });

// Find users with a specific name
const alice = await users.findOne({ name: 'Alice' });

// Complex queries
const results = await users.find({
  $and: [
    { age: { $gt: 25 } },
    { tags: { $in: ['developer'] } }
  ]
});

Updates

Updates modify documents in a collection. NebulaDB supports update operators like $set, $unset, $inc, etc.

// Update a user's age
await users.update(
  { id: '1' },
  { $set: { age: 31 } }
);

// Increment a counter
await users.update(
  { id: '1' },
  { $inc: { loginCount: 1 } }
);

Reactivity

NebulaDB supports reactive queries that update in real-time when data changes.

// Subscribe to changes in users over 30
const unsubscribe = users.subscribe(
  { age: { $gt: 30 } },
  (results) => {
    console.log('Users over 30:', results);
  }
);

// Later, unsubscribe when no longer needed
unsubscribe();

Performance Optimizations

NebulaDB includes several performance optimizations to ensure fast and efficient operation, even with large datasets:

Advanced Indexing

// Create a collection with indexes
const users = db.collection('users', {
  indexes: [
    { name: 'id_idx', fields: ['id'], type: 'unique' },
    { name: 'age_idx', fields: ['age'], type: 'single' },
    { name: 'name_age_idx', fields: ['name', 'age'], type: 'compound' },
    {
      name: 'active_users_idx',
      fields: ['lastActive'],
      type: 'single',
      options: {
        partial: { filter: { active: true } }
      }
    }
  ]
});

Query Optimization

// Configure query cache
const db = createDb({
  adapter: new MemoryAdapter(),
  queryCache: {
    enabled: true,
    maxSize: 100,  // Cache up to 100 queries
    ttlMs: 30000   // Cache entries expire after 30 seconds
  }
});

Batch Operations

// Batch insert
await users.insertBatch([
  { id: '1', name: 'Alice', age: 30 },
  { id: '2', name: 'Bob', age: 25 },
  { id: '3', name: 'Charlie', age: 35 }
]);

// Batch update
await users.updateBatch(
  [{ id: '1' }, { id: '2' }],
  [{ $set: { active: true } }, { $set: { active: false } }]
);

// Batch delete
await users.deleteBatch([{ id: '3' }]);

Memory Management

// Configure document compression
const db = createDb({
  adapter: new MemoryAdapter(),
  compression: {
    enabled: true,
    threshold: 1024,  // Compress documents larger than 1KB
    level: 6          // Compression level (1-9)
  }
});

// Process large datasets in chunks
await users.processInChunks(async (docs) => {
  // Process each chunk of documents
  return docs.map(doc => ({ ...doc, processed: true }));
});

Adaptive Concurrency

// Configure adaptive concurrency
const db = createDb({
  adapter: new MemoryAdapter(),
  concurrency: {
    enabled: true,
    initialConcurrency: 4,  // Start with 4 concurrent operations
    minConcurrency: 1,      // Minimum concurrency level
    maxConcurrency: 16,     // Maximum concurrency level
    targetLatency: 50       // Target latency in ms
  }
});

API Reference

For detailed API documentation, see the API Reference.

Adapters

NebulaDB supports multiple storage adapters:

For more information, see the Adapters Guide.

Plugins

NebulaDB can be extended with plugins:

For more information, see the Plugins Guide.

Examples

For example applications, see the Examples.

Advanced Usage

For advanced usage scenarios, see the Advanced Usage Guide.