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

``bash
npm install embedded-db
`

Or with Bun:

`bash
bun add embedded-db
`

Quick Start

$3

`typescript
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
`

$3

`javascript
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:

$3

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

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

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

$3

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

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

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

$3

- 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

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

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

$3

- 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

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

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

API Reference

$3

#### Constructor

`typescript
constructor(dbPath: string, dbOpts?: EmDBOptions)
`

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

#### EmDBOptions

`typescript
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

$3

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

$3

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

$3

`bash


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
`

$3

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:

`bash
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

$3

- 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