quickv

A fast, SQLite-backed key-value cache for Bun. No Redis required.

Features

• Zero dependencies - Uses Bun's built-in SQLite
• Persistent storage - Data survives restarts
• TTL support - Automatic expiration with lazy + periodic cleanup
• Atomic operations - incr/decr are transaction-safe
• Batch operations - mget/mset/mdel for bulk operations
• Type-safe - Full TypeScript support

Installation

bun add quickv

Quick Start

import { Cache } from "quickv";

const cache = new Cache();

// Basic operations
cache.set("user:1", { name: "Alice", email: "[email protected]" });
const user = cache.get<User>("user:1");

// With TTL (in seconds)
cache.set("session:abc", sessionData, 3600); // 1 hour

API Reference

Constructor

const cache = new Cache({
  path: "./cache.db", // Default: ":memory:" (in-memory)
  cleanupInterval: 60_000, // Default: 60000ms (1 min). Set to 0 to disable.
});

Basic Operations

| Method | Description | | ----------------------- | ------------------------------------------------------------- | | set(key, value, ttl?) | Store a value with optional TTL in seconds | | get<T>(key) | Retrieve a value. Returns undefined if not found or expired | | del(key) | Delete a key | | has(key) | Check if a key exists and is not expired |

TTL Management

| Method | Description | | ------------------ | ------------------------------------------------------------------------------------- | | ttl(key) | Get remaining TTL in seconds. Returns undefined if missing, null if no expiry | | expire(key, ttl) | Set/update expiry. Pass null to remove expiry. Returns false if key doesn't exist |

Counters

cache.incr("views"); // 1
cache.incr("views"); // 2
cache.incr("views", 5); // 7
cache.decr("views"); // 6

Both preserve existing TTL on the key.

Batch Operations

// Set multiple values
cache.mset({ a: 1, b: 2, c: 3 }, ttl?);
cache.mset(new Map([["a", 1], ["b", 2]]));
cache.mset([["a", 1], ["b", 2]]);

// Get multiple values
const values = cache.mget<number>(["a", "b", "c"]); // Map<string, number>

// Delete multiple keys
cache.mdel(["a", "b"]);

Utility Methods

| Method | Description | | ---------------- | ------------------------------------------------------ | | keys(pattern?) | List keys. Supports * and ? wildcards | | size() | Count of non-expired entries | | clear() | Delete all entries | | cleanup() | Manually remove expired entries. Returns count removed | | close() | Close database and stop cleanup timer |

Pattern Matching

cache.set("user:1", "alice");
cache.set("user:2", "bob");
cache.set("post:1", "hello");

cache.keys("user:*"); // ["user:1", "user:2"]
cache.keys("*:1"); // ["user:1", "post:1"]

Persistence

// In-memory (default) - fastest, lost on restart
const cache = new Cache();

// File-based - persists across restarts
const cache = new Cache({ path: "./cache.db" });

SQLite WAL mode is enabled automatically for better concurrent performance.

Performance

Benchmarked on Apple M4 Pro:

~600,000 writes/sec
~1,650,000 reads/sec

When to Use

Use quickv when:

• Single Bun instance
• Need persistent caching without external dependencies
• Want Redis-like API with zero setup

Use Redis when:

• Multiple instances need shared cache
• Need pub/sub or streams
• Distributed systems

License

MIT