@lumoproject/endb v0.21.3

🗃 Simple key-value storage with support for multiple backends.

If you have any questions or if you are experiencing issues with Endb, please do not hesitate to join our official Discord.

Features

• Easy-to-use: Endb has a simplistic and easy-to-use promise-based API.
• Adapters: By default, data is stored in memory. Optionally, install and utilize an "storage adapter".
• Third-Party Adapters: You can optionally utilize third-party adapters or build your own.
• Namespaces: Namespaces isolate elements within a database to enable useful features.
• Custom Serializers: Utilizes its own data serialization methods to ensure consistency across different backends.
• Embeddable: Designed to be easily embeddable inside modules.
• Data Types: Handles all the JSON types including Buffer.
• Error-Handling: Connection errors are sent through, from the adapter to the main instance; connection errors will not exit or kill the process.

Installation

$ npm install endb

By default, data is stored in memory. Optionally, install and utilize an "storage adapter". Officially supported adapters are LevelDB, MongoDB, NeDB, MySQL, PostgreSQL, Redis, and SQLite.

$ npm install level # LevelDB
$ npm install mongojs # MongoDB
$ npm install nedb # NeDB
$ npm install ioredis # Redis

# To use SQL database, an additional package 'sql' must be installed and an adapter
$ npm install sql

$ npm install mysql2 # MySQL
$ npm install pg # PostgreSQL
$ npm install sqlite3 # SQLite

Usage

// Import/require the package.
const Endb = require('endb');

const endb = new Endb();
const endb = new Endb({
    // One of the following
    uri: 'leveldb://path/to/database',
    uri: 'mongodb://user:pass@localhost:27017/dbname',
    uri: 'mysql://user:pass@localhost:3306/dbname',
    uri: 'postgresql://user:pass@localhost:5432/dbname',
    uri: 'redis://user:pass@localhost:6379',
    uri: 'sqlite://path/to/database.sqlite'
});

// Handles connection errors
endb.on('error', error => console.error('Connection Error: ', error));

await endb.set('foo', 'bar'); // true
await endb.get('foo'); // 'bar'
await endb.has('foo'); // true
await endb.all(); // [ { key: 'foo', value: 'bar' } ]
await endb.delete('foo'); // true
await endb.clear(); // undefined

Namespaces

Namespaces isolate elements within a database, avoid key collisions, separate elements by prefixing the keys, and allow clearance of only one namespace while utilizing the same database.

const users = new Endb({ namespace: 'users' });
const members = new Endb({ namespace: 'members' });

await users.set('foo', 'users'); // true
await members.set('foo', 'members'); // true
await users.get('foo'); // 'users'
await members.get('foo'); // 'members'
await users.clear(); // undefined
await users.get('foo'); // undefined
await members.get('foo'); // 'members'

Third-Party Adapters

You can optionally utilize third-party storage adapters or build your own. Endb will integrate the third-party adapter and handle complex data types internally.

const myAdapter = require('./my-adapter');
const endb = new Endb({ store: myAdapter });

For example, quick-lru is an unrelated module that has an API similar to that of Endb.

const QuickLRU = require('quick-lru');

const lru = new QuickLRU({ maxSize: 1000 });
const endb = new Endb({ store: lru });

Custom Serializers

Endb handles all the JSON data types including Buffer using its own data serialization methods that encode Buffer data as a base64-encoded string, and decode JSON objects which contain buffer-like data (either as arrays of strings or numbers) into Buffer instances to ensure consistency across different backends.

Optionally, pass your own data serialization methods to support extra data types.

const endb = new Endb({
    serialize: JSON.stringify,
    deserialize: JSON.parse
});

Warning: Using custom serializers means you lose any guarantee of data consistency.

Embeddable

Endb is designed to be easily embeddable inside modules. It is recommended to set a namespace for the module.

class MyModule {
    constructor(options) {
        this.db = new Endb({
            uri: typeof opts.store === 'string' && opts.store,
			store: typeof opts.store !== 'string' && opts.store
            namespace: 'mymodule'
        });
    }
}

// Caches data in the memory by default.
const myModule = new MyModule();

// After installing ioredis.
const myModule = new MyModule({ store: 'redis://localhost' });
const myModule = new AwesomeModule({ store: thirdPartyAdapter });

Links

• Documentation
• Discord
• GitHub
• NPM