keyv

Keyv gives Node.js applications a single, consistent Promise-based interface for key-value storage, so the same get/set/delete calls work whether the data lives in memory, Redis, MongoDB, SQLite, Postgres, MySQL, Etcd, Memcache, DynamoDB, or a custom store. It ships with an in-memory default so it works with zero configuration, and TTL-based expiry is built into the core, making it equally suited as a cache or a persistent key-value store.

Beyond basic storage, Keyv layers in namespaces to avoid key collisions across shared stores, a hooks system that fires before/after every operation, optional stats tracking for hit/miss/error counts, and a pluggable serialization pipeline (serialize -> compress -> encrypt) with official SuperJSON and MessagePack serializers plus gzip/brotli/lz4 compression adapters. Its v6 storage-adapter contract passes adapters an absolute expiry timestamp instead of a relative TTL, and a bridge adapter transparently converts this back for any legacy or third-party store, so the whole storage-adapter ecosystem can upgrade independently of application code.

What You Get

• A single npm install (keyv) that works with in-memory storage out of the box, no database required to get started
• Official adapters for Redis, Valkey, MongoDB, SQLite, Postgres, MySQL, Etcd, Memcache, DynamoDB, and Cloudflare KV, all covered by a shared conformance test suite (@keyv/test-suite)
• A hooks and stats system for logging, key rewriting, and cache observability without wrapping the client yourself
• TypeScript types with instance- and method-level generics for type-safe values
• Pluggable serialization (JSON built-in, SuperJSON/MessagePack official), compression (gzip/brotli/lz4), and encryption adapters

Common Use Cases

• Drop-in response or query caching layer in front of slow APIs or databases
• Swapping storage backends (memory -> Redis -> Postgres) without touching application code
• Multi-tenant namespace isolation on a single shared store
• Session and token storage with millisecond-precise TTL expiry

Under The Hood

Architecture The monorepo is organized into core/, serialization/, compression/, and storage/ package groups managed via pnpm workspaces, but the design center is core/keyv/src/keyv.ts’s single Keyv class, which extends the Hookified event emitter and resolves whatever is passed as a store via resolveStore() into one of three concrete adapters: a v6-native adapter used directly when it declares capabilities.expires === true, KeyvMemoryAdapter for synchronous Map-like stores, or KeyvBridgeAdapter for async/legacy stores lacking the v6 contract. Every operation (get/set/delete/has/clear/iterator) runs a uniform pipeline — sanitize key, fire a BEFORE_* hook, call the resolved store, encode/decode through the serialization chain, fire an AFTER_* hook, emit telemetry — giving predictable extension points without subclassing.

Tech Stack The core package is TypeScript, built per-package with tsdown into dual ESM/CJS output with generated .d.ts files, linted and formatted by Biome (biome check --error-on-warnings) rather than separate ESLint/Prettier tooling, and tested with Vitest plus @vitest/coverage-v8. hookified is the only runtime dependency, supplying the hook/event-emitter base class. Each storage backend (redis, mongo, mysql, postgres, sqlite, memcache, etcd, dynamo, valkey, cloudflare-kv) is an independent workspace package validated against the shared @keyv/test-suite contract tests, and a dedicated website/ package builds and deploys the documentation site via its own GitHub Actions workflow.

Code Quality The core keyv package alone has 19 Vitest test files covering the constructor, every public method, hooks, sanitization, stats, and both built-in adapters, using @faker-js/faker for realistic fixtures and vi mocks for isolation; coverage is tracked with @vitest/coverage-v8 and reported to Codecov. Errors from store operations are caught and emitted as typed error events rather than thrown by default (with an opt-in throwOnErrors mode), methods carry extensive TSDoc comments, and CI (tests.yaml, bun-test.yaml, browser-compat.yaml) runs the suite across Node, Bun, and browser environments to catch cross-runtime regressions. No missing-test gaps were found.

API Design The public surface stays small and predictable — get/set/delete/has/clear plus *Many and *Raw variants — while still exposing advanced needs (custom serialization/compression/encryption, per-operation hooks, opt-in stats, key/namespace sanitization against injection) without those concerns leaking into core method signatures. Getting started requires only new Keyv() with an in-memory default and no required configuration; swapping to a real backend is a one-line change to the constructor argument. The detectKeyv* family of capability-detection helpers lets custom adapters, serializers, and compressors self-verify compliance with the expected interface, and the v6 absolute-expires contract with automatic KeyvBridgeAdapter fallback lets older third-party adapters keep working unmodified while newer ones opt into a faster, more precise path.