# @keyv/valkey

> Valkey storage adapter for Keyv

Latest version **1.0.11** (published 2025-11-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @keyv/valkey
pnpm add @keyv/valkey
yarn add @keyv/valkey
bun add @keyv/valkey
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.11 |
| Published | 2025-11-11 |
| First published | 2024-10-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 18 |
| Dependencies | 1 |
| Unpacked size | 77 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3200 |
| Author | Jared Wray |
| Maintainers | jaredwray |
| Keywords | redis, valkey, valkeyio, ioredis, keyv, storage, adapter, key, value, store, cache, ttl |

## Links

- npm: https://www.npmjs.com/package/@keyv/valkey
- Repository: https://github.com/jaredwray/keyv
- Issues: https://github.com/jaredwray/keyv/issues
- npm.io page: https://npm.io/package/@keyv/valkey

## Dependencies (1)

- [iovalkey](https://npm.io/package/iovalkey.md) ^0.3.3

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 1.0.11 (latest) — 2025-11-11
- 6.0.0-rc.1 (rc) — 2026-08-03
- 6.0.0-beta.4 (beta) — 2026-06-18
- 6.0.0-alpha.3 (alpha) — 2026-03-22
- 6.0.0-beta.3 — 2026-06-11
- 6.0.0-alpha.2 — 2026-03-04
- 6.0.0-alpha.1 — 2026-02-26
- 1.0.10 — 2025-10-10
- 1.0.9 — 2025-10-03
- 1.0.8 — 2025-08-02
- 1.0.7 — 2025-07-09
- 1.0.6 — 2025-06-21
- 1.0.5 — 2025-06-21
- 1.0.4 — 2025-06-10
- 1.0.3 — 2025-02-18
- … 3 more at https://npm.io/package/@keyv/valkey/versions

## README

# @keyv/valkey [<img width="100" align="right" src="https://jaredwray.com/images/keyv-symbol.svg" alt="keyv">](https://github.com/jaredwra/keyv)

> Valkey storage adapter for Keyv

[![build](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml)
[![codecov](https://codecov.io/gh/jaredwray/keyv/branch/main/graph/badge.svg?token=bRzR3RyOXZ)](https://codecov.io/gh/jaredwray/keyv)
[![npm](https://img.shields.io/npm/v/@keyv/valkey.svg)](https://www.npmjs.com/package/@keyv/valkey)
[![npm](https://img.shields.io/npm/dm/@keyv/valkey)](https://npmjs.com/package/@keyv/valkey)

[Valkey](https://valkey.io) storage adapter for [Keyv](https://github.com/jaredwray/keyv).

Valkey is the open source replacement to Redis which decided to do a [dual license](https://redis.com/blog/redis-adopts-dual-source-available-licensing/) approach moving forward. Valkey is a drop-in replacement for Redis and is fully compatible with the Redis protocol.

We are using the [iovalkey](https://www.npmjs.com/package/iovalkey) which is a Node.js client for Valkey based on the `ioredis` client.

# Install

```shell
npm install --save keyv @keyv/valkey
```

# Usage

This is using the helper `createKeyv` function to create a Keyv instance with the Valkey storage adapter:

```js
import {createKeyv} from '@keyv/valkey';

const keyv = createKeyv('redis://localhost:6379');
keyv.on('error', handleConnectionError);
await keyv.set('foo', 'bar');
console.log(await keyv.get('foo')); // 'bar'
```

If you want to specify the `KeyvValkey` class directly, you can do so:

```js
import Keyv from 'keyv';
import KeyvValkey from '@keyv/valkey';

const keyv = new Keyv(new KeyvValkey('redis://user:pass@localhost:6379', { disable_resubscribing: true }));
```

Or you can manually create a storage adapter instance and pass it to Keyv:

```js
import Keyv from 'keyv';
import KeyvValkey from '@keyv/valkey';

const KeyvValkey = new KeyvValkey('redis://user:pass@localhost:6379');
const keyv = new Keyv({ store: KeyvValkey });
```

Or reuse a previous Redis instance:

```js
import Keyv from 'keyv';
import Redis from 'iovalkey';
import KeyvValkey from '@keyv/valkey';

const redis = new Redis('redis://user:pass@localhost:6379');
const KeyvValkey = new KeyvValkey(redis);
const keyv = new Keyv({ store: KeyvValkey });
```

Or reuse a previous Redis cluster:

```js
import Keyv from 'keyv';
import Redis from 'iovalkey';
import KeyvValkey from '@keyv/valkey';

const redis = new Redis.Cluster('redis://user:pass@localhost:6379');
const KeyvValkey = new KeyvValkey(redis);
const keyv = new Keyv({ store: KeyvValkey });
```
# Options

## useRedisSets

The `useRedisSets` option lets you decide whether to use Redis sets for key management. By default, this option is set to `true`.

When `useRedisSets` is enabled (`true`):

- A namespace for the Redis sets is created, and all created keys are added to this. This allows for group management of keys.
- When a key is deleted, it's removed not only from the main storage but also from the Redis set.
- When clearing all keys (using the `clear` function), all keys in the Redis set are looked up for deletion. The set itself is also deleted.

**Note**: In high-performance scenarios, enabling `useRedisSets` might lead to memory leaks. If you're running a high-performance application or service, it is recommended to set `useRedisSets` to `false`.

If you decide to set `useRedisSets` as `false`, keys will be handled individually and Redis sets won't be utilized.

However, please note that setting `useRedisSets` to `false` could lead to performance issues in production when using the `clear` function, as it will need to iterate over all keys to delete them.

## Example

Here's how you can use the `useRedisSets` option:

```js
import Keyv from 'keyv';

const keyv = new Keyv(new KeyvValkey('redis://user:pass@localhost:6379', { useRedisSets: false }));
```

## License

[MIT © Jared Wray](LISCENCE)

---
_Source: https://npm.io/package/@keyv/valkey · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._