Keyv is a simple key-value storage with support for multiple backend adapters (MySQL, PostgreSQL, SQLite, Redis, Mongo, DynamoDB, Firestore, Memcached, and more).

Features

Forked from keyv, plus:

• It isn't bloated.
• It supports namespaces.
• It supports TTL based expiry.
• It has a simple Promise based API.
• It handles all JSON types plus Buffer.
• It's support a vary of storages adapters.
• It can be easily embed inside another module.
• It works with any storage that implements the Map API.
• it handles database errors (db failures won't kill your app).
• It supports the current active LTS version of Node.js or higher.
• It's suitable as a TTL based cache or persistent key-value store.

Installation

1npm install @keyvhq/core --save 

You can optionally install the storage adapter you want to use:

1npm install @keyvhq/redis --save
2npm install @keyvhq/mongo --save
3npm install @keyvhq/sqlite --save
4npm install @keyvhq/postgres --save
5npm install @keyvhq/mysql --save

If you don't provide a specific storage adapter, a in-memory storage adapter is used by default.

Usage

Just create a new Keyv instance, using an specific storage adapter:

1const keyv = new Keyv() // in-memory, by default
2const keyvRedis = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379')})
3const keyvMongo = new Keyv({ store: new KeyvMongo('mongodb://user:pass@localhost:27017/dbname')})
4const keyvSQLite = new Keyv({ store: new KeyvSQLite('sqlite://path/to/database.sqlite')})
5const keyvPostgreSQL = new Keyv({ store: new KeyvPostgreSQL('postgresql://user:pass@localhost:5432/dbname')})
6const keyvMySQL = new Keyv({ store: new KeyvMySQL('mysql://user:pass@localhost:3306/dbname')})
7
8await keyv.set('foo', 'expires in 1 second', 1000) // true
9await keyv.set('foo', 'never expires') // true
10await keyv.get('foo') // 'never expires'
11await keyv.has('foo') // true
12await keyv.delete('foo') // true
13await keyv.has('foo') // false
14await keyv.clear() // undefined

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.

1const users = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379'), namespace: 'users' })
2const cache = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379'), namespace: 'cache' })
3
4await users.set('foo', 'users') // true
5await cache.set('foo', 'cache') // true
6await users.get('foo') // 'users'
7await cache.get('foo') // 'cache'
8await users.clear() // undefined
9await users.get('foo') // undefined
10await cache.get('foo') // 'cache'

Serialization

Keyv uses json-buffer for data serialization to ensure consistency across different backends.

You can optionally provide your own serialization functions to support extra data types or to serialize to something other than JSON.

The following example is using @keyvhq/compress as serializer:

1const KeyvCompress = require('@keyvhq/compress')
2const Keyv = require('@keyvhq/core')
3
4const keyv = KeyvCompress(
5  new Keyv({
6    serialize: v8.serialize,
7    deserialize: v8.deserialize
8  })
9)

Storage adapters

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

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.

1const KeyvRedis = require('@keyvhq/redis')
2const Keyv = require('@keyvhq/core')
3const got = require('got')
4
5const cache = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379') })
6
7await got('https://keyv.js.org', { cache })

The recommended pattern is to expose a cache option in your modules options which is passed through to Keyv.

For example, quick-lru is a completely unrelated module that implements the Map API.

1const Keyv = require('@keyvhq/core')
2const QuickLRU = require('quick-lru')
3
4const lru = new QuickLRU({ maxSize: 1000 })
5const keyv = new Keyv({ store: lru })

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

All the 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.

• @keyvhq/file – File storage adapter for Keyv.
• @keyvhq/mongo – MongoDB storage adapter for Keyv.
• @keyvhq/mysql – MySQL/MariaDB storage adapter for Keyv.
• @keyvhq/postgres – PostgreSQL storage adapter for Keyv.
• @keyvhq/redis – Redis storage adapter for Keyv.
• @keyvhq/sqlite – SQLite storage adapter for Keyv.

Decorators

• @keyvhq/compress – Adds compression bindings for your Keyv instance.
• @keyvhq/memoize – Memoize any function using Keyv as storage backend.
• @keyvhq/multi – Manages local and remote keyv stores as one.
• @keyvhq/offline – Adds offline capabilities for your keyv instance.
• @keyvhq/stats – Collects metrics for a Keyv instance over time.

Community

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.

• keyv-anyredis - Support for Redis clusters and alternative Redis clients.
• keyv-dynamodb - DynamoDB storage adapter for Keyv.
• keyv-file - File system storage adapter for Keyv.
• keyv-firestore – Firebase Cloud Firestore adapter for Keyv.
• keyv-lru – An in-memory LRU back-end for Keyv.
• keyv-memcache - Memcache storage adapter for Keyv.
• keyv-mssql - Microsoft SQL Server adapter for Keyv.
• keyv-s3 - Amazon S3 storage adapter for Keyv.
• quick-lru - Simple "Least Recently Used" (LRU) cache.

API

constructor([options])

Returns a new Keyv instance.

options

Type: Object

The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.

namespace

Type: String
Default: undefined

Namespace for the current instance.

ttl

Type: Number
Default: undefined

Default TTL in milliseconds. Can be overridden by specifying a TTL on .set().

serialize

Type: Function
Default: JSONB.stringify

A custom serialization function.

deserialize

Type: Function
Default: JSONB.parse

A custom deserialization function.

store

Type: Storage adapter instance
Default: new Map()

The storage adapter instance to be used by Keyv.

raw

Type: Boolean
Default: false

If set to true the raw DB object Keyv stores internally will be returned instead of just the value.

This contains the TTL timestamp.

.set(key, value, [ttl])

Set a value.

By default keys are persistent. You can set an expiry TTL in milliseconds.

Returns a promise which resolves to true.

.get(key, [options])

Returns a promise which resolves to the retrieved value.

.has(key)

Returns a promise which resolves to a boolean, indicating existence of a key.

.delete(key)

Deletes an entry.

Returns a promise which resolves to true if the key existed, false if not.

.clear()

Delete all entries in the current namespace.

Returns a promise which is resolved when the entries have been cleared.

When calling clear(), on a keyv instance with no namespace, all keys are cleared.

.iterator()

Returns an async iterator, which iterates over all the key-value pairs in the namespace. When called without a namespace, it iterates over all entries in the database.

The iterator shouldn't be used in environments where performance is key, or there are more than 1000 entries in the database, use an ORM or a native driver if you need to iterate over all entries.

License

keyv © Luke Childs, released under the MIT License.
Maintained by Microlink with help from contributors.

microlink.io · GitHub microlinkhq · X @microlinkhq