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: [email protected]

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

Typedefs

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 |