variablesoftware
@variablesoftware/mock-kv 🎛️🏷️✨
Mock Cloudflare KV Namespace for unit and integration testing
🎛️🏷️✨ @variablesoftware/mock-kv provides an in-memory simulation of Cloudflare Workers KV. It is designed for testing key-value storage logic with expiration, metadata, and batch operations — without any external dependencies.
🔧 Installation
yarn add --dev @variablesoftware/mock-kvThis package assumes a test environment with Vitest and support for ESM.
🚀 Usage
import { mockKVNamespace } from '@variablesoftware/mock-kv';
const kv = mockKVNamespace();
await kv.put('token-abc', 'value', { expirationTtl: 60 });
const result = await kv.get('token-abc');
console.log(result); // 'value'🎯 Goals
- ⚙ Match Cloudflare KV behavior closely for testing
- 🧪 Support test-safe mocking of put/get/delete/list flows
- 📦 No external storage dependencies; uses only in-memory JS objects
- 📎 Logging via
@variablesoftware/logfaceis required for test and runtime logging, but does not rely on any external services
✨ Features
Includes matching behavior for edge cases like:
- Key expiration mid-test
list()with prefix collisions and limitsMetadata preservation across put/get calls
In-memory mock of Cloudflare
KVNamespace- Supports
put,get,delete,list, and metadata options - TTL-aware: honors
expirationTtlandexpiration - Returns values as
string,ArrayBuffer, ornulljust like real KV - Simulates listing behavior including prefix + limit
- Supports metadata in
put()andgetWithMetadata() - Compatible with Vitest and any Cloudflare Worker test setup
- Logs via
@variablesoftware/logface - Optional
.dump()method for inspecting KV state during tests
🧪 Test Coverage
Tested using vitest run, with coverage for:
put()with TTL and metadataget()andgetWithMetadata()matching real behaviordelete()andlist()consistency- Full
.dump()snapshots for inspection and debugging
Run tests:
yarn test🚧 Status
This package is under active development and not yet stable.
Once stable, it will be published as:
"@variablesoftware/mock-kv": "^0.5.0"📄 License
MIT © Rob Friedman / Variable Software
Built with ❤️ by @variablesoftware
Thank you for downloading and using this project. Pull requests are warmly welcomed!
🌐 Inclusive & Accessible Design
- Naming, logging, error messages, and tests avoid cultural or ableist bias
- Avoids assumptions about input/output formats or encodings
- Faithfully reflects user data — no coercion or silent transformations
- Designed for clarity, predictability, and parity with underlying platforms (e.g., Cloudflare APIs)
- Works well in diverse, multilingual, and inclusive developer environments