What is keyv?
The keyv npm package is a simple key-value storage with support for multiple backends. It is designed to be a straightforward solution for key-value storage across different systems and protocols. It supports TTL based expiry, making it suitable for applications like caching and session storage.
What are keyv's main functionalities?
Simple Key-Value Storage
Store and retrieve data using simple key-value pairs.
{"const Keyv = require('keyv');
const keyv = new Keyv();
keyv.set('foo', 'bar').then(() => keyv.get('foo').then(value => console.log(value)));
// Logs: 'bar'"}
Namespaces
Use namespaces to avoid key collisions when sharing the same storage backend.
{"const Keyv = require('keyv');
const users = new Keyv('sqlite://path/to/database.sqlite', { namespace: 'users' });
const cache = new Keyv('sqlite://path/to/database.sqlite', { namespace: 'cache' });
// `users` and `cache` can share the same storage without key collisions."}
Support for Multiple Backends
Keyv can be used with various storage backends like Redis, MongoDB, SQLite, and more.
{"const Keyv = require('keyv');
const keyv = new Keyv('redis://user:pass@localhost:6379');
keyv.set('foo', 'bar').then(() => keyv.get('foo').then(value => console.log(value)));
// This will use Redis as the storage backend."}
TTL (Time to Live)
Automatically expire keys after a certain period of time.
{"const Keyv = require('keyv');
const keyv = new Keyv({ ttl: 10000 });
keyv.set('foo', 'expires in 10 seconds', 10000).then(() => setTimeout(() => keyv.get('foo').then(value => console.log(value)), 15000));
// Logs: undefined, since the key has expired after 10 seconds."}
Other packages similar to keyv
node-cache
node-cache is an in-memory key-value store similar to keyv but does not support multiple backends. It is purely for in-memory storage with TTL support.
levelup
levelup is a wrapper for LevelDB. It provides a key-value store with a rich set of features. Unlike keyv, levelup is more complex and is designed specifically for LevelDB.
ioredis
ioredis is a robust, performance-focused Redis client for Node.js. While keyv supports Redis as one of its backends, ioredis is dedicated solely to Redis and offers more advanced features specific to Redis.
memcached
memcached is a Node.js client for the memcached server. It is similar to keyv in providing a key-value cache but is specific to the memcached protocol and server.
Simple key-value storage with support for multiple backends
Keyv provides a consistent interface for key-value storage across multiple backends via storage adapters. It supports TTL based expiry, making it suitable as a cache or a persistent key-value store.
Features
There are a few existing modules similar to Keyv, however Keyv is different because it:
- Isn't bloated
- Has a simple Promise based API
- Suitable as a TTL based cache or persistent key-value store
- Easily embeddable inside another module
- Works with any storage that implements the
Map
API - Handles all JavaScript types (values can be
Buffer
/null
/undefined
) - Supports namespaces
- Wide range of efficient, well tested storage adapters
- Connection errors are passed through (db failures won't kill your app)
- Supports the current active LTS version of Node.js or higher
Usage
Install Keyv.
npm install --save keyv
By default everything is stored in memory, you can optionally also install a storage adapter.
npm install --save keyv-redis
npm install --save keyv-mongo
npm install --save keyv-sqlite
npm install --save keyv-postgres
npm install --save keyv-mysql
Create a new Keyv instance, passing your connection string if applicable. Keyv will automatically load the correct storage adapter.
const Keyv = require('keyv');
const keyv = new Keyv();
const keyv = new Keyv('redis://user:pass@localhost:6379');
const keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');
const keyv = new Keyv('sqlite://path/to/database.sqlite');
const keyv = new Keyv('postgresql://user:pass@localhost:5432/dbname');
const keyv = new Keyv('mysql://user:pass@localhost:3306/dbname');
keyv.on('error' err => console.log('Connection Error', err));
await keyv.set('foo', 'expires in 1 second', 1000);
await keyv.set('foo', 'never expires');
await keyv.get('foo');
await keyv.delete('foo');
await keyv.clear();
Namespaces
You can namespace your Keyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.
const users = new Keyv('redis://user:pass@localhost:6379', { namespace: 'users' });
const cache = new Keyv('redis://user:pass@localhost:6379', { namespace: 'cache' });
await users.set('foo', 'users');
await cache.set('foo', 'cache');
await users.get('foo');
await cache.get('foo');
await users.clear();
await users.get('foo');
await cache.get('foo');
Official Storage Adapters
The official storage adapters are covered by over 150 integration tests to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.
Third-party Storage Adapters
You can also use third-party storage adapters or build your own. Keyv will wrap these storage adapters in TTL functionality and handle complex types internally.
const Keyv = require('keyv');
const myAdapter = require('./my-storage-adapter');
const keyv = new Keyv({ store: myAdapter });
Any store that follows the Map
api will work.
new Keyv({ store: new Map() });
For example, quick-lru
is a completely unrelated module that implements the Map API.
const Keyv = require('keyv');
const QuickLRU = require('quick-lru');
const lru = new QuickLRU({ maxSize: 1000 });
const keyv = new Keyv({ store: lru });
Add Cache Support to your Module
Keyv 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. Caching will work in memory by default and users have the option to also install a Keyv storage adapter and pass in a connection string, or any other storage that implements the Map
API.
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 Keyv(opts.cache, { namespace: 'awesome-module' });
}
}
Now it can be consumed like this:
const AwesomeModule = require('awesome-module');
const awesomeModule = new AwesomeModule();
const awesomeModule = new AwesomeModule({ cache: 'redis://localhost' });
const awesomeModule = new AwesomeModule({ cache: some3rdPartyStore });
API
new Keyv([uri], [options])
Returns a new Keyv instance.
The Keyv instance is also an EventEmitter
that will emit an 'error'
event if the storage adapter connection fails.
uri
Type: String
Default: undefined
The connection string URI.
Merged into the options object as options.uri.
options
Type: Object
The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.
options.namespace
Type: String
Default: 'keyv'
Namespace for the current instance.
options.ttl
Type: Number
Default: undefined
Default TTL. Can be overridden by specififying a TTL on .set()
.
options.store
Type: Storage adapter instance
Default: new Map()
The storage adapter instance to be used by Keyv.
options.adapter
Type: String
Default: undefined
Specify an adapter to use. e.g 'redis'
or 'mongodb'
.
Instance
Keys must always be strings. Values can be of any type.
.set(key, value, [ttl])
Set a value.
By default keys are persistent. You can set an expiry TTL in milliseconds.
Returns true
.
.get(key)
Returns the value.
.delete(key)
Deletes an entry.
Returns true
if the key existed, false
if not.
.clear()
Delete all entries in the current namespace.
Returns undefined
.
License
MIT © Luke Childs