@monlite/kv

@monlite/kv

A Redis-like key-value cache for @monlite/core, backed by SQLite. Synchronous get/set/incr with TTLs — part of the local AI-agent harness (cache + queue + cron, replacing Redis locally).

npm install @monlite/core @monlite/kv

Quick start

import { createDb } from "@monlite/core";
import { kv } from "@monlite/kv";

const db = createDb("app.db");
const cache = kv(db);

cache.set("session:42", { user: "ali" }, { ttl: 60_000 }); // expires in 60s
cache.get("session:42");   // { user: "ali" }  — synchronous, no await
cache.incr("hits");        // 1
cache.incr("hits", 5);     // 6
cache.ttl("session:42");   // ~60000 (ms remaining)

The cache is synchronous (local SQLite — no network, no await), durable (survives restarts), and stored in your app's database. Use :memory: if you want a purely ephemeral cache.

API

Method	Description
get(key)	Value, or undefined (also if expired).
set(key, value, { ttl? })	Store any JSON-serializable value; ttl in ms (optional).
setNX(key, value, { ttl? })	Atomic set-if-absent (Redis SET NX); returns true if acquired. The lock/nonce primitive.
has(key) / delete(key)	Existence check / removal.
incr(key, by?) / decr(key, by?)	Atomic numeric increment/decrement; returns the new value.
mget(keys)	Array of values (undefined per missing/expired key).
keys(prefix?)	Live keys in the namespace, optionally filtered by prefix.
expire(key, ttl)	Set or refresh the TTL (ms); returns false if the key is absent.
ttl(key)	Remaining ms; -1 = no expiry, -2 = key absent (Redis convention).
size() / flush()	Count / clear all keys in the namespace.
stop()	Clear the sweep timer (if sweepIntervalMs was set).

Options

kv(db, {
  namespace: "sessions",   // isolate multiple caches in one db (default: "default")
  sweepIntervalMs: 60_000, // periodically purge expired keys (default: lazy-only)
});

Expired keys are removed lazily on read. Set sweepIntervalMs to also purge them on a timer. Call cache.stop() to clear the timer when shutting down.

License

MIT