@variablesoftware/mock-kv

@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-kv

This 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/logface is 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 limits

• Metadata preservation across put/get calls

• In-memory mock of Cloudflare KVNamespace

• Supports put, get, delete, list, and metadata options

• TTL-aware: honors expirationTtl and expiration

• Returns values as string, ArrayBuffer, or null just like real KV

• Simulates listing behavior including prefix + limit

• Supports metadata in put() and getWithMetadata()

• 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 metadata
• get() and getWithMetadata() matching real behavior
• delete() and list() 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