Simple key-value storage with support for multiple backends

Getting Started

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.

Install Keyv:

npm install keyv

By default everything is stored in memory. You can optionally install a storage adapter for persistent backends:

npm install @keyv/redis

Use it:

import Keyv from 'keyv';

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

For the full API documentation, see the Keyv README.

Project Structure

This monorepo is organized into categorized directories:

core/             Core packages
  keyv/             Main Keyv library
  test-suite/       Shared test suite for API compliance
  bigmap/           Scalable in-memory Map
serialization/    Serialization packages
  superjson/        SuperJSON serializer (@keyv/serialize-superjson)
  msgpackr/         MessagePack serializer (@keyv/serialize-msgpackr)
compression/      Compression adapters
  compress-brotli/
  compress-gzip/
  compress-lz4/
storage/          Storage adapters
  redis/  postgres/  mysql/  mongo/  sqlite/
  memcache/  etcd/  valkey/  dynamo/  cloudflare-kv/
website/          Documentation website (keyv.org)

Packages

• keyv - Simple key-value storage with support for multiple backends
• test-suite - Test suite for Keyv API compliance
• bigmap - Scalable in-memory Map

Storage Adapters

• cloudflare-kv - Cloudflare Workers KV storage adapter
• dynamo - DynamoDB storage adapter
• etcd - Etcd storage adapter
• memcache - Memcache storage adapter
• mongo - MongoDB storage adapter
• mysql - MySQL/MariaDB storage adapter
• postgres - PostgreSQL storage adapter
• redis - Redis storage adapter
• sqlite - SQLite storage adapter
• valkey - Valkey (Open Source Redis) storage adapter

Compression Adapters

• compress-brotli - Brotli compression adapter
• compress-gzip - Gzip compression adapter
• compress-lz4 - LZ4 compression adapter

Serialization

The default serializer (KeyvJsonSerializer) is built into the core keyv package. Alternative serializers are available as separate packages:

• serialize-superjson - SuperJSON serializer with Date, Map, Set, BigInt support (@keyv/serialize-superjson)
• serialize-msgpackr - High-performance MessagePack serializer (@keyv/serialize-msgpackr)

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.

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/

Contributing

We welcome contributions! Here are some ways to get involved:

• Pull Requests - Fork the repo, make your changes, run pnpm test, and open a PR. See CONTRIBUTING.md for detailed instructions.
• Issues - Report bugs or request features by opening an issue. For bugs, include replication steps and error messages.
• Questions - Create an issue with the label "question" and include relevant context.
• Storage Adapter Requests - Create an issue with the label "storage adapter." Requests are given 30-60 days for community interest before being triaged.
• Security - See our security policy for reporting vulnerabilities.
• Code of Conduct - Please review our Code of Conduct.

Keyv v5 to v6

We are actively working on Keyv v6, which includes several major changes such as improved TypeScript support, enhanced hooks system, and streamlined storage adapter interfaces. You can follow along with the development and see the full migration guide at https://keyv.org/docs/keyv-v5-to-v6

No major functionality will be added to Keyv v5. Only maintenance and security fixes will be applied going forward.

License

MIT © Jared Wray