Universal key-value and caching engine with zero-dependency core, pluggable storage adapters, multi-tier caching, and built-in cache stampede protection.
🎮 Launch the Interactive Web Playground & Stampede Simulator — Test multi-tier caching and simulate 5,000 concurrent stampede requests directly in your browser!
What happens when a hot cache key expires while 1,000 concurrent users request it simultaneously?
| Metric | Traditional Uncoalesced Caching | kvdock.getOrSet() |
Net Impact |
|---|---|---|---|
| Incoming Concurrent Requests | 1,000 | 1,000 | Identical load |
| Primary Database Hits | 1,000 queries (Thundering Herd) | 1 query (Single-Flight) | 99.9% DB load reduction |
| Coalesced Waiting Callers | 0 | 999 | Zero lock contention |
| DB Connection Pool Exhaustion | 💥 Critical Spike | 🟢 Baseline Stable | Zero connection exhaustion |
Run this benchmark locally at any time:
npm run build && node scripts/benchmark-stampede.mjs- Zero Runtime Dependencies: Core engine and official local drivers have zero external dependencies.
- Multi-Tiered Caching (
TieredDock): Pair an ultra-fast in-memory L1 cache with a distributed/persistent L2 store with automatic promotion. - Cache Stampede Protection: Single-flight promise coalescing stops thundering herds—concurrent requests for the same missing key run the fetcher only once.
- Streaming Scans (
dock.scan()): Memory-efficientAsyncIterablestream scanning to traverse millions of keys without buffer exhaustion. - Atomic Operations: Compare-And-Swap (
cas) semantics and ACID transactions across supported backends. - Tag-Based Invalidation: Group keys with tags and purge entire collections in a single call (
dock.invalidateTag()). - Tree-Shakeable Adapters: Import only the storage drivers your application needs.
- Reusable Compliance Test Suite: Scaffold new adapters in 15 minutes with
kvdock/testing. - Cross-Runtime: Runs anywhere: Node.js (>=18), Bun, Deno, Cloudflare Workers, Edge Runtimes, and Web Browsers.
| Feature | kvdock |
unstorage |
keyv |
|---|---|---|---|
| Stampede Protection (Single-Flight) | 🟢 Built-in (dock.getOrSet) |
❌ Manual | ❌ No |
Native Multi-Tier Storage (TieredDock) |
🟢 Built-in (L1 RAM + L2 DB) | 🟡 Driver overlay | ❌ No |
| Zero Runtime Dependencies Core | 🟢 Yes | 🟢 Yes | ❌ No |
Streaming Scans (dock.scan()) |
🟢 AsyncIterable | 🟡 Batched Array | 🟡 Iterator |
| Next.js 15 App Router Incremental Cache | 🟢 Official Handler | 🟡 Community | ❌ No |
| Cross-Process Invalidation Bus | 🟢 Built-in (KVDockBus) |
❌ No | ❌ No |
📖 Read the complete deep dive: Architectural Comparison: KVDock vs. Unstorage vs. Keyv
npm install kvdock| Adapter | Maturity | Capabilities | Target Runtime | Import |
|---|---|---|---|---|
| Memory | 🟢 Stable | TTL, Batch, Scan, LRU, CAS | All JS Runtimes | kvdock/adapters/memory |
| Memory (Byte-Sized) | 🟢 Stable | TTL, Batch, Scan, CAS, Byte limit | All JS Runtimes | kvdock/adapters/memory-sized |
| Memory (Window TinyLFU) | 🟢 Stable | Frequency sketch, Window cache, Admission policy | All JS Runtimes | kvdock/adapters/memory-wtinylfu |
SQLite (node:sqlite) |
🟢 Stable | TTL, Batch, Scan, CAS, ACID Tx | Node.js (>=22), Bun | kvdock/adapters/sqlite |
| Bun SQLite | 🟢 Stable | TTL, Batch, Scan, CAS, High-throughput | Bun | kvdock/adapters/bun-sqlite |
| Filesystem | 🟢 Stable | TTL, Scan, Atomic writes | Node.js, Bun | kvdock/adapters/fs |
| LevelDB | 🟢 Stable | TTL, Batch, Scan, LSM-tree | Node.js, Bun, Embedded | kvdock/adapters/leveldb |
| LocalStorage | 🟢 Stable | Envelope TTL, Quota resilience | Browsers, Web Workers | kvdock/adapters/localstorage |
| IndexedDB | 🟢 Stable | TTL, Batch, Scan, CAS | Browsers, PWAs | kvdock/adapters/indexeddb |
| Adapter | Maturity | Peer Dependency | Capabilities | Target Runtime | Import |
|---|---|---|---|---|---|
| Redis | 🟡 Production | ioredis (optional) |
TTL, Batch, Scan, Streaming | Node, Bun, Deno | kvdock/adapters/redis |
| PostgreSQL | 🟡 Production | pg (optional) |
TTL, Atomic CAS, Upsert, Relational | Node, Bun | kvdock/adapters/postgres |
| MongoDB | 🟡 Production | mongodb (optional) |
Native TTL index, Atomic CAS, Document | Node, Bun | kvdock/adapters/mongodb |
| Valkey Cluster | 🟡 Production | Zero-dep client | Slot routing, MOVED redirection, Batch | Node, Bun, Deno | kvdock/adapters/valkey-cluster |
| Upstash (REST) | 🟡 Production | REST / fetch | Serverless pipelining, Edge-ready | Serverless, Edge | kvdock/adapters/upstash |
| Cloudflare D1 | 🟡 Production | D1 binding | SQL persistence, TTL, CAS | Cloudflare Workers | kvdock/adapters/d1 |
| Cloudflare KV | 🟡 Production | KV binding | Edge caching, Cursor pagination | Cloudflare Workers | kvdock/adapters/cloudflare-kv |
| Deno KV | 🟡 Production | Deno native | Transactional tuples, Versionstamps | Deno | kvdock/adapters/deno-kv |
| LibSQL / Turso | 🟡 Production | @libsql/client (optional) |
Distributed SQLite, Edge replication | Edge, Node, Bun | kvdock/adapters/libsql |
| S3 / MinIO / R2 | 🟡 Production | AWS SDK S3 | Blob storage, Binary, Multipart | All cloud runtimes | kvdock/adapters/s3 |
| AWS DynamoDB | 🟡 Production | AWS SDK DynamoDB | Document client, TTL, Batch | AWS Lambda, Cloud | kvdock/adapters/dynamodb |
| Memcached | 🟡 Production | Binary protocol | High-speed memcached wire protocol | Node, Bun | kvdock/adapters/memcached |
| React Native | 🧪 Experimental | @react-native-async-storage |
Mobile local persistence | React Native, Expo | kvdock/adapters/async-storage |
| Framework | Integration | Scope | Import |
|---|---|---|---|
| Next.js 15 | KVDockNextCacheHandler |
App Router Incremental Cache & ISR | kvdock/integrations/nextjs |
| Elysia.js (Bun) | kvdockElysiaPlugin |
Zero-overhead Route, Context & Eden Treaty Caching | kvdock (Guide) |
| Hono | kvdockHonoCache, kvdockHonoSession |
HTTP 304 ETag Caching & Edge Sessions | kvdock/integrations/hono |
| Nuxt 3 / Nitro | defineKVDockDriver |
Unstorage backend driver | kvdock/integrations/nuxt |
| SvelteKit | createSvelteKitSession |
Hook session & cache middleware | kvdock/integrations/sveltekit |
| Fastify | kvdockFastifyPlugin |
Fastify route caching & session store | kvdock/integrations/fastify |
| Express | KVDockExpressStore |
Express-session store conforming API | kvdock/integrations/express |
See the complete Adapters Guide & Architectural Comparison for latency, persistence, and concurrency ratings.
import { KVDock } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
const dock = new KVDock({
adapter: new MemoryAdapter({ maxSize: 10_000 }),
prefix: "app",
defaultTTL: 60_000 // 1 minute
});
await dock.set("session:user_1", { role: "admin" });
const user = await dock.get("session:user_1");
// Cache-aside with automatic single-flight stampede protection
const data = await dock.getOrSet("expensive:analytics", async () => {
return await computeAnalytics();
}, { ttl: 300_000 });Pair in-memory L1 speed with persistent or distributed L2 caching:
import { TieredDock } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
import { RedisAdapter } from "kvdock/adapters/redis";
import Redis from "ioredis";
const redis = new Redis(process.env.REDIS_URL);
const dock = new TieredDock({
l1: new MemoryAdapter({ maxSize: 5_000 }), // Ultra-fast L1 (< 0.05ms)
l2: new RedisAdapter({ client: redis }), // Shared L2 (Redis)
l1TTL: 10_000, // Micro-cache hot keys for 10s
defaultTTL: 3600_000 // 1 hour in Redis
});
// Checks L1 first; on miss, fetches L2 and automatically backfills L1!
const product = await dock.get("product:123");Read the Multi-Tiered Caching Guide.
import { KVDock } from "kvdock";
import { SQLiteAdapter } from "kvdock/adapters/sqlite";
const dock = new KVDock({
adapter: new SQLiteAdapter({ path: "./cache.sqlite" })
});
await dock.set("token", "secret", { ttl: 120_000 });import { KVDock } from "kvdock";
import { CloudflareKVAdapter } from "kvdock/adapters/cloudflare-kv";
export default {
async fetch(req: Request, env: { MY_KV: KVNamespace }) {
const dock = new KVDock({
adapter: new CloudflareKVAdapter({ kv: env.MY_KV, prefix: "app" })
});
const result = await dock.getOrSet("feed", () => generateFeed());
return Response.json(result);
}
};Save up to 80% RAM/disk space on large payloads and secure sensitive data at rest using zero-dependency codecs:
import { KVDock, createCompressionCodec, createEncryptionCodec } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
// Automatically compress JSON payloads exceeding 1KB using Brotli
const compressedDock = new KVDock({
adapter: new MemoryAdapter(),
serializer: createCompressionCodec({ algorithm: "brotli", thresholdBytes: 1024 }),
});
// Authenticated AES-256-GCM encryption with tamper detection
const encryptedDock = new KVDock({
adapter: new MemoryAdapter(),
serializer: createEncryptionCodec({ secretKey: process.env.CACHE_SECRET_KEY! }),
});Protect APIs and workers against traffic spikes using rate limiters built directly on KVDock storage:
import { KVDock, TokenBucketLimiter, SlidingWindowLimiter } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
const dock = new KVDock({ adapter: new MemoryAdapter() });
// Token Bucket: smooth refills with burst capacity
const tokenBucket = new TokenBucketLimiter({
dock,
capacity: 10, // Burst allowance of 10 requests
refillRate: 2, // Replenish 2 tokens per second
});
const { allowed, remaining, resetMs } = await tokenBucket.consume("ip:192.168.1.1");
// Sliding Window Counter: O(1) memory with smooth boundary estimation
const slidingWindow = new SlidingWindowLimiter({
dock,
limit: 100, // 100 requests
windowMs: 60_000, // Per minute
});
const result = await slidingWindow.consume("api_key:secret_key");Shield your docks and storage adapters against transient network timeouts, rate limit spikes (429), and connection resets using exponential backoff with full jitter:
import { KVDock, withRetry } from "kvdock";
import { RedisAdapter } from "kvdock/adapters/redis";
// Wrap any adapter with automatic retry, exponential backoff, and full jitter
const resilientRedis = withRetry(new RedisAdapter({ host: "localhost", port: 6379 }), {
maxRetries: 3,
initialDelayMs: 100,
maxDelayMs: 3000,
jitter: "full", // "full" | "equal" | "decorrelated" | "none"
});
const dock = new KVDock({ adapter: resilientRedis });
await dock.set("session:123", { userId: 42 });Eliminate cache miss latency for hot keys using RFC 5861 Stale-While-Revalidate and the optimal ACM XFetch probabilistic recomputation algorithm:
import { KVDock } from "kvdock";
import { RedisAdapter } from "kvdock/adapters/redis";
const dock = new KVDock({ adapter: new RedisAdapter() });
// Stale-While-Revalidate: serve stale data immediately (0ms wait)
// while an asynchronous single-flight promise refreshes the cache in the background
const catalog = await dock.getOrSet("products:feed", async () => {
return await fetchHeavyCatalog();
}, {
ttl: 60_000, // Fresh for 60 seconds
staleWhileRevalidate: 300_000, // Serve stale for up to 5 minutes during background refresh
xfetch: true, // Optimal probabilistic early refresh before expiration (ACM 2015)
});Protect applications from cascading outages when distributed cache backends (Redis, DynamoDB, Upstash, Postgres) suffer network partitions or latency spikes:
import { KVDock, withCircuitBreaker, withFailover } from "kvdock";
import { RedisAdapter } from "kvdock/adapters/redis";
import { MemoryAdapter } from "kvdock/adapters/memory";
// Circuit Breaker: fail fast, detect slow calls, and divert to in-memory fallback
const breakerRedis = withCircuitBreaker(new RedisAdapter(), {
failureThreshold: 3, // Trips after 3 consecutive failures (or error rate > 50%)
resetTimeoutMs: 10_000, // Probes recovery after 10s
fallbackAdapter: new MemoryAdapter(), // Transparent fallback during outage
degradeGracefully: true, // Return safe defaults instead of crashing if no fallback
});
// Active-Passive Multi-Adapter Failover with write replication
const failoverStore = withFailover([new RedisAdapter(), new MemoryAdapter()], {
replicateWrites: true, // Keep standby cache pre-warmed
healthCheckIntervalMs: 5000,// Auto-failback when primary recovers
});Mount distinct storage backends to key prefix hierarchies through a unified, transparent client interface:
import { RouterDock, KVDock } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
import { RedisAdapter } from "kvdock/adapters/redis";
import { S3Adapter } from "kvdock/adapters/s3";
const router = new RouterDock({
default: new KVDock({ adapter: new RedisAdapter() }),
})
.mount("session:", new KVDock({ adapter: new MemoryAdapter({ maxSize: 10_000 }) }))
.mount("media:", new KVDock({ adapter: new S3Adapter({ bucket: "assets" }) }));
// Transparently routes "session:user_1" to in-memory, "media:avatar.png" to S3, and everything else to Redis
await router.set("session:user_1", { name: "Alice" });
await router.set("media:avatar.png", imageBuffer);
await router.set("config:site_title", "My App");Synchronize in-memory L1 caches across horizontal microservice pods or worker clusters in real time:
import { TieredDock, RedisPubSubBus, BroadcastChannelBus } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
import { RedisAdapter } from "kvdock/adapters/redis";
import Redis from "ioredis";
const redis = new Redis(process.env.REDIS_URL);
const bus = new RedisPubSubBus({ pubClient: redis, subClient: redis.duplicate() });
const dock = new TieredDock({
l1: new MemoryAdapter({ maxSize: 50_000 }),
l2: new RedisAdapter({ client: redis }),
bus, // Automatically broadcasts evictions across all cluster pods
});
// Modifying or deleting a key evicts L1 on every listening instance across your cluster
await dock.delete("product:price:1001");Achieve near-optimal hit ratios that outperform pure LRU by combining a fast admission window with a 4-bit Count-Min frequency sketch:
import { KVDock } from "kvdock";
import { WindowTinyLFUAdapter } from "kvdock/adapters/memory-wtinylfu";
const dock = new KVDock({
adapter: new WindowTinyLFUAdapter({
maxSize: 100_000,
}),
});Ensure runtime data integrity and eliminate corrupted cache entries using Standard Schema (Zod, Valibot, ArkType):
import { KVDock, withSchema } from "kvdock";
import { z } from "zod";
const UserSchema = z.object({
id: z.number(),
name: z.string(),
email: z.string().email(),
});
const userStore = withSchema(dock, UserSchema, { onInvalid: "delete" });
// Fully typed and validated get/set
await userStore.set("user:42", { id: 42, name: "Alice", email: "alice@example.com" });
const user = await userStore.get("user:42"); // Typed as { id: number; name: string; email: string } | nullDump point-in-time state from any backend and restore it anywhere (seeding staging, local test fixtures, backups):
import { createSnapshot, restoreSnapshot, exportSnapshotToJSON } from "kvdock/tooling/snapshot";
// 1. Snapshot all keys matching a prefix from Redis
const snapshot = await createSnapshot(redisDock, { prefix: "config:" });
// 2. Export portable JSON backup
const jsonBackup = exportSnapshotToJSON(snapshot, true);
// 3. Restore into in-memory or SQLite store with custom prefix
await restoreSnapshot(memoryDock, snapshot, { keyPrefix: "staging:" });Safely increment and decrement numeric counters (page hits, inventory, sequence numbers, rate limits) without lost updates using optimistic Compare-And-Swap (CAS) concurrency control:
import { KVDock } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
const dock = new KVDock({ adapter: new MemoryAdapter() });
// Atomically increment (initializes missing keys to delta)
const views = await dock.increment("page:views:home"); // 1
await dock.increment("page:views:home", 5); // 6
// Decrement counter
const stock = await dock.decrement("inventory:item_9", 2);
// Passes through TTL and fires reactive mutation watchers
await dock.increment("rate:ip:127.0.0.1", 1, { ttl: 60_000 });Prevent duplicate LLM API bills (OpenAI, Anthropic, Gemini, DeepSeek) with deterministic prompt hashing, single-flight stampede protection, and model-level purging:
import { KVDock, createLLMCachePlugin } from "kvdock";
import { MemoryAdapter } from "kvdock/adapters/memory";
const dock = new KVDock({ adapter: new MemoryAdapter() });
const llmCache = createLLMCachePlugin({
dock,
defaultTTL: 86_400_000, // 24 hours
autoTagModel: true, // Tags entries as "model:gpt-4o"
});
// 100 simultaneous users asking the same prompt -> API called exactly ONCE
const response = await llmCache.wrap(
{ model: "gpt-4o", prompt: "Explain quantum computing", temperature: 0.2 },
async () => openai.chat.completions.create(...)
);
// Invalidate all cached responses for a specific model
await llmCache.invalidateModel("gpt-4o");Benchmark performance: see BENCHMARKS.md for empirical payload compression and throughput evaluations.
Check out the standalone, runnable applications in the examples/ directory:
| Starter Example | Key Capabilities Demonstrated | Run Command |
|---|---|---|
examples/tiered-cache |
L1 (Memory) + L2 (SQLite) tiered caching, single-flight stampede coalescing (100 -> 1 query), automatic promotions | npx tsx examples/tiered-cache/index.ts |
examples/circuit-breaker-failover |
Circuit breaker failover, active-passive multi-adapter failover, write replication, and SWR zero-latency caching | npx tsx examples/circuit-breaker-failover/index.ts |
examples/distributed-lock |
Distributed Mutex with monotonic fencing tokens, lease renewal, and Distributed Semaphore concurrency pooling | npx tsx examples/distributed-lock/index.ts |
examples/hono-caching |
Edge HTTP route caching, automatic ETag generation, conditional 304 Not Modified revalidation, encrypted sessions |
npx tsx examples/hono-caching/index.ts |
examples/nextjs-isr |
Next.js 14/15 App Router IncrementalCache handler (cacheHandler), tag-based invalidation (revalidateTag) |
npx tsx examples/nextjs-isr/index.ts |
examples/llm-response-caching |
AI / LLM response caching (OpenAI/Anthropic/Gemini), prompt hashing, stampede coalescing, cost reduction | npx tsx examples/llm-response-caching/index.ts |
kvdock includes an interactive CLI binary for inspecting keys, diagnosing adapters, and running micro-benchmarks:
# Diagnostic inspection
npx kvdock doctor
# Benchmark adapter throughput
npx kvdock bench --adapter=memory --ops=10000
npx kvdock bench --adapter=sqlite --ops=5000
# Inspect and manage keys
npx kvdock set user:1 '{"name":"Alice"}' --adapter=sqlite
npx kvdock get user:1 --adapter=sqlite --json
npx kvdock keys "user:*" --adapter=sqliteWe actively encourage and welcome external contributors! We designed our repository so anyone can build and submit an adapter or feature in under 15 minutes without merge conflicts:
- 1-Command Scaffolding:
npm run create:adapter <name>automatically creates your adapter directory, tests, benchmarks, and exports. - Exported Compliance Test Suite: Import
defineAdapterTestSuitefromkvdock/testingto instantly run 25+ conformance checks against your driver. - Open Issues & Milestones: Check out our Open Issues labeled
good first issueandhelp wanted.
Read the Contributor Guide: Building a Custom Adapter in 15 Minutes.
-
Rust:
zisam-glitch/kvdock-rs— Thread-safe, zero-dependency caching layer with monotonicInstantTTL. -
Go:
zisam-glitch/kvdock-go— Generic key-value cache engine with atomic telemetry. -
Swift:
zisam-glitch/kvdock-swift— Actor-isolated concurrent cache withContinuousClock. -
Kotlin:
zisam-glitch/kvdock-kt— Thread-safe$O(1)$ LRU key-value cache for JVM.
zisam shaikh 🚇 🚧 💻 📖 |
Vamsi 💻 |
Bryan | Full Stack Developer 💻 |
Kemal Codes 💻 📖 |
mafujahmedridoy22-commits 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!
Designed and maintained with care by zisam shaikh (@zisam-glitch).
Follow along on GitHub for low-latency systems engineering deep dives, lock-free data structures, and zero-dependency runtime tooling.