YAKV - Yet Another Key-Value Store

YAKV is very simple storage that is designed to solve one simple problem - managing external lock for relational databases. Database engines implement locks in some way, but it is quite complex work to manage such locks from distributed applications using connection pools, sometimes existing lock mechanisms are not suitable for modern applications.

YAKV consists of two modules:

• KV storage that can be used as a local in-memory store
• Web server to access KV storage over RESTful API

Table of Contents

• Features
• Local Storage
  • Parameters
  • Create New Storage
  • Add Value
  • Get Value
  • Get Current Storage Size
  • Get Max Storage Size
  • Get Default TTL
  • Delete Expired Values
• HTTP Server
• RESTful API
  • Health
  • Read Value
  • Add Value
  • Add Value With TTL

Features

• Keys can be strings or number
• Value can be anything
• Global TTL (expire time)
• Per-key TTL (expire time)
• RESTful API
• Key can't be replaced until expired

Local Storage

Parameters

maxStorageSize: Optional. Max number of key/values. Default value is 1000000.

defaultTTL: Optional. TTL for values if not set on create. Default value is 60000. Value is in milliseconds.

Create Storage

To create new storage with default parameters

const store = new KVStore();

Set max number of key/values to 1000

const store = new KVStore(1000);

Set max number of key/values to 1000 and default TTL to 5 seconds

const store = new KVStore(1000, 5000);

Add Value

ttl is optional parameter

const res1 = store.set('key1', { someData: 'test data' });
console.log(res1); // prints `true`, value added

const res2 = store.set('key1', { someData: 'new data' });
console.log(res2); // prints `false`, value not added as current values TTL is not expired yet

// wait TTL to expire

const res3 = store.set('key1', { someData: 'new data' });
console.log(res3); // prints `true`, value overridden because TTL expired

Get Value

const res1 = store.get('key1');
console.log(res1); // prints value `{ someData: 'test data' }`

const res2 = store.get('key2');
console.log(res2); // prints `undefined`, because key not found in storage

Get Current Storage Size

const store = new KVStore();
const res1 = store.set('key1', 'foo');
store.getSize(); // returns 1

Get Max Storage Size

const store = new KVStore(1000);
store.getMaxStorageSize(); // returns 100

Get Default TTL

const store = new KVStore(1000, 5000);
store.getDefaultTTL(); // returns 5000

Delete Expired Values

const store = new KVStore();
store.cleanUp();

HTTP Server

When new instance is created it also creates in-memory storage with the same parameters passed to HTTP server.

Parameters

maxStorageSize: Optional. Max number of key/values. Default value is 1000000.

defaultTTL: Optional. TTL for values if not set on create. Default value is 60000. Value is in milliseconds.

port: Optional. Port to listen to. Default value is 8080.

Create And Start Server

To create new storage with default parameters

const server = new KVServer();

Once server is created it can be started, so it will start listening for requests

server.start();

Some parameters can be passed to change server defaults, as per example below server is created with storage size 10, 10 seconds TTL and will be listening on port 8081.

const server = new KVServer(10, 10000, 8081);

Stop Server

In cases when server should be gracefully stopped it has async stop method

await server.stop();

Internal Express Instance

There is a getinstance method to get access to internal express instance

server.getInstance();

Delete Expired Values

There is a crealUp method to delete expired values from internal storage, it basically executes cleanUp against internal storage instance.

server.cleanUp();

RESTful API

Health

To get current storage state

GET /kv/v1/health

Example response:

{
    "defaultTTL": 60000,
    "maxStorageSize": 1000000,
    "storageUsed": 0
}

Read Value

To read value by key

GET /kv/v1/get/:key

If key exists then response will contain value

{
    "data": "foo"
}

Otherwise value will be null

{
    "data": null
}

Add Value

PUT /kv/v1/put/:key

If value successfully added or overridden because TTL expired then response will be

{
    "created": true
}

otherwise false

{
    "created": false
}

Add Value With TTL

PUT /kv/v1/put/:key/:ttl