@availity/keyv-local-sync NPM

@availity/keyv-local-sync

Simple local real-time key-value storage with support for TTL

keyv-local-sync provides a consistent interface for key-value. It supports TTL based expiry, making it suitable as a cache key-value store.

Features

There are a few existing modules similar to keyv-local-sync, however keyv-local-sync is different because it:

Isn't bloated
Isn't async, uses local memory-based storage for real-time lookups and storage
Cache promises or anything, it's not serialized so you get back exactly what you put in
Suitable as a TTL based cache key-value store
Easily embeddable inside another module
Works with any storage that implements the Map API
Supports namespaces
Supports the current active LTS version of Node.js or higher

Usage

Install keyv-local-sync.

npm install --save @availity/keyv-local-sync

Create a new keyv-local-sync instance. keyv-local-sync will automatically load the correct storage adapter.

const KeyvLocalSync = require('@availity/keyv-local-sync');

// One of the following
const keyvLocalSync = new KeyvLocalSync(); // the default store uses quick-lru
const keyvLocalSync = new KeyvLocalSync({ store: new Map() });

keyvLocalSync.set('foo', 'expires in 1 second', 1000); // true
keyvLocalSync.set('foo', 'never expires'); // true
keyvLocalSync.get('foo'); // 'never expires'
keyvLocalSync.delete('foo'); // true
keyvLocalSync.clear(); // undefined

Namespaces

keyv-local-sync instance to avoid key collisions and allow you to clear only a certain namespace while u You can namespace your keyv-local-sync instance to avoid key collisions and allow you to clear only a certain namespace.

const users = new KeyvLocalSync({ namespace: 'users' });
const cache = new KeyvLocalSync({ namespace: 'cache' });

users.set('foo', 'users'); // true
cache.set('foo', 'cache'); // true
users.get('foo'); // 'users'
cache.get('foo'); // 'cache'
users.clear(); // undefined
users.get('foo'); // undefined
cache.get('foo'); // 'cache'

Third-party Storage Adapters

You can also use third-party storage adapters or build your own. keyv-local-sync will wrap these storage adapters in TTL functionality and handle complex types internally.

const KeyvLocalSync = require('@availity/keyv-local-sync');
const myAdapter = require('./my-storage-adapter');

const keyvLocalSync = new KeyvLocalSync({ store: myAdapter });

Any store that follows the Map api will work.

new KeyvLocalSync({ store: new Map() });

For example, quick-lru is a module that implements the Map API, it is used by default is no store is provided.

const KeyvLocalSync = require('@availity/keyv-local-sync');

const keyvLocalSync = new KeyvLocalSync({ size: 1000 });

The following are third-party storage adapters compatible with keyv-local-sync:

quick-lru - Simple "Least Recently Used" (LRU) cache

Add Cache Support to your Module

keyv-local-sync is designed to be easily embedded into other modules to add cache support. The recommended pattern is to expose a cache option in your modules options which is passed through to keyv-local-sync.

You should also set a namespace for your module so you can safely call .clear() without clearing unrelated app data.

Inside your module:

class AwesomeModule {
    constructor(opts) {
        this.cache = new KeyvLocalSync({
            store: opts.cache,
            namespace: 'awesome-module',
        });
    }
}

Now it can be consumed like this:

const AwesomeModule = require('awesome-module');

// Caches stuff in memory by default
const awesomeModule = new AwesomeModule();

// After npm install --save keyv-local-sync-redis
const awesomeModule = new AwesomeModule({ cache: new Map() });

// Some third-party module that implements the Map API
const awesomeModule = new AwesomeModule({ cache: some3rdPartyStore });