Affected versions:
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.
There are a few existing modules similar to Keyv, however Keyv is different because it:
Map APIBuffer and BigInt via the built-in KeyvJsonSerializerInstall 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/valkey
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
npm install --save @keyv/memcache
npm install --save @keyv/dynamo
First, create a new Keyv instance.
import Keyv from 'keyv';
You can create a Keyv instance with a generic type to enforce type safety for the values stored. Additionally, both the get and set methods support specifying custom types for specific use cases.
const keyv = new Keyv<number>(); // Instance handles only numbers
await keyv.set('key1', 123);
const value = await keyv.get('key1'); // value is inferred as number
You can also specify a type directly in the get or set methods, allowing flexibility for different types of values within the same instance.
const keyv = new Keyv(); // Generic type not specified at instance level
await keyv.set<string>('key2', 'some string'); // Method-level type for this value
const strValue = await keyv.get<string>('key2'); // Explicitly typed as string
await keyv.set<number>('key3', 456); // Storing a number in the same instance
const numValue = await keyv.get<number>('key3'); // Explicitly typed as number
This makes Keyv highly adaptable to different data types while maintaining type safety.
Once you have created your Keyv instance you can use it as a simple key-value store with in-memory by default. To use a storage adapter, create an instance of the adapter and pass it to the Keyv constructor. Here are some examples:
// redis
import KeyvRedis from '@keyv/redis';
const keyv = new Keyv(new KeyvRedis('redis://user:pass@localhost:6379'));
You can also pass in a storage adapter with other options such as ttl and namespace (example using sqlite):
//sqlite
import KeyvSqlite from '@keyv/sqlite';
const keyvSqlite = new KeyvSqlite('sqlite://path/to/database.sqlite');
const keyv = new Keyv({ store: keyvSqlite, ttl: 5000, namespace: 'cache' });
To handle an event you can do the following:
// Handle DB connection errors
keyv.on('error', err => console.log('Connection Error', err));
Now lets do an end-to-end example using Keyv and the Redis storage adapter:
import Keyv from 'keyv';
import KeyvRedis from '@keyv/redis';
const keyvRedis = new KeyvRedis('redis://user:pass@localhost:6379');
const keyv = new Keyv({ store: keyvRedis });
await keyv.set('foo', 'expires in 1 second', 1000); // true
await keyv.set('foo', 'never expires'); // true
await keyv.get('foo'); // 'never expires'
await keyv.delete('foo'); // true
await keyv.clear(); // undefined
It's is just that simple! Keyv is designed to be simple and easy to use.
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(new KeyvRedis('redis://user:pass@localhost:6379'), { namespace: 'users' });
const cache = new Keyv(new KeyvRedis('redis://user:pass@localhost:6379'), { namespace: 'cache' });
await users.set('foo', 'users'); // true
await cache.set('foo', 'cache'); // true
await users.get('foo'); // 'users'
await cache.get('foo'); // 'cache'
await users.clear(); // undefined
await users.get('foo'); // undefined
await cache.get('foo'); // 'cache'
Keyv is an EventEmitter (built on hookified) and will emit an 'error' event if there is an error. By default an error is only thrown if there are no listeners attached to the 'error' event. To always throw on errors regardless of listeners, enable the throwOnErrors option.
const keyv = new Keyv();
keyv.on('error', err => console.log('Connection Error', err));
In addition it will emit clear and disconnect events when the corresponding methods are called.
const keyv = new Keyv();
const handleConnectionError = err => console.log('Connection Error', err);
const handleClear = () => console.log('Cache Cleared');
const handleDisconnect = () => console.log('Disconnected');
keyv.on('error', handleConnectionError);
keyv.on('clear', handleClear);
keyv.on('disconnect', handleDisconnect);
Keyv supports hooks for all of its operations. Hooks are useful for logging, debugging, and other custom functionality. Each operation fires a BEFORE_* hook before it runs and an AFTER_* hook after it completes. Here is the list of all the hooks:
BEFORE_GET / AFTER_GET
BEFORE_GET_MANY / AFTER_GET_MANY
BEFORE_GET_RAW / AFTER_GET_RAW
BEFORE_GET_MANY_RAW / AFTER_GET_MANY_RAW
BEFORE_SET / AFTER_SET
BEFORE_SET_RAW / AFTER_SET_RAW
BEFORE_SET_MANY / AFTER_SET_MANY
BEFORE_SET_MANY_RAW / AFTER_SET_MANY_RAW
BEFORE_DELETE / AFTER_DELETE
BEFORE_DELETE_MANY / AFTER_DELETE_MANY
BEFORE_HAS / AFTER_HAS
BEFORE_HAS_MANY / AFTER_HAS_MANY
BEFORE_CLEAR / AFTER_CLEAR
BEFORE_DISCONNECT / AFTER_DISCONNECT
The older
PRE_*/POST_*hook names (e.g.PRE_GET,POST_SET) are deprecated aliases that still fire for backward compatibility. Prefer theBEFORE_*/AFTER_*names going forward.
You can access these by importing KeyvHooks from the main Keyv package and registering a handler with onHook():
import Keyv, { KeyvHooks } from 'keyv';
const keyv = new Keyv();
keyv.onHook(KeyvHooks.BEFORE_SET, (data) => {
console.log(`Setting key ${data.key} to ${data.value}`);
});
The AFTER_GET and AFTER_GET_RAW hooks fire on both cache hits and misses. When a cache miss occurs (key doesn't exist or is expired), the hook receives undefined as the value.
// AFTER_GET hook - fires on both hits and misses
const keyv = new Keyv();
keyv.onHook(KeyvHooks.AFTER_GET, (data) => {
if (data.value === undefined) {
console.log(`Cache miss for key: ${data.key}`);
} else {
console.log(`Cache hit for key: ${data.key}`, data.value);
}
});
await keyv.get('existing-key'); // Logs cache hit with value
await keyv.get('missing-key'); // Logs cache miss with undefined
// AFTER_GET_RAW hook - same behavior as AFTER_GET
const keyv = new Keyv();
keyv.onHook(KeyvHooks.AFTER_GET_RAW, (data) => {
console.log(`Key: ${data.key}, Value:`, data.value);
});
await keyv.getRaw('foo'); // Logs with value or undefined
// BEFORE_SET hook
const keyv = new Keyv();
keyv.onHook(KeyvHooks.BEFORE_SET, (data) => console.log(`Setting key ${data.key} to ${data.value}`));
// AFTER_SET hook
const keyv = new Keyv();
keyv.onHook(KeyvHooks.AFTER_SET, ({ key, value }) => console.log(`Set key ${key} to ${value}`));
In the BEFORE_SET hook you can also manipulate the value before it is set. For example, you could add a prefix to all keys.
const keyv = new Keyv();
keyv.onHook(KeyvHooks.BEFORE_SET, (data) => {
console.log(`Manipulating key ${data.key} and ${data.value}`);
data.key = `prefix-${data.key}`;
data.value = `prefix-${data.value}`;
});
Now this key will have prefix- added to it before it is set.
In the BEFORE_DELETE and AFTER_DELETE hooks, the value could be a single item or an Array. This is based on the fact that delete can accept a single key or an Array of keys.
By default, Keyv uses its built-in KeyvJsonSerializer — a JSON-based serializer with support for Buffer and BigInt types. This works out of the box with all storage adapters.
In addition to the built-in serializer, Keyv offers two official serialization packages:
@keyv/serialize-superjson supports Date, RegExp, Map, Set, BigInt, undefined, Error, and URL types.
import Keyv from 'keyv';
import { superJsonSerializer } from '@keyv/serialize-superjson'; // using the helper function that does new KeyvSuperJsonSerializer()
const keyv = new Keyv({ serialization: superJsonSerializer });
@keyv/serialize-msgpackr is a binary serializer that supports Date, RegExp, Map, Set, Error, undefined, NaN, and Infinity types.
import Keyv from 'keyv';
import { KeyvMsgpackrSerializer } from '@keyv/serialize-msgpackr';
const keyv = new Keyv({ serialization: new KeyvMsgpackrSerializer() });
You can provide your own serializer by implementing the KeyvSerializationAdapter interface with stringify and parse methods:
interface KeyvSerializationAdapter {
stringify: (object: unknown) => string | Promise<string>;
parse: <T>(data: string) => T | Promise<T>;
}
You can disable serialization entirely by passing false. This stores data as raw objects, which works for in-memory Map storage where string conversion is not needed:
const keyv = new Keyv({ serialization: false });
When serialization, compression, and/or encryption are configured, Keyv applies them in this order:
On set: serialize → compress (optional) → encrypt (optional) → store
On get: store → decrypt (optional) → decompress (optional) → parse → value
Compression and encryption operate on the serialized string, so they only run when a serializer is configured. The built-in KeyvJsonSerializer is enabled by default, so this works out of the box. If you disable serialization with serialization: false, values are passed through to the store as-is and compression/encryption are skipped.
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.
| Database | Adapter | Native TTL |
|---|---|---|
| Redis | @keyv/redis | Yes |
| Valkey | @keyv/valkey | Yes |
| MongoDB | @keyv/mongo | Yes |
| SQLite | @keyv/sqlite | No |
| PostgreSQL | @keyv/postgres | No |
| MySQL | @keyv/mysql | No |
| Etcd | @keyv/etcd | Yes |
| Memcache | @keyv/memcache | Yes |
| DynamoDB | @keyv/dynamo | Yes |
We love the community and the third-party storage adapters they have built. They enable Keyv to be used with even more backends and use cases.
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.
import Keyv from 'keyv';
import myAdapter from 'my-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.
import Keyv from 'keyv';
import QuickLRU from 'quick-lru';
const lru = new QuickLRU({ maxSize: 1000 });
const keyv = new Keyv({ store: lru });
View the complete list of third-party storage adapters and learn how to build your own at https://keyv.org/docs/third-party-storage-adapters/
The public API above is unchanged —
keyv.set(key, value, ttl)still takes a relative TTL in milliseconds. The change below only affects authors of custom storage adapters.
As of v6, Keyv passes an absolute expires timestamp (Unix ms since epoch) to a storage adapter's write methods instead of a relative TTL. Keyv computes expires once, so adapters never need to derive or parse it:
import { keyvStorageCapability } from 'keyv';
type KeyvStorageEntry<Value> = { key: string; value: Value; expires?: number };
class MyAdapter {
// Declare support for the absolute-`expires` contract:
get capabilities() {
return keyvStorageCapability(this); // -> { ...detected, expires: true }
}
// `expires` is absolute Unix ms; `undefined` means no expiry; `<= Date.now()` means already expired.
async set(key: string, value: unknown, expires?: number): Promise<boolean> { /* ... */ }
async setMany<Value>(entries: KeyvStorageEntry<Value>[]): Promise<boolean[] | undefined> { /* ... */ }
// ...get, delete, clear, has, getMany, deleteMany, hasMany, etc.
}
A v6 adapter declares capabilities.expires === true (the keyvStorageCapability(this) helper sets it for you). Keyv then passes the absolute expires to it directly — this takes precedence over structural detection, so an adapter whose methods aren't written with async is still used directly rather than bridged. Any legacy storage adapter that does not declare capabilities.expires is treated as a relative-TTL adapter and transparently wrapped by KeyvBridgeAdapter, which converts the absolute expires back to a relative TTL before delegating (and deletes outright when the deadline has already elapsed) — so existing third-party adapters keep working unchanged. Stores that expose absolute-expiry primitives (e.g. Redis PXAT) use expires directly. Map-like stores wrapped via new Keyv({ store: new Map() }) are unaffected.
Adapters should enforce expiry — and Keyv double-checks by default. Declaring
capabilities.expires === truemeans a v6 adapter should enforce expiry itself — ideally via a native mechanism (key expiry, TTL index, lease) so the backend reclaims space, and/or a client-side check on read. On top of that, Keyv core filters expired reads at its own layer by default (checkExpiredistrue), using the absoluteexpiresin the serialized envelope, soget/getMany/hasnever surface a key past its deadline even on backends whose native expiry is coarse or lazily swept (e.g. Memcached, DynamoDB). Run@keyv/test-suite'sstorageTtlTestsagainst your adapter to verify its own expiry behaviour.
Keyv ships with two storage adapters built directly into the core package. You rarely instantiate them yourself — Keyv selects and wires up the right one automatically when you create an instance — but knowing how they work explains how the default in-memory store behaves and how legacy or async stores are adapted to the v6 contract. Both are exported from keyv:
KeyvMemoryAdapter is the default store. When you create a Keyv instance without a store (new Keyv()), it uses new KeyvMemoryAdapter(new Map()) under the hood. It wraps any synchronous, Map-like object — the built-in Map, quick-lru, lru.min, or anything exposing get, set, delete, clear, and has.
It adds the pieces a raw Map does not have:
namespace and keySeparator (default :), so one underlying store can host multiple namespaces. A namespaced clear() removes only the current namespace's keys when the underlying store exposes a keys() method (a standard Map does); a minimal store without keys() falls back to wiping the entire store, so take care sharing one such store across namespaces.{ value, expires } wrapper alongside the stored value, so it can evict expired entries lazily on get, getMany, has, and iterator() without decoding the value. This wrapper is separate from the { value, expires } envelope Keyv core builds and runs through serialization/compression/encryption — with the default serializer that encoded payload still contains expires, so custom serializer/encryption adapters must still handle the expires field; only the adapter's outer copy lives outside the payload. When the underlying store accepts a TTL argument (e.g. QuickLRU), the adapter also passes a derived relative duration so the store can evict on its own.getMany, setMany, hasMany, deleteMany, and an async iterator() (when the store supports entries()).capabilities.expires === true, so Keyv hands it the absolute expires timestamp directly and trusts it to enforce expiry.import Keyv, { KeyvMemoryAdapter } from 'keyv';
// Wrap any Map-like store. Put the namespace on the Keyv options, not the adapter: Keyv
// propagates its own namespace to the store, overwriting any namespace set on the adapter.
const keyv = new Keyv({ store: new KeyvMemoryAdapter(new Map()), namespace: 'cache' });
// Or wrap an LRU to bound memory usage
import QuickLRU from 'quick-lru';
const cache = new Keyv({ store: new KeyvMemoryAdapter(new QuickLRU({ maxSize: 1000 })) });
KeyvBridgeAdapter wraps any promise-based / async store and adapts it to the v6 storage contract. Keyv applies it automatically when you pass:
capabilities.expires (i.e. pre-v6 third-party adapters), orMap-like store with async get, set, delete, and clear. For such a store to actually expire data, its set(key, value, ttl) must honor the relative millisecond ttl the bridge passes as the third argument — a plain Promise-wrapped Map that ignores it won't evict on its own. Keyv's checkExpired (on by default) still filters expired entries on read, but they linger in the store until read; for native eviction, prefer a full v6 adapter or a store that honors the ttl.This is why existing third-party adapters keep working unchanged on v6. The bridge:
expires timestamp; the bridge converts it back to the relative TTL the wrapped store expects. A write whose deadline has already elapsed is deleted instead of stored, so a past expires becomes an absent key — matching how the native adapters treat an already-expired write.getMany, setMany, has, hasMany, deleteMany, iterator, or disconnect, the bridge calls them directly; otherwise it falls back to looping over the single-key primitives.namespace property), the bridge propagates its namespace to the store and does not prefix keys, avoiding double-namespacing, so the store's native scoped clear() and iterator() are used. Otherwise the bridge prefixes keys itself, letting one shared store host multiple namespaces.error events from the wrapped store so connection failures surface on the Keyv instance.import Keyv, { KeyvBridgeAdapter } from 'keyv';
// Usually automatic — just pass the store:
const keyv = new Keyv({ store: myAsyncStore });
// ...which is equivalent to wrapping it explicitly. Put the namespace on the Keyv options —
// Keyv overwrites any namespace set on the adapter directly:
const explicit = new Keyv({ store: new KeyvBridgeAdapter(myAsyncStore), namespace: 'cache' });
JavaScript's built-in Map object has a practical limit of approximately 16.7 million entries (2^24). When you try to store more entries than this limit, you'll encounter performance degradation or runtime errors. This limitation is due to how JavaScript engines internally manage Map objects.
For applications that need to cache millions of entries in memory, this becomes a significant constraint. Common scenarios include:
@keyv/bigmap solves this limitation by using a distributed hash approach with multiple internal Map instances. Instead of storing all entries in a single Map, BigMap distributes entries across multiple Maps using a hash function. This allows you to scale beyond the 16.7 million entry limit while maintaining the familiar Map API.
BigMap can be used directly with Keyv as a storage adapter, providing scalable in-memory storage with full TTL support.
npm install --save keyv @keyv/bigmap
The simplest way to use BigMap with Keyv is through the createKeyv helper function:
import { createKeyv } from '@keyv/bigmap';
const keyv = createKeyv();
// Set values with TTL (time in milliseconds)
await keyv.set('user:1', { name: 'Alice', email: 'alice@example.com' }, 60000); // Expires in 60 seconds
// Get values
const user = await keyv.get('user:1');
console.log(user); // { name: 'Alice', email: 'alice@example.com' }
// Delete values
await keyv.delete('user:1');
// Clear all values
await keyv.clear();
For more details about BigMap, see the @keyv/bigmap documentation.
Keyv supports gzip, brotli and lz4 compression. To enable compression, pass the compress option to the constructor.
import Keyv from 'keyv';
import KeyvGzip from '@keyv/compress-gzip';
const keyvGzip = new KeyvGzip();
const keyv = new Keyv({ compression: keyvGzip });
import Keyv from 'keyv';
import KeyvBrotli from '@keyv/compress-brotli';
const keyvBrotli = new KeyvBrotli();
const keyv = new Keyv({ compression: keyvBrotli });
import Keyv from 'keyv';
import KeyvLz4 from '@keyv/compress-lz4';
const keyvLz4 = new KeyvLz4();
const keyv = new Keyv({ compression: keyvLz4 });
You can also pass a custom compression function to the compression option. Following the pattern of the official compression adapters.
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 KeyvCompressionAdapter {
compress(value: any, options?: any): Promise<any>;
decompress(value: any, options?: any): Promise<any>;
}
In addition to the interface, you can test it with our compression test suite using @keyv/test-suite:
import { keyvCompressionTests } from '@keyv/test-suite';
import KeyvGzip from '@keyv/compress-gzip';
keyvCompressionTests(test, new KeyvGzip());
Keyv supports pluggable encryption of stored values via the KeyvEncryptionAdapter interface. Pass an adapter with encrypt and decrypt methods using the encryption option (or set the .encryption property). Encryption runs on the serialized (and optionally compressed) value, so it requires a serializer — the built-in KeyvJsonSerializer is enabled by default.
interface KeyvEncryptionAdapter {
encrypt: (data: string) => string | Promise<string>;
decrypt: (data: string) => string | Promise<string>;
}
import Keyv from 'keyv';
const encryption = {
encrypt: async (data) => Buffer.from(data).toString('base64'),
decrypt: async (data) => Buffer.from(data, 'base64').toString('utf8'),
};
const keyv = new Keyv({ encryption });
await keyv.set('foo', 'bar'); // value is encrypted at rest
await keyv.get('foo'); // 'bar'
Keyv exports helper functions to check whether an object implements the expected interface for a Keyv instance, storage adapter, compression adapter, serialization adapter, or encryption adapter. Each function returns an object with a top-level compatible boolean (whether the object fully satisfies the interface) plus a methods record describing every method it looked for.
import {
detectKeyv,
detectKeyvStorage,
detectKeyvCompression,
detectKeyvSerialization,
detectKeyvEncryption,
} from 'keyv';
Every entry in the methods record has the shape { exists: boolean, methodType: "sync" | "async" | "none" }.
Returns a KeyvCapability: { compatible, methods, properties }. compatible is true only when all Keyv methods and properties are present.
import Keyv, { detectKeyv } from 'keyv';
const result = detectKeyv(new Keyv());
result.compatible; // true — all capabilities present
result.methods.get.exists; // true
result.methods.get.methodType; // "async"
result.properties.hooks; // true
result.properties.stats; // true
const partial = detectKeyv(new Map());
partial.compatible; // false — missing getMany, setMany, hooks, stats, etc.
partial.methods.get.exists; // true
Returns a KeyvStorageCapability: { compatible, store, methods }. compatible is true when the object is a usable storage adapter, and store reports the detected kind:
"keyvStorage" — implements the full async storage adapter interface (get, set, delete, clear, has, setMany, deleteMany, hasMany, all async)"mapLike" — has synchronous get, set, delete, and has (i.e. it behaves like a Map)"asyncMap" — has at least async get, set, delete, and clear"none" — not a usable storeimport { detectKeyvStorage } from 'keyv';
// Map-like object
const map = detectKeyvStorage(new Map());
map.compatible; // true
map.store; // "mapLike"
map.methods.get.methodType; // "sync"
// Async storage adapter
const adapter = {
get: async () => {}, set: async () => {}, delete: async () => {},
clear: async () => {}, has: async () => {}, setMany: async () => {},
deleteMany: async () => {}, hasMany: async () => {},
};
const adapterResult = detectKeyvStorage(adapter);
adapterResult.compatible; // true
adapterResult.store; // "keyvStorage"
adapterResult.methods.get.methodType; // "async"
Returns a KeyvCompressionCapability: { compatible, methods }. compatible is true when both compress and decompress methods are present.
import { detectKeyvCompression } from 'keyv';
const result = detectKeyvCompression({ compress: (d) => d, decompress: (d) => d });
result.compatible; // true
result.methods.compress.exists; // true
result.methods.decompress.exists; // true
Returns a KeyvSerializationCapability: { compatible, methods }. compatible is true when both stringify and parse methods are present.
import { detectKeyvSerialization } from 'keyv';
const result = detectKeyvSerialization(JSON);
result.compatible; // true
result.methods.stringify.exists; // true
result.methods.parse.exists; // true
Returns a KeyvEncryptionCapability: { compatible, methods }. compatible is true when both encrypt and decrypt methods are present.
import { detectKeyvEncryption } from 'keyv';
const result = detectKeyvEncryption({ encrypt: (d) => d, decrypt: (d) => d });
result.compatible; // true
result.methods.encrypt.exists; // true
result.methods.decrypt.exists; // true
Returns a new Keyv instance.
The Keyv instance is also an EventEmitter that will emit an 'error' event if the storage adapter connection fails.
Type: KeyvStorageAdapter
Default: undefined
The storage adapter instance to be used by Keyv.
Type: String
Default: undefined
This is the namespace for the current instance. When you set it it will set it also on the storage adapter.
Type: Object
The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.
Type: String
Default: undefined
Namespace for the current instance.
Type: Number
Default: undefined
Default TTL. Can be overridden by specififying a TTL on .set().
Type: KeyvCompressionAdapter
Default: undefined
Compression package to use. See Compression for more details.
Type: KeyvSerializationAdapter | false
Default: KeyvJsonSerializer (built-in)
A serialization object with stringify and parse methods. Set to false to disable serialization and store raw objects. See Serialization for more details.
Type: Storage adapter instance
Default: new Map()
The storage adapter instance to be used by Keyv.
Type: Boolean
Default: false
Enable statistics tracking (hits, misses, sets, deletes, errors). See .stats for details.
Type: Boolean
Default: false
Throw on all errors instead of only when there are no 'error' listeners. See .throwOnErrors for details.
Type: KeyvSanitizeOptions
Default: undefined
Enable sanitization of keys and namespaces by stripping dangerous patterns. See .sanitize for details.
Type: KeyvEncryptionAdapter
Default: undefined
Encryption adapter used to encrypt and decrypt stored values. See Encryption for details.
Type: Boolean
Default: true
When true (default), Keyv checks expiry at its own layer on get/getMany/has/hasMany in addition to the storage adapter. Set to false to trust the storage adapter alone. See .checkExpired for details.
Keys must always be strings. Values can be of any type.
Set a value.
By default keys are persistent. You can set an expiry TTL in milliseconds.
Returns a promise which resolves to true.
Set multiple values using KeyvEntry<Value> objects ({ key: string, value: Value, ttl?: number }). The Value type is inferred from the entries provided.
Returns a promise which resolves to the retrieved value, or undefined if the key does not exist or is expired. If an array of keys is passed it delegates to .getMany() and resolves to an array of values.
Returns a promise which resolves to an array of retrieved values, with undefined for keys that do not exist or are expired.
Returns a promise which resolves to the raw stored data for the key or undefined if the key does not exist or is expired.
Returns a promise which resolves to an array of raw stored data for the keys or undefined if the key does not exist or is expired.
Sets a raw value in the store without wrapping. This is the write-side counterpart to .getRaw(). The caller provides the KeyvValue envelope directly ({ value, expires? }) instead of having Keyv wrap it. The envelope is still serialized before storing so that all read paths (get(), getRaw(), has(), getManyRaw()) work consistently. If you need TTL-based expiration, set expires on the value directly (e.g. { value: 'bar', expires: Date.now() + 60000 }). The store-level TTL is derived automatically from value.expires.
Returns a promise which resolves to true.
const keyv = new Keyv();
// Set a raw value with expiration
await keyv.setRaw('foo', { value: 'bar', expires: Date.now() + 60000 });
// Set a raw value without expiration
await keyv.setRaw('foo', { value: 'bar' });
// Round-trip: get raw, modify, set raw
const raw = await keyv.getRaw('foo');
if (raw) {
raw.value = 'updated';
await keyv.setRaw('foo', raw);
}
Sets many raw values in the store without wrapping. Each entry should have a key and a value (KeyvValue envelope). Like setRaw(), the envelopes are serialized before storing and the store-level TTL is derived from each entry's value.expires.
Returns a promise which resolves to an array of booleans.
const keyv = new Keyv();
await keyv.setManyRaw([
{ key: 'foo', value: { value: 'bar' } },
{ key: 'baz', value: { value: 'qux', expires: Date.now() + 60000 } },
]);
Deletes an entry.
Returns a promise which resolves to true if the key existed, false if not.
Deletes multiple entries.
Returns a promise which resolves to true if all keys were deleted successfully, false otherwise.
Delete all entries in the current namespace.
Returns a promise which is resolved when the entries have been cleared.
Check if a key exists in the store.
Returns a promise which resolves to true if the key exists, false if not.
await keyv.set('foo', 'bar');
await keyv.has('foo'); // true
await keyv.has('unknown'); // false
Check if multiple keys exist in the store.
Returns a promise which resolves to an array of booleans indicating if each key exists.
await keyv.set('foo', 'bar');
await keyv.hasMany(['foo', 'unknown']); // [true, false]
Disconnect from the storage adapter. Emits a 'disconnect' event.
Returns a promise which is resolved when the connection has been closed.
await keyv.disconnect();
Iterate over all key-value pairs in the store. Automatically deserializes values, filters out expired entries, and deletes them.
Returns an async generator that yields [key, value] pairs. Use with for await...of:
for await (const [key, value] of keyv.iterator()) {
console.log(key, value);
}
The iterator works with any storage backend:
Symbol.iteratoriterator() method (e.g., Redis SCAN, SQL cursor)Type: String
The namespace for the current instance. This will define the namespace for the current instance and the storage adapter. If you set the namespace to undefined it will no longer do key prefixing.
const keyv = new Keyv({ namespace: 'my-namespace' });
console.log(keyv.namespace); // 'my-namespace'
here is an example of setting the namespace to undefined:
const keyv = new Keyv();
console.log(keyv.namespace); // undefined which is default
keyv.namespace = undefined;
console.log(keyv.namespace); // undefined
Type: Number
Default: undefined
Default TTL. Can be overridden by specififying a TTL on .set(). If set to undefined it will never expire.
const keyv = new Keyv({ ttl: 5000 });
console.log(keyv.ttl); // 5000
keyv.ttl = undefined;
console.log(keyv.ttl); // undefined (never expires)
Type: Storage adapter instance
Default: new Map()
The storage adapter instance to be used by Keyv. This will wire up the iterator, events, and more when a set happens. If it is not a valid Map or Storage Adapter it will throw an error.
import KeyvSqlite from '@keyv/sqlite';
const keyv = new Keyv();
console.log(keyv.store instanceof Map); // true
keyv.store = new KeyvSqlite('sqlite://path/to/database.sqlite');
console.log(keyv.store instanceof KeyvSqlite); // true
Type: KeyvSerializationAdapter | false | undefined
Default: KeyvJsonSerializer (built-in)
The serialization object used for storing and retrieving values. Set to false or undefined to disable serialization and use raw object pass-through. See Serialization for more details.
const keyv = new Keyv();
console.log(keyv.serialization); // KeyvJsonSerializer (default)
keyv.serialization = false; // disable serialization
console.log(keyv.serialization); // undefined
Type: KeyvCompressionAdapter
Default: undefined
This is the compression package to use. See Compression for more details. If it is undefined it will not compress (default).
import KeyvGzip from '@keyv/compress-gzip';
const keyv = new Keyv();
console.log(keyv.compression); // undefined
keyv.compression = new KeyvGzip();
console.log(keyv.compression); // KeyvGzip
Type: KeyvEncryptionAdapter
Default: undefined
The encryption adapter used to encrypt and decrypt stored values. If undefined (default) values are not encrypted. See Encryption for more details.
const keyv = new Keyv();
console.log(keyv.encryption); // undefined
keyv.encryption = {
encrypt: async (data) => Buffer.from(data).toString('base64'),
decrypt: async (data) => Buffer.from(data, 'base64').toString('utf8'),
};
console.log(keyv.encryption); // the encryption adapter
Type: Boolean
Default: true
A read-only property (configured via the checkExpired constructor option). When true (the default), Keyv checks expiry at its own layer on get, getMany, has, and hasMany, deleting any expired entries it encounters. It does this using the absolute expires stored in the serialized envelope, so reads stay millisecond-precise regardless of the adapter.
This defaults to true because some backends can return entries that are already logically expired: Memcached's exptime is second-granular (a value can linger up to ~1s past a sub-second deadline), and DynamoDB's native TTL is a background sweep that can lag by hours before it deletes expired items. Trusting the backend alone would surface those stale reads; the Keyv-layer check closes that gap.
Set it to false to trust the storage adapter to handle expiry on its own. That skips the extra decode + expiry check on every read (and lets has/hasMany use the adapter's native existence check), at the cost of backend-granularity expiry.
const keyv = new Keyv();
console.log(keyv.checkExpired); // true (default)
const trusting = new Keyv({ checkExpired: false });
console.log(trusting.checkExpired); // false
Type: Boolean
Default: false
If set to true, Keyv will throw an error if any operation fails. This is useful if you want to ensure that all operations are successful and you want to handle errors.
const keyv = new Keyv({ throwOnErrors: true });
console.log(keyv.throwOnErrors); // true
keyv.throwOnErrors = false;
console.log(keyv.throwOnErrors); // false
A good example of this is with the @keyv/redis storage adapter. If you want to handle connection errors, retries, and timeouts more gracefully, you can use the throwOnErrors option. This will throw an error if any operation fails, allowing you to catch it and handle it accordingly:
import Keyv from 'keyv';
import KeyvRedis from '@keyv/redis';
// create redis instance that will throw on connection error
const keyvRedis = new KeyvRedis('redis://user:pass@localhost:6379', { throwOnConnectErrors: true });
const keyv = new Keyv({ store: keyvRedis, throwOnErrors: true });
What this does is it only throw on connection errors with the Redis client.
Type: KeyvStats
Default: KeyvStats instance with enabled: false
The stats property provides access to statistics tracking for cache operations. When enabled via the stats option during initialization, it tracks hits, misses, sets, deletes, and errors. It also maintains LRU-bounded per-key frequency maps for each event type, allowing you to see which keys are accessed most.
const keyv = new Keyv({ stats: true });
console.log(keyv.stats.enabled); // true
Aggregate counters:
hits: Number of successful cache retrievalsmisses: Number of failed cache retrievalssets: Number of set operationsdeletes: Number of delete operationserrors: Number of errors encounteredPer-key LRU frequency maps (each capped at maxEntries, default 1000):
hitKeys: Map<string, number> — key to hit countmissKeys: Map<string, number> — key to miss countsetKeys: Map<string, number> — key to set countdeleteKeys: Map<string, number> — key to delete counterrorKeys: Map<string, number> — key to error countconst keyv = new Keyv({ stats: true });
await keyv.set('foo', 'bar');
await keyv.get('foo'); // cache hit
await keyv.get('nonexistent'); // cache miss
await keyv.delete('foo');
console.log(keyv.stats.hits); // 1
console.log(keyv.stats.misses); // 1
console.log(keyv.stats.sets); // 1
console.log(keyv.stats.deletes); // 1
// Per-key frequency maps
console.log(keyv.stats.hitKeys.get('foo')); // 1
console.log(keyv.stats.missKeys.get('nonexistent')); // 1
keyv.stats.reset();
console.log(keyv.stats.hits); // 0
console.log(keyv.stats.hitKeys.size); // 0
You can also manually enable/disable stats tracking at runtime. Disabling stats will automatically unsubscribe from events:
const keyv = new Keyv({ stats: false });
keyv.stats.enabled = true; // Enable stats tracking
// ... perform operations ...
keyv.stats.enabled = false; // Disable stats tracking and unsubscribe
You can create a KeyvStats instance independently and subscribe it to a Keyv instance:
import { KeyvStats } from 'keyv';
const stats = new KeyvStats({ enabled: true, maxEntries: 500, emitter: keyv });
Type: KeyvSanitize (configured via the sanitize option: KeyvSanitizeOptions)
Default: disabled
The .sanitize property is a KeyvSanitize adapter. It is configured through the sanitize constructor option (true, or a KeyvSanitizeOptions object) and disabled by default.
It detects and strips dangerous patterns from keys and namespaces to protect against SQL injection, MongoDB operator injection, path traversal, and control character attacks. Harmless characters like quotes, slashes, and dollar signs pass through unchanged — only dangerous patterns are stripped.
Results are cached in an LRU cache (10,000 entries) for fast repeated lookups.
| Category | Patterns Stripped | Purpose |
|---|---|---|
sql | ; -- /* | Prevents SQL injection |
mongo | leading $, {$ sequences | Prevents MongoDB operator injection |
escape | \0 \r \n | Strips null bytes, CRLF injection |
path | ../ ..\ | Prevents path traversal |
| Target | Default | Description |
|---|---|---|
keys | true (when enabled) | Sanitize keys on all operations |
namespace | true (when enabled) | Sanitize namespace on construction and setter |
Enable all sanitization:
const keyv = new Keyv({ sanitize: true });
await keyv.set("test; DROP TABLE", "value");
// Key is stored as "test DROP TABLE"
// Harmless characters pass through
await keyv.set("user's-data", "value");
// Key is stored as "user's-data" (unchanged)
Disable all sanitization (default):
const keyv = new Keyv({ sanitize: false });
Granular control per target and category:
const keyv = new Keyv({
sanitize: {
keys: { sql: true, mongo: false }, // only SQL patterns on keys
namespace: { path: true, sql: false }, // only path patterns on namespace
}
});
Disable namespace sanitization only:
const keyv = new Keyv({
sanitize: { keys: true, namespace: false }
});
Change at runtime by updating the options on the existing adapter, or by replacing it:
import { KeyvSanitize } from 'keyv';
// Update options on the existing adapter
keyv.sanitize.updateOptions({ keys: true, namespace: true }); // enable all
keyv.sanitize.updateOptions({ keys: { sql: true, mongo: false } }); // granular
// Or replace the adapter entirely
keyv.sanitize = new KeyvSanitize({ keys: true, namespace: true });
Sanitization is applied to all key-accepting methods: get, set, delete, has, getMany, setMany, deleteMany, hasMany, getRaw, getManyRaw, setRaw, and setManyRaw. Namespace sanitization is applied at construction and when the namespace setter is used.
We make a best effort to support Bun as a runtime. Our default and primary target is Node.js, but we run tests against Bun to ensure compatibility. If you encounter any issues while using Keyv with Bun, please report them at our GitHub issues.
We welcome contributions to Keyv! 🎉 Here are some guides to get you started with contributing:
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 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 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 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.
FAQs
Simple key-value storage with support for multiple backends
The npm package keyv receives a total of 83,488,448 weekly downloads. As such, keyv popularity was classified as popular.
We found that keyv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST disclosed an unreleased AI tool called V-etalon and opened a broad inquiry into NVD modernization after years of automation plans produced no public enrichment system.
Security News
In his AI Council 2026 talk, Feross Aboukhadijeh covers recent package compromises, vulnerability discovery, and a more automated security model.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.