Getting Started Guide

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. Follow the steps below to get you up and running.

1. Make a Project Directory

Make a directory with your project in it.

mkdir keyv
cd keyv

You’re now inside your project’s directory.

2. Install keyv

npm install --save keyv

By default, everything is stored in memory; you can optionally also install a storage adapter; choose one from the following:

npm install --save @keyv/redis
npm install --save @keyv/valkey
npm install --save @keyv/memcache
npm install --save @keyv/mongo
npm install --save @keyv/sqlite
npm install --save @keyv/postgres
npm install --save @keyv/mysql
npm install --save @keyv/etcd

Note: You can also use third-party storage adapters

The following are third-party storage adapters compatible with Keyv:

• quick-lru - Simple "Least Recently Used" (LRU) cache
• keyv-file - File system storage adapter for Keyv
• keyv-dynamodb - DynamoDB storage adapter for Keyv
• keyv-lru - LRU storage adapter for Keyv
• keyv-null - Null storage adapter for Keyv
• keyv-firestore – Firebase Cloud Firestore adapter for Keyv
• keyv-mssql - Microsoft Sql Server adapter for Keyv
• keyv-azuretable - Azure Table Storage/API adapter for Keyv
• keyv-arango - ArangoDB storage adapter for Keyv
• keyv-momento - Momento storage adapter for Keyv
• @resolid/keyv-sqlite - A new SQLite storage adapter for Keyv

3. Create a New Keyv Instance

Pass your connection string if applicable. Keyv will automatically load the correct storage adapter. ////

// example Keyv instance that uses sqlite storage adapter
const keyv = new Keyv('sqlite://path/to/database.sqlite');

Keyv Parameters

options Parameters

Example - Create an Instance of Keyv with a connection URI

The following example shows how you would create and Instance of Keyv with a mongodb connection URI.

const Keyv = require('keyv');

const keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');

// Handle DB connection errors
keyv.on('error', err => console.log('Connection Error', err));

Example - Create an Instance of Keyv using a third-party storage adapter

quick-lru is a third-party 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 });

// Handle DB connection errors
keyv.on('error', err => console.log('Connection Error', err));

4. Create Some Key Value Pairs

Method: set(key, value, [ttl]) - Set a value for a specified key.

The following example code shows you how to create a key-value pair using the set method.

const keyv = new Keyv('redis://user:pass@localhost:6379');

// set a key value pair that expires in 1000 milliseconds
await keyv.set('foo', 'expires in 1 second', 1000); // true

// set a key value pair that never expires
await keyv.set('bar', 'never expires'); // true

Method: delete(key) - Deletes an entry.

To delete a key value pair use the delete(key) method as shown below:

// Delete the key value pair for the 'foo' key
await keyv.delete('foo'); // true

5. Advanced - Use Namespaces to Avoid Key Collisions

You can namespace your Keyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.

The example code below creates two namespaces, 'users' and 'cache' and creates a key value pair using the key 'foo' in both namespaces, it also shows how to delete all values in a specified namespace.

const users = new Keyv('redis://user:pass@localhost:6379', { namespace: 'users' });
const cache = new Keyv('redis://user:pass@localhost:6379', { namespace: 'cache' });

// Set a key-value pair using the key 'foo' in both namespaces
await users.set('foo', 'users'); // returns true
await cache.set('foo', 'cache'); // returns true

// Retrieve a Value
await users.get('foo'); // returns 'users'
await cache.get('foo'); // returns 'cache'

// Delete all values for the specified namespace
await users.clear();

6. Advanced - Enable Compression

Keyv supports both gzip and brotli methods of compression. Before you can enable compression, you will need to install the compression package:

npm install --save keyv @keyv/compress-gzip

Example - Enable Gzip compression

To enable compression, pass the compression option to the constructor.

const KeyvGzip = require('@keyv/compress-gzip');
const Keyv = require('keyv');

const keyvGzip = new KeyvGzip();
const keyv = new Keyv({ compression: KeyvGzip });

You can also pass a custom compression function to the compression option. Custom compression functions must follow the pattern of the official compression adapter (see below for further information).

Want to build your own?

Great! Keyv is designed to be easily extended. You can build your own compression adapter by following the pattern of the official compression adapters based on this interface:

interface CompressionAdapter {
	async compress(value: any, options?: any);
	async decompress(value: any, options?: any);
	async serialize(value: any);
	async deserialize(value: any);
}

Test your custom compression adapter

In addition to the interface, you can test it with our compression test suite using @keyv/test-suite:

const {keyvCompresstionTests} = require('@keyv/test-suite');
const KeyvGzip = require('@keyv/compress-gzip');

keyvCompresstionTests(test, new KeyvGzip());

7. Advanced - Extend your own Module with Keyv

Keyv can be easily embedded into other modules to add cache support.

• Caching will work in memory by default, and users can 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 to safely call .clear() without clearing unrelated app data.

Note: The recommended pattern is to expose a cache option in your module's options which is passed through to Keyv.

Example - Add Cache Support to a Module

1. Install whichever storage adapter you will be using, keyv-redis in this example

npm install --save keyv-redis

2. Declare the Module with the cache controlled by a Keyv instance

class AwesomeModule {
	constructor(opts) {
		this.cache = new Keyv({
			uri: typeof opts.cache === 'string' && opts.cache,
			store: typeof opts.cache !== 'string' && opts.cache,
			namespace: 'awesome-module'  
		});
	}
}

3. Create an Instance of the Module with caching support

const AwesomeModule = require('awesome-module');
const awesomeModule = new AwesomeModule({ cache: 'redis://localhost' });