omedb

OmeDB

A simple, encrypted key-value database store.

Since Version 3.0.0, all functions now use promises. Either use async/await (recommended), or use .then. See Usage.

⚠️ Versions <2.0.0 (v1 Format Databases) are not compatible with >=2.0.0 (v2 Format Databases). As of 2.1.0, a migration tool has been added. See the Migration section for details.

⚠️ Installing globally will force all databases to use the same key.

Functions

• db.set(key, value) - Set a value in the database.
• db.get(key) - Get a value in the database.
• db.has(key) - Returns true if the key has an associated value or is listed in the database, false if it doesn't exist.
• db.delete(key) - Delete a value in the database.
• db.clear() - Clear all values in the database.
• db.add(key, amount) - Add a certain amount to a value in the database. Adds to 0 if a number isn't present.
• db.subtract(key, amount) - Subtract a certain amount from a value in the database. Subtracts from 0 if a number isn't present.
• db.push(key, value) - Pushes a value to an array. Makes a new array if an array isn't present.
• db.list(prefix) - Lists all keys in the database that starts with a specific prefix. Lists every key if prefix is ommited.

Installation:

npm install omedb

or using shorthand

npm i omedb

Importing:

Import with node require()

const OmeDB = require("omedb");
const db = new OmeDB()

Usage:

const OmeDB = require("./index.js") // Imports the database.
const db = new OmeDB() // Initialises the database.

/*
==========================
ASYNCHRONOUS (RECOMMENDED)
==========================
*/

async function blah() { // This is not needed, just make sure you are running in an asynchronous function.
	await db.clear() // Deletes all items in database.
	await db.set("string", "A cool string!") // Sets a value in the database.
	console.log(await db.get("string")) // A cool string!
	
	/* --------------- Arrays --------------- */

	console.log(await db.get("items")) // undefined
	await db.push("items", "Sword") // Adds "Sword" to an array (is created if doesn't exist)
	console.log(await db.get("items")) // [ 'Sword' ]
	await db.push("items", "Coffee") // Adds "Coffee" to the array.
	console.log(await db.get("items")) // [ 'Sword', 'Coffee' ]

	/* --------------- Numbers --------------- */

	await db.set("number", 31) // Sets "number" to 31.
	console.log(await db.get("number")) // 31
	await db.add("number", 10.5) // Adds 10.5 to "number" (if entry doesn't exist, it adds to 0.)
	console.log(await db.get("number")) // 41.5
	await db.subtract("number", 23) // Subtracts 23 from "number" if entry doesn't exist, it subtracts from 0.)
	console.log(await db.get("number")) // 18.5

	/* --------------- Database --------------- */

	console.log(await db.list()) // Every key in the database, in our case it would be: ["string", "items", "number"], which could be iterated through and the value would be retrieved by using db.get(key).
	// Setting entries for next example.
	await db.set("entry1", "Hello!")
	await db.set("entry2", "This is a")
	await db.set("entry3", "database example")
	await db.set("entry4", "where keys are listed")
	await db.set("entry5", "by a prefix!")
	
	console.log(await db.list('entry')) // Lists all keys starting with a specific prefix, in our case the prefix "entry" which would return: ["entry1", "entry2", "entry3", "entry4", "entry5"]. 

	console.log(await db.has("entry5")) // true, as "entry5" exists within the database.
	console.log(await db.has("entry6")) // false, as we have not yet added "entry6" to our database.

	await db.delete("entry5") // returns with "true" if deletion was successful, "false" if it couldn't be deleted, or "undefined" if it does not exist.
}

blah();

/*
==========================
SYNCHRONOUS (USING .then().)
==========================
*/

db.clear() // Deletes all items in database.
db.set("string", "A cool string!") // Sets a value in the database.
db.get("string").then(value => {
	console.log(value) // A cool string!
})

/* --------------- Arrays --------------- */

db.get("items").then(value => {
	console.log(value) // undefined
	db.push("items", "Sword") // Adds "Sword" to an array (is created if doesn't exist)
	db.get("items").then(value => {
		console.log(value) // [ 'Sword' ]
		db.push("items", "Coffee").then(value => { // Adds "Coffee" to the array.
			db.get("items").then(value => {
				console.log(value) // [ 'Sword', 'Coffee' ]
			})
		})
	})
})

/* --------------- Numbers --------------- */

db.set("number", 31) // Sets "number" to 31.
db.get("number").then(value => {
	console.log(value) // 31
	db.add("number", 10.5)// Adds 10.5 to "number" (if entry doesn't exist, it adds to 0.)
	db.get("number").then(value => {
		console.log(value) // 41.5
		db.subtract("number", 23) // Subtracts 23 from "number" if entry doesn't exist, it subtracts from 0.)
		db.get("number").then(value => {
			console.log(value) // 18.5
		})
	})
})

/* --------------- Database --------------- */

db.list().then(value => {
	console.log(db.list()) // Every key in the database, in our case it would be: ["string", "items", "number"], which could be iterated through and the value would be retrieved by using db.get(key).
})
// Setting entries for next example.

db.set("entry1", "Hello!")
db.set("entry2", "This is a")
db.set("entry3", "database example")
db.set("entry4", "where keys are listed")
db.set("entry5", "by a prefix!")

db.list('entry').then(value => {
	console.log(db.list('entry')) // Lists all keys starting with a specific prefix, in our case the prefix "entry" which would return: ["entry1", "entry2", "entry3", "entry4", "entry5"].
})

db.has("entry5").then(value => {
	console.log(value) // true, as "entry5" exists within the database.
})

db.has("entry6").then(value => {
	console.log(value) // false, as we have not yet added "entry6" to our database.
})

db.delete("entry5") // returns with "true" if deletion was successful, "false" if it couldn't be deleted, or "undefined" if it does not exist.

Migration

To migrate a v1 Database to a v2 Database, use the following code.

const OmeDB = require("omedb")
const migrate = OmeDB.migrate

migrate() // Any errors will be printed in console.
console.log(db.list()) // OPTIONAL: Used to check whether or not migration was successful.

For configuration, use this format:

migrate(old file, new file)

Excluding any arguments will default them to the following: migrate("omedb.odb", "db.odb")

For example:

migrate("olddatabase.odb", "newdatabase.odb")
migrate("dbv1.odb", "dbv2.odb")
migrate("hello.odb", "world.odb")

API

Versions >=3.0.0 have an API and a wrapper for said API. This is designed for databases running off a different server. Regular OmeDB will work seamlessly with the API.

Exposing the API:

var OmeDB = require("omedb")
var api = new OmeDB.api()
api.listen(3000) // Listens on port 3000 or the specified port. Defaults to 3654.

// Code here...

Using the Wrapper:

var Wrapper = require("omedb").wrapper
const db = new Wrapper("localhost", '3000') // Connects to API on localhost:3000. Make sure the port is the same as the API. Defaults to localhost:3654.

// Use DB as normal.

Support Links:

Official Discord Server

Changelog

Version 1.0.0

• Initial Release

Version 2.0.0

• Completely reworked the code, and database encryption is handled differently.
• Database key is now stored elsewhere, so we advise not to upgrade until a tool has been developed to migrate your old v1 database. If security is important, join our support server (link above, or click here), and we will guide you to migrate manually. Added. See Migration.
• Due to how the key is stored, please ensure that Node has permissions to modify the node_modules folder, the database will not function otherwise, without compromising security.
• Also due to how the key is stored, do not install globally, unless you want all databases to use the same key for encryption.
• One file is now only needed, excluding where the key is stored (which will not be stored in the root of the project).

Version 2.1.0

• v1 Database migration added.
• Couple changes to allow v2 Database to function with migrated database data.

Version 3.0.0

• Added an API endpoint (requires extra setup, see API)
• Added a Wrapper for aforementioned API.
• Database code now operates on Promises, as such pre-existing code needs to be modified and updated to work with >=3.0.0
• Updated Usage section to reflect above change.

Version 3.0.1

• Fixed API examples.