We shipped Keyv 6.1.0, our first stable v6 release, on October 6. We planned to ship in August. After ChainDrop, I paused the release to change how we build and publish our packages. I wrote about those changes in my incident report.
Keyv tells the storage adapter when a key expires
This call stores a value for one minute. The same call works with an in-memory store or a Redis adapter.
import Keyv from 'keyv';
const cache = new Keyv();
await cache.set('user:123', { name: 'Jared' }, 60_000);
In v5, some adapters had to open the stored value and read its JSON to recover the deadline. That worked until someone added compression or changed the serializer. Then the adapter could miss the deadline and leave the entry in the database.
In v6, Keyv calculates the deadline once and passes it to the adapter alongside the value. A write that starts at noon with a one-minute TTL expires at 12:01, even if it takes two seconds to reach the store. The adapter can expire the entry on time even if the value is encrypted.
For v6 storage adapters, the third argument to store.set(key, value, expires) is a Unix timestamp in milliseconds. An undefined deadline means the entry has no expiration. An adapter sets capabilities.expires to true to tell Keyv it accepts that timestamp. For a v5 storage adapter, Keyv uses KeyvBridgeAdapter to convert the deadline back to the time left.
Keyv encrypts values before they reach the store
An application can add encryption to its Keyv instance and keep its existing storage adapter. On Node.js, @keyv/encrypt-node takes a random secret. The example reads that secret from KEYV_ENCRYPTION_KEY.
import Keyv from 'keyv';
import KeyvEncryptNode from '@keyv/encrypt-node';
const key = process.env.KEYV_ENCRYPTION_KEY;
if (!key) {
throw new Error('KEYV_ENCRYPTION_KEY is required');
}
const cache = new Keyv({ encryption: new KeyvEncryptNode({ key }) });
await cache.set('user:123', { name: 'Jared' }, 60_000);
const user = await cache.get('user:123'); // { name: 'Jared' }
The store sees the cache key user:123 and an encrypted value. Keyv decrypts the value on read. Encryption requires serialization, which Keyv enables by default. With serialization: false and encryption enabled, the write fails. Node.js encryption adapter docs
Keyv v6 now supports the browser
Browser apps can now use the same Keyv methods as server apps, including get, set, and delete. Keys can expire in either environment. In this example, Keyv keeps a product list in memory for one minute. During that minute, the app can read the list without another API call.
import Keyv from 'keyv';
const cache = new Keyv({ store: new Map() });
async function getProducts() {
const cached = await cache.get('products');
if (cached !== undefined) return cached;
const response = await fetch('/api/products');
if (!response.ok) throw new Error('Could not load products');
const products = await response.json();
await cache.set('products', products, 60_000);
return products;
}
A page reload clears this cache because the map lives in memory. For apps that use Web Crypto, v6 also includes @keyv/encrypt-web. A browser bundle exposes any server secret it contains.
Keyv v6 also runs in Cloudflare Workers
A Cloudflare Worker can use the same get and set calls. The @keyv/cloudflare-kv adapter uses the Worker's KV namespace binding to store values across requests. Cloudflare KV adapter docs
This Worker reads a product list from a KV namespace with a binding named CACHE. It returns an empty list if the key is missing.
import Keyv from 'keyv';
import KeyvCloudflareKV from '@keyv/cloudflare-kv';
export default {
async fetch(request, env) {
const cache = new Keyv(new KeyvCloudflareKV(env.CACHE));
const products = await cache.get('products');
return Response.json(products ?? []);
},
};
Migration checks for Keyv v5 applications
The first migration check is whether v6 can read a key that v5 wrote. A test that writes and reads a fresh key in v6 can pass even when the app misses every old entry.
For example, a default v5 Redis setup could store foo as keyv::keyv:foo. In v6, Keyv has no default namespace. Adapters that join a namespace and a key use :: by default. The settings that preserve access to old keys depend on the adapter and its original configuration. The migration guide shows the key layouts, including the separate case for Redis users who called createKeyv().
- Runtime. Keyv v6 requires Node.js 22.19.0 or later for server apps that run on Node.js.
- Packages. The application pins Keyv and its official adapters to the same exact v6 release.
- Backup. A backup preserves the original data before the first v6 connection. SQLite converts its table on that connection.
- Existing keys. A migration test uses a copy of the store. After the adapter migration, v6 should return the expected value for a known v5 key.
- Redis connection. In JavaScript,
new Keyv('redis://…')can silently use an in-memory store in v6. The application needs an explicit Redis adapter. To check the connection, a test starts two independent instances with the application's Redis configuration and namespace. The first writes a unique key. The second must read the same value. A read from the first instance alone can pass with an in-memory store. - Expiration. The test writes a new key with a short TTL. After the deadline,
getshould returnundefined.
An application that can rebuild its cache can let it fill again. Teams that need more time can stay on v5, which still receives maintenance and security fixes. For migration issues, the adapter name, namespace settings, and a small example help the maintainers reproduce the problem. Keyv issue tracker
