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/ valkey-glide/ 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
- valkey-glide - Valkey GLIDE storage adapter
Compression Adapters
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/storage-adapters/third-party/
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
Keyv v6 is the current stable release, starting with 6.1.0. It includes several major changes such as improved TypeScript support, enhanced hooks system, and streamlined storage adapter interfaces. See the full migration guide at https://keyv.org/docs/migration/v5-to-v6/ (coming from v4? start with https://keyv.org/docs/migration/v4-to-v5/).
Using an AI coding agent? Tell it: "Upgrade this project to Keyv v6 using https://keyv.org/skills/migrate". The migration skill lives in skills/keyv-migrate and can also be installed with npx skills add jaredwray/keyv --skill keyv-migrate.
The previous documentation site is archived at https://keyv.org/v5/.
No major functionality will be added to Keyv v5. Only maintenance and security fixes will be applied going forward.
License
MIT © Jared Wray
