@un-index/kv-abstraction

kv-abstraction - an easy to use key-value database interface that uses SQL under the hood

Make sure to read the licence's terms before usage

If you've got any uses for this, please email me here so I can put them up: [e-mail]

This was created as a personal project that offers no particular benefit to usage over existing developed relational database interfaces, although it may prove useful for small projects (may) where speed is not the biggest concern. If you have any suggestions or improvements regardless of its usage, please send a pull request! (quick responses are not guaranteed)

API Reference

API Reference can also be found at https://un-index.github.io/kv-abstraction/global.html

Github: https://github.com/Un-index/kv-abstraction/blob/main/README.md

runkit: https://npm.runkit.com/%40un-index%2Fkv-abstraction

Objects

obj : object

_internalDataStoreObject : object

Typedefs

DataStoreObject : Object

Note: Detailed documentation exists separately for each method, read that if you want.

GetCallback : function

callback to be executed once a value is retrieved for a specified key by _internalDataStoreObject.Get

obj : object

Kind: global namespace

obj.GetDataStore(dataStoreName, [hostname], user, pass, dbName, [portName], debug) ⇒ DataStoreObject

creates and returns a _internalDataStoreObject object with the specified configurations, the created connection can be terminated via _internalDataStoreObject.Destroy()

Kind: static method of obj Returns: _internalDataStoreObject - internal DataStoreObject

Param	Type	Default	Description
dataStoreName	string		specifies the DataStore's name, under the hood this causes an SQL query to create a table with the specified name (that is, if the table doesn't already exist). Note that this is different from the parameter: dbName
[hostname]	string	"localhost"	specifies the hostname of the MySQL database to connect to; Default: localhost. This hostname is given to you by your DataBase provider; for e.g, when using db4free.net your hostname would be db4free.net
user	string		The MySQL user to authenticate as
pass	string		The password of the MySQL user specified by the parameter: user
dbName	string		The name of the database to use for this connection. Note that this is different from the parameter: dataStoreName
[portName]	string	"3306"	The port number to user for this connection; Default: 3306
debug	boolean		specifies whether to activate debug mode for this connection. Can be true/false or an array of string packet type names that should be printed; Default: false. Packet type names can be either ComQueryPacket, RowDataPacket, COM_QUIT etc.

_internalDataStoreObject : object

Kind: global namespace

• _internalDataStoreObject : object
  • .Set(key, value) ⇒ any
  • .GetAsync(key) ⇒ Promise
  • .Get(key, callback) ⇒ any
  • .Destroy() ⇒ void

_internalDataStoreObject.Set(key, value) ⇒ any

saves a value to the specified key (if it's an object then it will be converted to an SQL friendly syntax for you, just pass your object (array, table etc.) to _internalDataStoreObject.Get and it'll take care of the rest )

Kind: static method of _internalDataStoreObject Returns: any - value - returns the specified value back

Param	Type	Description
key	string	the key to associate a value with
value	any	the value to associate with the specified key; objects are serialized to strings automatically but in the end the string can have a maximum of 4,000,000 characters before saving

Example

let kv = require("kv-abstraction");
let DataStoreObject = kv.GetDataStore("dataStoreName", "hostname", "user", "pass", "dbName", "portName", false);
DataStoreObject.Set("key", 10);             // numbers are valid arguments
DataStoreObject.Set("key", "10");           // strings are valid arguments
DataStoreObject.Set("key", ["a", 1, "2"]);  // arrays are valid arguments
DataStoreObject.Set("key", {a:"1", b:"2"}); // dictionaries are valid arguments
DataStoreObject.Set("key", {a:"1", b:"2", c:[1,2]}); // mixed tables are valid arguments

_internalDataStoreObject.GetAsync(key) ⇒ Promise

retrieves the value associated to the specified key asynchronously

Kind: static method of _internalDataStoreObject Returns: Promise - value - returns a Promise object that resolves to the value associated with the specified key

Param	Type	Description
key	string	the key to retrieve a value for - if the retrieved value was an object before saving then it will automatically be parsed into a Javascript object for you (all you have to do is call _internalDataStoreObject.GetAsync)

Example

let kv = require("kv-abstraction");
let DataStoreObject = kv.GetDataStore("dataStoreName", "hostname", "user", "pass", "dbName", "portName", false);
DataStoreObject.Get("key").then((value) => {
    console.log("value = " + value)
}, (err) => {
    console.log(err)
});

_internalDataStoreObject.Get(key, callback) ⇒ any

retrieves the value associated to the specified key synchronously

Kind: static method of _internalDataStoreObject

Param	Type	Description
key	string	the key to retrieve a value for - if the retrieved value was an object before saving then it will automatically be parsed into a Javascript object for you (all you have to do is call _internalDataStoreObject.Get)
callback	GetCallback	the callback to pass the retrieved value to - make sure to handle errors as well using the second parameter

Example

let kv = require("kv-abstraction");
let DataStoreObject = kv.GetDataStore("dataStoreName", "hostname", "user", "pass", "dbName", "portName", false);
DataStoreObject.Get("key", function(value, err) {
    if (err) {
        console.log("err = "+err)
    };
    console.log("value = " + value);
});

_internalDataStoreObject.Destroy() ⇒ void

ends / kills connection to a database that was initiated by DataStoreObject.GetDataStore

Kind: static method of _internalDataStoreObject Example

let kv = require("kv-abstraction");
let DataStoreObject = kv.GetDataStore("dataStoreName", "hostname", "user", "pass", "dbName", "portName", false);
DataStoreObject.Destroy();

DataStoreObject : Object

Note: Detailed documentation exists separately for each method, read that if you want.

Kind: global typedef Properties

Name	Type	Description
Set	function	saves a value to the specified key (read the documentation for DataStoreObject.Set)
Get	function	retrieves the value associated to the specified key (read the documentation for DataStoreObject.Get)
GetAsync	function	essentially DataStoreObject.Get, but asynchronous and returns a promise
Destroy	function	ends connection to a database so that you can't read from / write to it

GetCallback : function

callback to be executed once a value is retrieved for a specified key by _internalDataStoreObject.Get

Kind: global typedef

Param	Type
retrievedValue	string
errorMessage	string