Em-DB

A high-performance, TypeScript-first embedded key-value store for Node.js with multiple storage adapters and 100% test coverage.

Features

• ✅ TypeScript Support: Full TypeScript definitions and type safety
• ✅ 100% Test Coverage: Comprehensive test suite with 100% code coverage
• ✅ Multiple Adapters: JSON, CompressedJSON, File, and CompressedFile storage
• ✅ High Performance: Optimized for speed and memory usage
• ✅ Zero Dependencies: No external runtime dependencies
• ✅ Auto-sync: Automatic data persistence with configurable intervals
• ✅ Process Cleanup: Automatic data sync on process exit
• ✅ Flexible Storage: Support for both string and Buffer values
• ✅ Pre-commit Hooks: Automated testing and linting

Installation

npm install embedded-db

Or with Bun:

bun add embedded-db

Quick Start

TypeScript/ES Modules

import { EmDB } from '@bugless/em-db';
import { JSONAdapter } from '@bugless/em-db/adapters/JSON-Adapter';

// Create database with default settings
const db = new EmDB('./data.db');

// Basic operations
db.put('user:1', 'John Doe');
db.put('user:2', Buffer.from('Jane Smith'));

const user1 = db.get('user:1'); // 'John Doe'
const user2 = db.get('user:2'); // Buffer

// Get all keys and size
const keys = db.keys(); // ['user:1', 'user:2']
const size = db.size(); // 2

// Auto-sync (data is automatically persisted)
db.open(); // Start auto-sync every 1 second
db.close(); // Stop auto-sync and final sync

CommonJS

const { EmDB } = require('@bugless/em-db');
const { CompressedJSONAdapter } = require('@bugless/em-db/adapters/CompressedJSON-Adapter');

const db = new EmDB('./data.db', {
  adapter: CompressedJSONAdapter,
  verbose: true
});

db.put('key', 'value');
const value = db.get('key');

Storage Adapters

Node-EmDB supports multiple storage adapters for different use cases:

JSONAdapter

• Use case: Simple key-value storage
• Storage: Single JSON file
• Pros: Human-readable, simple
• Cons: No compression, slower for large datasets

import { JSONAdapter } from '@bugless/em-db/adapters/JSON-Adapter';

const db = new EmDB('./data.json', { adapter: JSONAdapter });

CompressedJSONAdapter (Default)

• Use case: General-purpose storage with compression
• Storage: Single compressed JSON file
• Pros: Space-efficient, good performance
• Cons: Not human-readable

import { CompressedJSONAdapter } from '@bugless/em-db/adapters/CompressedJSON-Adapter';

const db = new EmDB('./data.db', { adapter: CompressedJSONAdapter });

FileAdapter

• Use case: File-based storage, one file per key
• Storage: Directory with individual files
• Pros: Easy to browse, good for large values
• Cons: Many small files, slower for many keys

import { FileAdapter } from '@bugless/em-db/adapters/File-Adapter';

const db = new EmDB('./data-dir', { adapter: FileAdapter });

CompressedFileAdapter

• Use case: File-based storage with compression
• Storage: Directory with compressed files
• Pros: Space-efficient, good for large values
• Cons: Many files, not human-readable

import { CompressedFileAdapter } from '@bugless/em-db/adapters/CompressedFile-Adapter';

const db = new EmDB('./data-dir', { adapter: CompressedFileAdapter });

API Reference

EmDB Class

Constructor

constructor(dbPath: string, dbOpts?: EmDBOptions)

Parameters:

• dbPath: string - Path to the database file or directory
• dbOpts?: EmDBOptions - Database options

EmDBOptions

interface EmDBOptions {
  append_if_exists?: boolean;    // Append to existing data (default: true)
  verbose?: boolean;            // Enable verbose logging (default: false)
  adapter?: AdapterConstructor; // Storage adapter class (default: CompressedJSONAdapter)
  appendMode?: boolean;         // Enable append mode for deserialization
}

Methods

put(key: string, val: string | Buffer): void

Stores a value with the given key.

Parameters:

• key: string - The key to store the value under
• val: string | Buffer - The value to store

get(key: string): string | Buffer | undefined

Retrieves a value by key.

Parameters:

• key: string - The key to retrieve

Returns: The stored value or undefined if not found

keys(): string[]

Returns an array of all keys in the database.

Returns: Array of key strings

size(): number

Returns the number of key-value pairs in the database.

Returns: Number of entries

sync(): void

Manually synchronizes data to disk.

open(): void

Starts automatic synchronization every 1 second.

close(): void

Stops automatic synchronization and performs final sync.

Development

Prerequisites

• Node.js >= 12.0.0
• npm >= 6.0.0

Setup

git clone https://github.com/serendipious/Node-EmDB.git
cd Node-EmDB
npm install

Available Scripts

# Build the project
npm run build

# Build in watch mode
npm run build:watch

# Run tests with Jest
npm test

# Run tests with Bun
npm run test:bun

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run benchmark with Node.js
npm run benchmark

# Run benchmark with Bun
npm run benchmark:bun

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Clean build artifacts
npm run clean

Test Coverage

This project maintains 100% test coverage across all metrics:

• Lines: 100%
• Functions: 100%
• Branches: 100%
• Statements: 100%

Coverage reports are generated in the coverage/ directory and can be viewed by running:

npm run test:coverage:report

Performance

The library is optimized for high performance:

• Put Operations: ~0.1-1ms per operation
• Get Operations: ~0.05-0.5ms per operation
• Memory Usage: Minimal, with efficient data structures
• Bundle Size: ~5KB minified and gzipped

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Please see our CONTRIBUTING.md guide for details on how to contribute to this project.

Changelog

v1.0.0

• BREAKING: Migrated to TypeScript with full type safety
• Added comprehensive test coverage (100%)
• Added multiple storage adapters (JSON, CompressedJSON, File, CompressedFile)
• Added pre-commit hooks for quality assurance
• Enhanced documentation and examples
• Added performance optimizations
• Added process cleanup handling
• Added automatic data synchronization