Keyv Documentation

Keyv v5 includes several significant improvements:

• TypeScript Support: Full native TypeScript support.
• ESM Support: Written in ESM with full support.
• Event Emitter: Emits events for set, delete, clear, and error without third-party dependencies.
• Built-in Statistics: Tracks hits, misses, sets, deletes, and errors.
• Hooks: Provides pre and post processing hooks for set(), get(), getMany(), and delete().

When serialization, compression, and/or encryption are configured, Keyv applies them in a specific order:

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

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

Compression and encryption only run if a serializer is configured. If serialization: false is used, values are passed to the store as-is.

Keyv provides a consistent interface for key-value storage across multiple backends. By default, it uses in-memory storage. To use persistent backends, you must install a specific storage adapter (e.g., @keyv/redis).

import Keyv from 'keyv';

const keyv = new Keyv();
await keyv.set('foo', 'bar');
await keyv.get('foo'); // 'bar'

To use Keyv with Redis in a NestJS project, install the cacheable package and the @keyv/redis adapter:

$ npm install cacheable @keyv/redis --save

Keyv computes an absolute expiry (Unix timestamp in milliseconds) and sends it to Redis using the PXAT option. This ensures immunity to clock skew and network latency.

• Redis 6.2+: Uses PXAT for absolute expiry.
• Older versions: Automatically falls back to the relative PX option (remaining lifetime in milliseconds).

No manual configuration is required; the adapter detects the Redis version on the first expiring write and caches the result.

To use @keyv/redis in a NestJS application, follow these steps:

1. Install dependencies: npm install @keyv/redis keyv @nestjs/cache-manager cache-manager cacheable

2. Create a Cache Module using NestCacheModule.registerAsync and createKeyv.

3. Register the module in your AppModule.

4. Create a Cache Service that injects CACHE_MANAGER to provide a typed wrapper for get, set, and delete operations.

import { Module } from '@nestjs/common';
import { CacheModule as NestCacheModule } from '@nestjs/cache-manager';
import { createKeyv } from '@keyv/redis';

@Module({
  imports: [
    NestCacheModule.registerAsync({
      useFactory: () => ({
        stores: [createKeyv('redis://localhost:6379')],
      }),
    }),
  ],
  providers: [],
  exports: [],
})
export class CacheModule {}

Any store that implements the Map API can be used as a Keyv store. Keyv will wrap these adapters in TTL functionality and handle complex types internally.

import Keyv from 'keyv';
import myAdapter from 'my-adapter';

const keyv = new Keyv({ store: myAdapter });

Enabling Write-Ahead Logging (WAL) mode can significantly improve concurrency and write performance. In WAL mode, readers do not block writers and vice versa.

Note: WAL mode is not supported for in-memory databases (:memory:). If enabled for an in-memory database, a warning will be logged and the option will be ignored.

const store = new KeyvSqlite({
  uri: 'sqlite://path/to/database.sqlite',
  wal: true,
});

Namespaces prefix every key with namespace:. To ensure isolation, it is recommended to give each namespace its own KeyvMemcache instance.

Warning: The clear() method always flushes the entire Memcached server because Memcached cannot enumerate keys; it is not scoped to a namespace.

import Keyv from 'keyv';
import KeyvMemcache from '@keyv/memcache';

const keyv1 = new Keyv({ store: new KeyvMemcache('localhost:11211'), namespace: "namespace1" });
const keyv2 = new Keyv({ store: new KeyvMemcache('localhost:11211'), namespace: "namespace2" });

//set
await keyv1.set("foo","bar1", 6000)
await keyv2.set("foo","bar2", 6000)

//get
const obj1 = await keyv1.get("foo"); //will return bar1
const obj2 = await keyv2.get("foo"); //will return bar2