milodb/README.md

A simple mini database with optional encryption to store key-value pairs

# milodb

A simple mini database with optional encryption to store key-value pairs. Features include encryption, TTL support, batch operations, and advanced search capabilities.

## Installation

```bash
npm install milodb
```

## Usage

```javascript
const MinoDB = require('milodb');

// Initialize with an optional password for encryption and flag to enable/disable encryption
const db = new MinoDB('my-secret-password', true); // true to encrypt data

// Basic operations
await db.set('name', 'John Doe');
console.log(await db.get('name'));  // Output: John Doe

// Set with TTL (Time To Live) in milliseconds
await db.set('temp', 'This will expire', 3600000); // Expires in 1 hour

// Delete an entry
await db.delete('name');
console.log(await db.get('name'));  // Output: null

// Clear all entries
await db.clear();

// Advanced search with options
const results = await db.search('John', {
    regex: false,        // Use regex for searching
    caseSensitive: false, // Case-sensitive search
    limit: 10           // Limit number of results
});

// Batch operations
const batchResults = await db.batch([
    { type: 'set', key: 'key1', value: 'value1', ttl: 3600000 },
    { type: 'set', key: 'key2', value: 'value2' },
    { type: 'delete', key: 'key3' }
]);

// Get database statistics
const stats = await db.stats();
console.log(stats);
// Output: { total: 2, expired: 0, active: 2 }
```

## Features:
- Secure encryption using AES-256-GCM with salt
- TTL (Time To Live) support for entries
- Async operations (set, get, delete, list, search)
- Batch operations support
- Advanced search with regex and case-sensitivity options
- Automatic cleanup of expired entries
- Database statistics
- Store data in a JSON file
- Proper error handling and validation
- Lazy initialization for better performance

## Security Features:
- Uses PBKDF2 for key derivation
- Implements salt for each encryption
- Uses AES-256-GCM for authenticated encryption
- Proper IV handling
- Input validation

## Performance Characteristics

The database is designed for simplicity and ease of use, with some performance considerations:

### Memory Usage
- All data is loaded into memory when the database is initialized
- Memory usage scales linearly with the number of entries and their size
- Typical memory usage: ~100-200 bytes per entry (for small values)

### Performance Limits
- Recommended for up to 100,000 entries with small values
- Can handle up to 1 million entries, but with increased memory usage and slower operations
- Not recommended for very large values (>1MB) or millions of entries

### Benchmark
A benchmark script is included to test performance with large datasets:

```bash
node benchmark/benchmark.js
```

The benchmark will:
- Insert 1 million key-value pairs
- Measure insertion time and memory usage
- Verify sample values
- Clean up the test database

### Performance Tips
1. Use batch operations for multiple writes
2. Keep values small when possible
3. Use TTL to automatically clean up old data
4. Consider using a more robust database for:
   - Millions of entries
   - Very large values
   - High-frequency writes
   - Distributed systems

## Error Handling:
The database will throw errors for:
- Invalid key types (must be string)
- Empty keys
- Undefined values
- Missing password when encryption is enabled
- Invalid encryption/decryption operations

## License
MIT