Examples

Examples Integrating k-value

Below contains an example for each adapter with the expected options and examples of accessing each part of the API.

Adapters

MemoryAdapter

const { MemoryAdapter } = require('k-value')
const kv = new MemoryAdapter()

MySQLAdapter

const { MySQLAdapter } = require('k-value')
const kv = new MySQLAdapter({
  client: 'mysql2',
  table: 'kv_table_name',
  cache: false, // set to true to enable global caching. use this if only 1 client will be connected to the table below
  connection: {
    host: 'hostname',
    user: 'username',
    password: 'password',
    database: 'database',
  },
  encoder: {
    use: true,
    store: 'base64',
    parse: 'utf-8'
  }
})
// You must call kv#configure() before this adapter will be usable. This is an asynchronous function. (Promise)

PostgreSQLAdapter

const kv = new PostgreSQLAdapter({
  client: 'pg',
  table: 'kv_table_name',
  cache: false, // set to true to enable global caching. use this if only 1 client will be connected to the table below
  connection: 'postgres://username:password@hostname/database',
  encoder: {
    use: true,
    store: 'base64',
    parse: 'utf-8'
  }
})
// You must call kv#configure() before this adapter will be usable. This is an asynchronous function. (Promise)

SQLiteAdapter

While supported, we recommend using the MySQLAdapter if you intend to handle high volume or if your data is of large physical size, due to the nature of SQLite using synchronous access for reading and writing operations. Creating many instances to different filenames is recommended for higher volume environments.

const { SQLiteAdapter } = require('k-value')
const kv = new SQLiteAdapter({
  client: 'sqlite3',
  cache: false // set to true to enable global caching. use this if only 1 client will be connected to the table below
  connection: {
    filename: require('path').resolve(__dirname, './ci.database'),
    table: 'kv_table_name',
  },
  encoder: {
    use: true,
    store: 'base64',
    parse: 'utf-8'
  }
})
// You must call kv#configure() before this adapter will be usable. This is an asynchronous function. (Promise)

Using the API

The below example is consistent across all adapters and is our standardized API. The only difference is how you initialize the adapter and which class you use for each adapter type.

const { MemoryAdapter } = require("../dist/index"); // require('kvalue')

async function example() {
  const kv = new MemoryAdapter();
  await kv.configure(); // This is needed for SQL-based, MongoDB, and Redis Adapters.
  await kv.set("key", "value");
  await kv.set("key2", { objKey: "value" });
  await kv.set(["key3", "key4"], { objKey: "multi-set" });
  await kv.set("key4", true);
  await kv.set("key5", { x: 1 });
  await kv.set("key5", { y: 2 }, { merge: true }); // { x: 1, y: 2 }
  await kv.set("key6", { x: 300 }, { lifetime: 10000 }); // Expires after 10s

  await kv.get("key"); // "value"
  await kv.get(["key2", "key3"]); // [ { key: 'key2', value: { objKey: "value" }}, { key: 'key3', value: { objKey: "multi-set" }} ]
  await kv.get("unknown", { defaultValue: "default" }); // "default"
  await kv.get(["unknown1", "unknown2"], { defaultValue: "default" }); // [ { key: 'unknown1', value: 'default' }, { key: 'unknown2', value: 'default' } ]

  // Caching not enabled on MemoryAdapter
  // Cache the value to memory, expiring after cacheExpire ms
  // Adapter#set() will invalidate the cached value.
  await kv.get("key4", { cache: true, cacheExpire: 1000 });

  await kv.has("key"); // true
  await kv.has("unknown"); // false
  await kv.has(["key", "key2", "unknown"]); // [ { key: 'key', has: true }, { key: 'key2', has: true }, { key: 'unknown', has: false } ]

  await kv.keys(); // [ 'key', 'key2', 'key3', 'key4', 'key5', 'key6' ]
  await kv.keys({ limit: 5 }); // [ 'key', 'key2', 'key3', 'key4', 'key5' ]
  await kv.keys({ limit: 3, randomize: true }); // [ 'key', 'key5', 'key2' ]

  await kv.delete("key");
  await kv.delete(["key2", "key3"]);
  await kv.delete("unknown");

  await kv.entries(); // [ [key, value], [key2, value], [key3, value], [key4, value], [key5, value], [key6, value] ]
  await kv.values(); // [ value, value, value, value, ... ]

  await kv.clear();
}

example();

Enabling Storage Encoding

When dealing with string dense complex objects, the likelihood of misaligned escape sequences may cause your JSON to become corrupted and unreadable. To resolve this, k-value has designed a mode that will encode your object before storage. This allows us to rebuild your objects exactly how they were before being stored with k-value. This feature can be enabled by adding the following to your adapter options, which is where you do new SomeAdapter({ ... }) This feature is not enabled with our Memory adapter, as it is unaffected.

We greatly recommend enabling this, as it provides further layers of integrity to your information. This sadly sacrifices the human readability of the information that is stored on the database, which will require you to manually decode the information or recall the data with the Adapter#get() action.

{
  table: 'tableName',
  encoder: {
    use: true,
    store: 'base64',
    parse: 'utf-8' 
  }
}