yakv

YAKV - Yet Another Key-Value Store

YAKV is very simple storage that can be used inside application or as a standalone redis-like storage.

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 the 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 for a RESTful API server. 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 a storage size 10, 10 seconds TTL and will be listening on port 8081.

To create a new storage with the maximum storage size of 10, a default TTL of 10 seconds, and to listen on port 8081:

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

Stop Server

In cases when a 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 the express instance

server.getInstance();

Delete Expired Values

There is a cleanUp method that can be called to clean up expired items when used as an in-memory storage.

server.cleanUp();

Clean Up Task

Server can start internal clean up task to periodically delete expired key/value pairs.

To start clean up task with the default interval (30 seconds)

server.startCleanupTask();

To start clean up task with the custom interval (in milliseconds)

server.startCleanupTask(2000);

To stop task

server.stopCleanupTask();

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