Keyv API

Table of Contents

Simple key-value storage with support for multiple backends

build bun browser codecov npm npm

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 JSON types plus Buffer and BigInt via the built-in KeyvJsonSerializer
  • 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

Table of Contents

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/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';

Type-safe Usage

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.

Example with Instance-level Generic Type:

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

Example with Method-level Generic Type:

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.

Using Storage Adapters

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.

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(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'

Events

Keyv is a custom EventEmitter and will emit an 'error' event if there is an error. If there is no listener for the 'error' event, an uncaught exception will be thrown. To disable the 'error' event, pass emitErrors: false in the constructor options.

const keyv = new Keyv({ emitErrors: false });

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);

Hooks

Keyv supports hooks for get, set, and delete methods. Hooks are useful for logging, debugging, and other custom functionality. Here is a list of all the hooks:

PRE_GET
    POST_GET
    PRE_GET_RAW
    POST_GET_RAW
    PRE_GET_MANY
    POST_GET_MANY
    PRE_GET_MANY_RAW
    POST_GET_MANY_RAW
    PRE_SET
    POST_SET
    PRE_SET_RAW
    POST_SET_RAW
    PRE_SET_MANY_RAW
    POST_SET_MANY_RAW
    PRE_DELETE
    POST_DELETE

You can access this by importing KeyvHooks from the main Keyv package.

import Keyv, { KeyvHooks } from 'keyv';

Get Hooks

The POST_GET and POST_GET_RAW hooks fire on both cache hits and misses. When a cache miss occurs (key doesn't exist or is expired), the hooks receive undefined as the value.

// POST_GET hook - fires on both hits and misses
    const keyv = new Keyv();
    keyv.hooks.addHandler(KeyvHooks.POST_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
    
// POST_GET_RAW hook - same behavior as POST_GET
    const keyv = new Keyv();
    keyv.hooks.addHandler(KeyvHooks.POST_GET_RAW, (data) => {
      console.log(`Key: ${data.key}, Value:`, data.value);
    });
    
    await keyv.getRaw('foo'); // Logs with value or undefined

Set Hooks

//PRE_SET hook
    const keyv = new Keyv();
    keyv.hooks.addHandler(KeyvHooks.PRE_SET, (data) => console.log(`Setting key ${data.key} to ${data.value}`));
    
    //POST_SET hook
    const keyv = new Keyv();
    keyv.hooks.addHandler(KeyvHooks.POST_SET, ({key, value}) => console.log(`Set key ${key} to ${value}`));

In these examples 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.hooks.addHandler(KeyvHooks.PRE_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.

Delete Hooks

In PRE_DELETE and POST_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.

Serialization

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.

Official Serializers

In addition to the built-in serializer, Keyv offers two official serialization packages:

SuperJSON

@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 });

MessagePack (msgpackr)

@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() });

Custom Serializers

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: (data: string) => T | Promise;
    }

Disabling Serialization

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 });

Pipeline

When serialization and/or compression are configured, Keyv applies them in this order:

On set: serialize (optional) → compress (optional) → store

On get: store → decompress (optional) → parse (optional) → value

If compression is configured without a serializer, Keyv will use JSON.stringify/JSON.parse as a minimum fallback since compression adapters require string input.

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.

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

Third-party Storage Adapters

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/

Using BigMap to Scale

Understanding JavaScript Map Limitations

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:

  • High-traffic caching layers
  • Session stores for large-scale applications
  • In-memory data processing of large datasets
  • Real-time analytics with millions of data points

Why BigMap?

@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.

Key Benefits:

  • Scales beyond Map limits: Store 20+ million entries without issues
  • Map-compatible API: Drop-in replacement for standard Map
  • Performance: Uses efficient DJB2 hashing for fast key distribution
  • Type-safe: Built with TypeScript and supports generics
  • Customizable: Configure store size and hash functions

Using BigMap with Keyv

BigMap can be used directly with Keyv as a storage adapter, providing scalable in-memory storage with full TTL support.

Installation

npm install --save keyv @keyv/bigmap

Basic Usage

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: '[email protected]' }, 60000); // Expires in 60 seconds
    
    // Get values
    const user = await keyv.get('user:1');
    console.log(user); // { name: 'Alice', email: '[email protected]' }
    
    // Delete values
    await keyv.delete('user:1');
    
    // Clear all values
    await keyv.clear();

For more details about BigMap, see the @keyv/bigmap documentation.

Compression

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.

Want to build your own KeyvCompressionAdapter?

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());

Encryption

Keyv provides a KeyvEncryptionAdapter interface for encryption support. This interface is available for custom implementations but is not yet wired into the core pipeline.

interface KeyvEncryptionAdapter {
      encrypt: (data: string) => string | Promise<string>;
      decrypt: (data: string) => string | Promise<string>;
    }

Capability Detection

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 boolean flags for every capability, plus a top-level boolean indicating whether the object fully satisfies the interface.

import {
      detectKeyv,
      detectKeyvStorage,
      detectKeyvCompression,
      detectKeyvSerialization,
      detectKeyvEncryption,
      detectCapabilities,
    } from 'keyv';

detectKeyv(obj)

Returns a KeyvCapability with a boolean for each Keyv method/property. The keyv flag is true only when all capabilities are present.

import Keyv, { detectKeyv } from 'keyv';
    
    detectKeyv(new Keyv());
    // { keyv: true, get: true, set: true, delete: true, clear: true, has: true,
    //   getMany: true, setMany: true, deleteMany: true, hasMany: true,
    //   disconnect: true, getRaw: true, getManyRaw: true, setRaw: true,
    //   setManyRaw: true, hooks: true, stats: true, iterator: true }
    
    detectKeyv(new Map());
    // { keyv: false, get: true, set: true, ... }

detectKeyvStorage(obj)

Returns a KeyvStorageCapability. The keyvStorage flag is true when the object has get, set, delete, clear, has, setMany, deleteMany, and hasMany.

The result also includes:

  • mapLike — true when the object has synchronous get, set, delete, has, entries, and keys methods (i.e. it behaves like a Map)
  • methodTypes — a record mapping each method name to "sync", "async", or "none" (not present)
import { detectKeyvStorage } from 'keyv';
    
    // Map-like object
    const result = detectKeyvStorage(new Map());
    result.mapLike; // true
    result.methodTypes.get; // "sync"
    result.methodTypes.set; // "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.keyvStorage; // true
    adapterResult.mapLike; // false
    adapterResult.methodTypes.get; // "async"

detectKeyvCompression(obj)

Returns a KeyvCompressionCapability. The keyvCompression flag is true when both compress and decompress methods are present.

import { detectKeyvCompression } from 'keyv';
    
    detectKeyvCompression({ compress: (d) => d, decompress: (d) => d });
    // { keyvCompression: true, compress: true, decompress: true }

detectKeyvSerialization(obj)

Returns a KeyvSerializationCapability. The keyvSerialization flag is true when both stringify and parse methods are present.

import { detectKeyvSerialization } from 'keyv';
    
    detectKeyvSerialization(JSON);
    // { keyvSerialization: true, stringify: true, parse: true }

detectKeyvEncryption(obj)

Returns a KeyvEncryptionCapability. The keyvEncryption flag is true when both encrypt and decrypt methods are present.

import { detectKeyvEncryption } from 'keyv';
    
    detectKeyvEncryption({ encrypt: (d) => d, decrypt: (d) => d });
    // { keyvEncryption: true, encrypt: true, decrypt: true }

detectCapabilities(obj, spec)

A generic helper for building your own capability checks. Accepts a CapabilitySpec describing which methods and properties to look for, which are required, and the name of the composite boolean key.

import { detectCapabilities } from 'keyv';
    
    const result = detectCapabilities(myObject, {
      methods: ['read', 'write'],
      properties: ['name'],
      requiredKeys: ['read', 'write', 'name'],
      compositeKey: 'isValid',
    });
    // { isValid: true/false, read: true/false, write: true/false, name: true/false }

API

new Keyv([storage-adapter], [options]) or new Keyv([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.

storage-adapter

Type: KeyvStorageAdapter Default: undefined

The storage adapter instance to be used by Keyv.

.namespace

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.

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: undefined

Namespace for the current instance.

options.ttl

Type: Number Default: undefined

Default TTL. Can be overridden by specififying a TTL on .set().

options.compression

Type: KeyvCompressionAdapter Default: undefined

Compression package to use. See Compression for more details.

options.serialization

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.

options.store

Type: Storage adapter instance Default: new Map()

The storage adapter instance to be used by Keyv.

Keyv 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 a promise which resolves to true.

.setMany(entries)

Set multiple values using KeyvEntry objects ({ key: string, value: Value, ttl?: number }). The Value type is inferred from the entries provided.

.get(key, [options])

Returns a promise which resolves to the retrieved value.

.getMany(keys, [options])

Returns a promise which resolves to an array of retrieved values.

.getRaw(key)

Returns a promise which resolves to the raw stored data for the key or undefined if the key does not exist or is expired.

.getManyRaw(keys)

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.

.setRaw(key, value)

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);
    }

.setManyRaw(entries)

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 } },
    ]);

.delete(key)

Deletes an entry.

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

.deleteMany(keys)

Deletes multiple entries. Returns a promise which resolves to true if all keys were deleted successfully, false otherwise.

.clear()

Delete all entries in the current namespace.

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

.has(key)

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

.hasMany(keys)

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()

Disconnect from the storage adapter. Emits a 'disconnect' event.

Returns a promise which is resolved when the connection has been closed.

await keyv.disconnect();

.iterator()

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:

  • Map stores: iterates using the built-in Symbol.iterator
  • Storage adapters: delegates to the adapter's iterator() method (e.g., Redis SCAN, SQL cursor)
  • Unsupported stores: emits an error event if the store does not support iteration

API - Properties

.namespace

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

.ttl

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)

.store

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

.serialization

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

.compression

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

.useKeyPrefix

Type: Boolean Default: true

If set to true Keyv will prefix all keys with the namespace. This is useful if you want to avoid collisions with other data in your storage.

const keyv = new Keyv({ useKeyPrefix: false });
    console.log(keyv.useKeyPrefix); // false
    keyv.useKeyPrefix = true;
    console.log(keyv.useKeyPrefix); // true

With many of the storage adapters you will also need to set the namespace option to undefined to have it work correctly. This is because in v5 we started the transition to having the storage adapter handle the namespacing and Keyv will no longer handle it internally via KeyPrefixing. Here is an example of doing ith with KeyvSqlite:

import Keyv from 'keyv';
    import KeyvSqlite from '@keyv/sqlite';
    
    const store = new KeyvSqlite('sqlite://path/to/database.sqlite');
    const keyv = new Keyv({ store });
    keyv.useKeyPrefix = false; // disable key prefixing
    store.namespace = undefined; // disable namespacing in the storage adapter
    
    await keyv.set('foo', 'bar'); // true
    await keyv.get('foo'); // 'bar'
    await keyv.clear();

.emitErrors

Type: Boolean Default: true

If set to true, Keyv will emit an 'error' event when an error occurs. Set to false to suppress error events.

const keyv = new Keyv({ emitErrors: false });
    console.log(keyv.emitErrors); // false
    keyv.emitErrors = true;
    console.log(keyv.emitErrors); // true

.throwOnErrors

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.

.stats

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.

Enabling Stats:

const keyv = new Keyv({ stats: true });
    console.log(keyv.stats.enabled); // true

Available Statistics:

Aggregate counters:

  • hits: Number of successful cache retrievals
  • misses: Number of failed cache retrievals
  • sets: Number of set operations
  • deletes: Number of delete operations
  • errors: Number of errors encountered

Per-key LRU frequency maps (each capped at maxEntries, default 1000):

  • hitKeys: Map — key to hit count
  • missKeys: Map — key to miss count
  • setKeys: Map — key to set count
  • deleteKeys: Map — key to delete count
  • errorKeys: Map — key to error count

Accessing Stats:

const 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

Resetting Stats:

keyv.stats.reset();
    console.log(keyv.stats.hits); // 0
    console.log(keyv.stats.hitKeys.size); // 0

Manual Control:

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

Standalone Usage:

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 });

.sanitize

Type: boolean | KeyvSanitizeOptions Default: false

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.

Pattern Categories

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

Targets

Target Default Description
keys true (when enabled) Sanitize keys on all operations
namespace true (when enabled) Sanitize namespace on construction and setter

Usage

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:

keyv.sanitize = false; // disable
    keyv.sanitize = true;  // enable all
    keyv.sanitize = { keys: { sql: true, mongo: false } }; // granular

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.

Bun Support

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.

How to Contribute

We welcome contributions to Keyv! 🎉 Here are some guides to get you started with contributing:

License

MIT © Jared Wray

Table of Contents