',
})
} catch (err) {
console.error('Init Error:', err.message);
process.exit(1);
}
```
### Encryption Methods
- `aes-128-cbc` (16 bytes) - 32 hex characters
- `aes-192-cbc` (24 bytes) - 48 hex characters
- `aes-256-cbc` (32 bytes) - 64 hex characters
- `aes-128-gcm` (16 bytes) - 32 hex characters
- `aes-256-gcm` (32 bytes) - 64 hex characters
### Example Configuration
```js
const eveloDB = require('evelodb')
let db
try {
db = new eveloDB({
extension: 'db',
encryption: 'aes-256-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef' // 64 hex characters
})
} catch (err) {
console.error('Init Error:', err.message);
process.exit(1);
}
```
### Generate Hex Key
Using EveloDB inbuild method
```js
const length = 32 // 32, 48, 64
const key = db.generateKey(length)
console.log(key)
```
Using Crypto JS
```js
const crypto = require('crypto');
const key = crypto.randomBytes(16).toString('hex'); // 32 hex chars
console.log(key);
```
# ๐ Change Configuration
- Note: If you are using the config, you can use the same instance of the database.
- If you change the encryption / encryptionKey / extension or directory, your current db files and data was initialized with the old config will be corrupted and cannot be read.
- Solution for change configuration, use `changeConfig()` method. It can change your current db config to new config and continue normally after initialize again with new config .
-
- Eg: Converting my current
`aes-256-cbc` encrypted .json database from './evelodatabase' to `aes-128-cbc` and .db with new key and './database' directory.
```js
const res = db.changeConfig({
from: {
directory: './evelodatabase',
extension: 'json',
encryption: 'aes-256-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
},
to: {
directory: './database',
extension: 'db',
encryption: 'aes-128-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef' // 32 hex characters
},
collections: ['users', 'accounts'] // if not set collections, convert all collections
})
console.log(res)
// { success: true, converted: 2, failed: 0 }
// Initialize again
try {
db = new eveloDB({
directory: './database',
extension: 'db',
encryption: 'aes-128-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef'
});
} catch (err) {
console.error('Re-init Error:', err.message);
}
```
If you remove `encryption` and `encryptionKey` parameters in `to` object, it will remove the encryptions in your database and continue with json string.
```js
const res = db.changeConfig({
from: {
encryption: 'aes-256-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
},
to: {}
})
```
# โ
Testing with Examples
- Copy `test.js` file to your project directory and run:
Show Script
```js
// This is a test file for the EveloDB module.
const eveloDB = require('evelodb');
let db
// Initialize DB
try {
db = new eveloDB({
extension: 'db',
noRepeat: true,
encode: 'json',
autoPrimaryKey: 'key' // auto incrementing key
// Start unencrypted to test conversion
});
} catch (err) {
console.error('Init Error:', err.message);
process.exit(1);
}
// ===== TEST FLOW =====
const testUser = { name: 'John Doe', age: 30 };
const query = { age: 30 };
const new_query = { age: 40 };
const search_query = { name: 'Joh' };
let createdId;
// Create Data
console.log('\nโ
Create Data');
try {
const res = db.create('users', testUser);
createdId = res.__id;
console.log(`Create Result:`, res);
} catch (err) {
console.error('Create Error:', err.message);
}
// Find Data
console.log('\n๐ Find Before Conversion');
try {
const res = db.find('users', query);
console.log(`Find Result:`, res);
} catch (err) {
console.error('Find Error:', err.message);
}
// Search Data
console.log('\n๐ Search by a piece of value');
try {
const res = db.search('users', search_query);
console.log(`Find Result:`, res);
} catch (err) {
console.error('Find Error:', err.message);
}
// Convert to encrypted format
console.log('\n๐ Convert to Encrypted Format');
try {
const res = db.changeConfig({
from: {},
to: {
encryption: 'aes-128-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef'
}
});
console.log('Conversion Result:', res);
} catch (err) {
console.error('Conversion Error:', err.message);
}
// Initialize with new config
try {
db = new eveloDB({
directory: './evelodatabase',
extension: 'db',
noRepeat: true,
encryption: 'aes-128-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef'
});
} catch (err) {
console.error('Re-init Error:', err.message);
}
// Find Data Again
console.log('\n๐ Try Reading Encrypted With New DB Config');
try {
const res = db.find('users', query);
console.log(`Find Result:`, res);
} catch (err) {
console.error('Find Error:', err.message);
}
// Edit Data
console.log('\n๐ Editing data');
try {
const res = db.edit('users', query, new_query);
console.log(`Editing Result:`, res);
} catch (err) {
console.error('Edit Error:', err.message);
}
// Find Data Again
console.log('\n๐ Find old object again after edit');
try {
const res = db.find('users', query);
console.log(`Find Result:`, res);
} catch (err) {
console.error('Find Error:', err.message);
}
// Find Data Again
console.log('\n๐ Find new object again after edit');
try {
const res = db.find('users', new_query);
console.log(`Find Result:`, res);
} catch (err) {
console.error('Find Error:', err.message);
}
// Convert config back to plain JSON
console.log('\n๐ Convert Back to Plain JSON');
try {
const res = db.changeConfig({
from: {
encryption: 'aes-128-cbc',
encryptionKey: '0123456789abcdef0123456789abcdef'
},
to: {}
});
console.log('Conversion Result:', res);
} catch (err) {
console.error('Conversion Error:', err.message);
}
// Initialize with new config
try {
db = new eveloDB({
extension: 'db',
noRepeat: true
});
} catch (err) {
console.error('Re-init Error:', err.message);
}
// Delete Data
console.log('\n๐งน Clean Up');
try {
const res = db.delete('users', new_query);
console.log(`Delete Result:`, res);
} catch (err) {
console.error('Delete Error:', err.message);
}
// Reset collection
console.log('\n๐งน Drop Collection')
try {
const res = db.drop('users');
console.log(`Drop Result:`, res);
} catch (err) {
console.error('Drop Error:', err.message);
}
```
# ๐ Use BSON encoded
> ### Binary Serialized Object Notation with EveloDB
- EveloDB can handle both JSON and BSON encoded data. Here's how to use BSON encoded data with eveloDB:
- JSON use string for keys, while BSON use ObjectId for keys.
- โ ๏ธ Note: BSON encoding doesn't support encryption. It allways unreadable.
### Configuration with BSON encoding
```js
const eveloDB = require('evelodb')
let db
try {
db = new eveloDB({
directory: './evelodatabase',
extension: 'db', // default 'bson'
encode: 'bson',
})
} catch (err) {
console.error('Init Error:', err.message);
process.exit(1);
}
```
- `encode: 'bson'` for BSON encoding
- `encode: 'json'` for JSON encoding (default)
## Benchmark test JSON vs BSON
Show Result
Source code:
```js
const eveloDB = require('evelodb');
let db
const test = 'json' // 'json' or 'bson'
try {
db = new eveloDB({
extension: test,
encode: test
});
} catch (err) {
console.error('Init Error:', err.message);
process.exit(1);
}
const testUser = {
name: 'John Doe',
age: 40,
photo: '[ 96MB base64 image string and test ]',
}
// Create Data
function createData() {
console.log('\nโ
Create Data');
try {
db.create('users', testUser);
} catch (err) {
console.error('Create Error:', err.message);
}
}
// Find Data
function findData() {
let startTime = Date.now();
try {
const res = db.find('users', { name: 'John Doe' });
if (res.length > 0) {
const t = Date.now() - startTime;
console.log(`Find Result Time taken: ${t}ms - ${test.toLocaleUpperCase()}`);
}
} catch (err) {
console.error('Find Error:', err.message);
}
}
for (let i = 0; i < 180; i++) {
createData()
}
findData()
```
Result:
```bash
680KB -> Find Result Time taken: 1ms - JSON
680KB -> Find Result Time taken: 4ms - BSON
19157KB -> Find Result Time taken: 40ms - JSON
17331KB -> Find Result Time taken: 50ms - BSON
```
After trying to create 210+ data - result:
```js
for (let i = 0; i < 210; i++) {
createData()
}
```
```bash
20115KB -> Find Result Time taken: 41ms - JSON
BSON -> Create Error: The value of "offset" is out of range. It must be >= 0 && <= 17825792. Received 17825794
```
## Why JSON is faster than BSON?
- BSON requires binary decode `BSON.deserialize` before JS can use it.
- JSON uses `JSON.parse`, which is highly optimized in V8 (Node.js engine).
- BSON spec has a hard cap: 16,777,216 bytes (~16MB) per document.
# ๐ก Features
- โ JSON-based storage
- โ BSON-based storage
- โ AES Encryption
- โ Custom path and extension
- โ B-Tree indexing
- โ Fast retrieval
- โ No Repeat option
- โ Auto Primary Key option
Copyright 2024 ยฉ Evelocore - All rights reserved
Developed by K.Prabhasha
