Radiant KV Store

Radiant provides a lightweight, async key-value store facade RadiantKV that proxies to various drivers based on configuration. This allows you to write the same key-value logic regardless of the underlying storage engine.

Supported Drivers

Radiant KV supports three built-in drivers:

• sqlite (Default): Uses bun:sqlite to persist KV data to disk.
• memory: Fast, in-memory store. Ephemeral and clears on restart.
• redis: Connects to a Redis instance for distributed KV storage.

Usage

import { RadiantKV } from "@codesordinatestudio/radiant";

// Initialize with the default sqlite driver
const kv = new RadiantKV({ driver: "sqlite", sqlite: { path: "./data/kv.sqlite" } });

// Set a key with a TTL (Time To Live in milliseconds)
await kv.set("session:123", { userId: 42, role: "admin" }, 3600 * 1000);

// Get a key
const session = await kv.get<{ userId: number }>("session:123");

// Check if a key exists
const exists = await kv.has("session:123");

// Delete a key
await kv.delete("session:123");

Batch Operations

The KV store provides optimized methods for batch operations:

// Set multiple keys
await kv.setMany([
  { key: "user:1", value: { name: "Alice" } },
  { key: "user:2", value: { name: "Bob" }, ttl: 60000 }
]);

// Get multiple keys
const users = await kv.getMany<{ name: string }>(["user:1", "user:2"]);
console.log(users.get("user:1")); // { name: "Alice" }

// Delete multiple keys
await kv.deleteMany(["user:1", "user:2"]);

Advanced Queries

// Get all keys starting with a specific prefix
const allSessionKeys = await kv.keys("session:");

// Count total keys
const totalItems = await kv.count();

// Clear the entire KV store
await kv.clear();

TTL and Cleanup

When using memory or sqlite drivers, expired keys are periodically cleaned up using an interval (default 60_000 ms). You can customize this or trigger a manual cleanup:

const kv = new RadiantKV({
  driver: "sqlite",
  cleanupInterval: 120_000 // Clean up every 2 minutes
});

// Manually trigger a cleanup
const deletedCount = await kv.cleanup();

Note: When using the redis driver, TTL is handled natively by Redis, and the periodic cleanup interval is automatically disabled.