Skip to content
zisam-glitchPublic

About

Zero-dependency caching engine with built-in cache stampede protection (single-flight) and multi-tier L1/L2 storage for Node.js, Bun & Next.js

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

2 watching

Forks

Repository files navigation

kvdock

CI OpenSSF Scorecard npm version License: MIT Bundle Size Interactive Playground Community Hub Follow @zisam-glitch

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!


⚡ Real-World Benchmark: Single-Flight Stampede Coalescing

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

Highlights

  • 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-efficient AsyncIterable stream 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.

🥊 Architectural Comparison: KVDock vs. Alternatives

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


Installation

npm install kvdock

Adapters & Integrations Matrix

Core & Local Storage Drivers (Zero External Dependencies)

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

Distributed & Cloud Drivers (Optional Peer Dependencies)

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

Full-Stack Framework Integrations

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.


Quick Start

1. In-Memory Cache (LRU + TTL)

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 });

2. Multi-Tier Caching (TieredDock)

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.

3. SQLite Embedded Persistence

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 });

4. Cloudflare Workers KV

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);
  }
};

5. Transparent Compression & Encryption Codecs

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! }),
});

6. Production Rate Limiting (Token Bucket & Sliding Window)

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");

7. Resilient Exponential Backoff Retry with Jitter

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 });

8. Zero-Downtime Cache Coalescing: SWR & XFetch Stampede Prevention

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)
});

9. High-Availability Circuit Breaker & Multi-Adapter Failover

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
});

10. RouterDock: Hierarchical Prefix Mounts

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");

11. Multi-Node Cluster Invalidation: KVDockBus

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");

12. Window TinyLFU Cache: High-Hit-Ratio Admission Policy

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,
  }),
});

13. Type-Safe Schema Validation: withSchema

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 } | null

14. Portable Storage Snapshots: createSnapshot & restoreSnapshot

Dump 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:" });

15. Atomic Counters: Concurrency-Safe increment & decrement

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 });

16. AI & LLM Response Caching (createLLMCachePlugin)

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.


Runnable Examples & Framework Starters

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

CLI Tool

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=sqlite

Contributing & Developer Flywheel

We 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 defineAdapterTestSuite from kvdock/testing to instantly run 25+ conformance checks against your driver.
  • Open Issues & Milestones: Check out our Open Issues labeled good first issue and help wanted.

Read the Contributor Guide: Building a Custom Adapter in 15 Minutes.


Multi-Language Implementations


Contributors

zisam shaikh
zisam shaikh

🚇 🚧 💻 📖
Vamsi
Vamsi

💻 ⚠️
Bryan | Full Stack Developer
Bryan | Full Stack Developer

💻 ⚠️ 📖
Kemal Codes
Kemal Codes

💻 📖
mafujahmedridoy22-commits
mafujahmedridoy22-commits

💻 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!


Maintainer & Architecture

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.

Follow @zisam-glitch on GitHub


License

MIT © zisam shaikh

About

Zero-dependency caching engine with built-in cache stampede protection (single-flight) and multi-tier L1/L2 storage for Node.js, Bun & Next.js

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages