bundis 0.1.0 → 0.2.0

package/src/storage/cache.ts

@@ -0,0 +1,373 @@
+/**
+ * HotCacheStorage — write-through in-memory hot cache over a StorageEngine.
+ *
+ * Policy (write-through + adaptive time-to-idle + LRU byte cap):
+ * - kvSet writes through to the inner engine, then caches the fresh value, so
+ *   a key is hot from the moment it is written.
+ * - kvGet serves live cache entries without touching SQLite; misses read
+ *   through and fill the cache.
+ * - An entry is evicted when idle longer than its effective TTI. The TTI grows
+ *   with accumulated hits — `min(maxFactor·base, base·(1 + log2(1 + hits)))` —
+ *   so frequently-read keys survive longer idle gaps. Hit counts halve on every
+ *   sweep so past popularity decays.
+ * - Total cached bytes are capped; the least-recently-used entries are evicted
+ *   first when the cap is exceeded. Values larger than 1/8 of the cap are never
+ *   cached (one huge value must not flush the whole working set).
+ *
+ * Coherence (single-writer, single-process):
+ * - Every mutation in the inner engine fires its onWrite hook; the server wires
+ *   that hook to {@link invalidate}, so all write paths (DEL, EXPIRE, INCR,
+ *   hash/set ops, sweeps, type overwrites) evict stale entries automatically.
+ * - Inside an explicit transaction (MULTI/EXEC) fills are suppressed: a rolled
+ *   back transaction must not leave uncommitted values in the cache.
+ *   Invalidations still apply immediately (evicting too much is always safe).
+ * - Cache entries carry expireAtMs and are checked lazily on every hit, so an
+ *   expired key never serves from cache.
+ */
+
+import type { RedisType, SetOptions, StorageEngine } from "./types";
+
+interface CacheEntry {
+  value: Uint8Array;
+  expireAtMs: number | null;
+  lastAccess: number;
+  hits: number;
+  bytes: number;
+}
+
+export interface HotCacheOptions {
+  /** Hard ceiling for cached bytes (keys + values + overhead). */
+  readonly maxBytes: number;
+  /** Base time-to-idle in ms. */
+  readonly baseIdleMs: number;
+  /** Cap on the adaptive TTI as a multiple of baseIdleMs (default 8). */
+  readonly maxIdleFactor?: number;
+  /** Min interval between idle sweeps in ms (default 5000). */
+  readonly sweepEveryMs?: number;
+}
+
+export interface CacheStats {
+  entries: number;
+  bytes: number;
+  maxBytes: number;
+  hits: number;
+  misses: number;
+  fills: number;
+  invalidations: number;
+  evictedIdle: number;
+  evictedLru: number;
+}
+
+const ENTRY_OVERHEAD = 96; // rough per-entry bookkeeping cost in bytes
+
+/** Sentinel: the key vanished between write/read and the expiry read-back. */
+const ABSENT = Symbol("absent");
+
+export class HotCacheStorage implements StorageEngine {
+  // Map iteration order doubles as the LRU order: a hit re-inserts its entry.
+  #cache = new Map<string, CacheEntry>();
+  #bytes = 0;
+  #inTxn = false;
+  #lastSweep = 0;
+
+  #hits = 0;
+  #misses = 0;
+  #fills = 0;
+  #invalidations = 0;
+  #evictedIdle = 0;
+  #evictedLru = 0;
+
+  readonly #maxBytes: number;
+  readonly #baseIdleMs: number;
+  readonly #maxIdleMs: number;
+  readonly #sweepEveryMs: number;
+  readonly #maxEntryBytes: number;
+
+  constructor(
+    private readonly inner: StorageEngine,
+    opts: HotCacheOptions,
+  ) {
+    this.#maxBytes = opts.maxBytes;
+    this.#baseIdleMs = opts.baseIdleMs;
+    this.#maxIdleMs = opts.baseIdleMs * (opts.maxIdleFactor ?? 8);
+    this.#sweepEveryMs = opts.sweepEveryMs ?? 5000;
+    this.#maxEntryBytes = Math.max(1, Math.floor(opts.maxBytes / 8));
+  }
+
+  /** Evict one key (no-op if absent). Wired to the inner engine's onWrite. */
+  invalidate = (key: Uint8Array): void => {
+    const k = mapKey(key);
+    const entry = this.#cache.get(k);
+    if (entry) {
+      this.#cache.delete(k);
+      this.#bytes -= entry.bytes;
+      this.#invalidations++;
+    }
+  };
+
+  stats(): CacheStats {
+    return {
+      entries: this.#cache.size,
+      bytes: this.#bytes,
+      maxBytes: this.#maxBytes,
+      hits: this.#hits,
+      misses: this.#misses,
+      fills: this.#fills,
+      invalidations: this.#invalidations,
+      evictedIdle: this.#evictedIdle,
+      evictedLru: this.#evictedLru,
+    };
+  }
+
+  // ── cached fast paths ────────────────────────────────────────────────────-
+
+  kvGet(key: Uint8Array, now: number): Uint8Array | null {
+    const entry = this.#liveEntry(key, now);
+    if (entry) {
+      this.#hits++;
+      return entry.value;
+    }
+    this.#misses++;
+    const value = this.inner.kvGet(key, now);
+    if (value !== null && !this.#inTxn) {
+      const exp = this.#expireOf(key, now);
+      if (exp !== ABSENT) this.#fill(key, value, exp, now);
+    }
+    return value;
+  }
+
+  kvSet(key: Uint8Array, value: Uint8Array, now: number, opts?: SetOptions): "set" | "noop" {
+    const result = this.inner.kvSet(key, value, now, opts);
+    // onWrite already invalidated any stale entry; cache the committed value.
+    // A "noop" (NX/XX guard) fires no onWrite, so the old entry stays valid.
+    if (result === "set" && !this.#inTxn) {
+      // If the write carried an already-past expiry, the read-back's lazy
+      // expiry deletes the row and reports ABSENT — caching then would create
+      // an immortal ghost entry that SQLite no longer backs.
+      const exp = this.#expireOf(key, now);
+      if (exp !== ABSENT) this.#fill(key, value, exp, now);
+    }
+    return result;
+  }
+
+  exists(key: Uint8Array, now: number): boolean {
+    if (this.#liveEntry(key, now)) {
+      this.#hits++;
+      return true;
+    }
+    this.#misses++;
+    return this.inner.exists(key, now);
+  }
+
+  typeOf(key: Uint8Array, now: number): RedisType | null {
+    if (this.#liveEntry(key, now)) {
+      this.#hits++;
+      return "string";
+    }
+    this.#misses++;
+    return this.inner.typeOf(key, now);
+  }
+
+  pttl(key: Uint8Array, now: number): number {
+    const entry = this.#liveEntry(key, now);
+    if (entry) {
+      this.#hits++;
+      return entry.expireAtMs === null ? -1 : Math.max(0, entry.expireAtMs - now);
+    }
+    this.#misses++;
+    return this.inner.pttl(key, now);
+  }
+
+  sweepExpired(now: number): number {
+    if (now - this.#lastSweep >= this.#sweepEveryMs) {
+      this.#lastSweep = now;
+      this.#idleSweep(now);
+    }
+    // Inner sweep fires onWrite per removed key → cache invalidation included.
+    return this.inner.sweepExpired(now);
+  }
+
+  withTransaction<T>(fn: () => T): T {
+    // Suppress fills while a MULTI/EXEC body runs: if the transaction rolls
+    // back, the cache must not retain values that were never committed.
+    const outer = this.#inTxn;
+    this.#inTxn = true;
+    try {
+      return this.inner.withTransaction(fn);
+    } finally {
+      this.#inTxn = outer;
+    }
+  }
+
+  close(): void {
+    this.#cache.clear();
+    this.#bytes = 0;
+    this.inner.close();
+  }
+
+  // ── pure delegations (onWrite keeps the cache coherent) ──────────────────-
+
+  del(keys: Uint8Array[], now: number): number {
+    // Eager eviction (not just onWrite): inner.del only fires onWrite for keys
+    // whose row exists, so this guarantees DEL always heals any divergence.
+    for (const k of keys) this.invalidate(k);
+    return this.inner.del(keys, now);
+  }
+  expireSet(key: Uint8Array, atMs: number, now: number): boolean {
+    return this.inner.expireSet(key, atMs, now);
+  }
+  persist(key: Uint8Array, now: number): boolean {
+    return this.inner.persist(key, now);
+  }
+  dbsize(now: number): number {
+    return this.inner.dbsize(now);
+  }
+  flushAll(): void {
+    this.invalidateAll();
+    this.inner.flushAll();
+  }
+  /** Drop every cache entry (FLUSHDB or any whole-keyspace event). */
+  invalidateAll(): void {
+    this.#invalidations += this.#cache.size;
+    this.#cache.clear();
+    this.#bytes = 0;
+  }
+  incrBy(key: Uint8Array, delta: bigint, now: number): bigint {
+    return this.inner.incrBy(key, delta, now);
+  }
+  incrByFloat(key: Uint8Array, delta: number, now: number): number {
+    return this.inner.incrByFloat(key, delta, now);
+  }
+  append(key: Uint8Array, value: Uint8Array, now: number): number {
+    return this.inner.append(key, value, now);
+  }
+  hSet(key: Uint8Array, pairs: ReadonlyArray<readonly [Uint8Array, Uint8Array]>, now: number): number {
+    return this.inner.hSet(key, pairs, now);
+  }
+  hGet(key: Uint8Array, field: Uint8Array, now: number): Uint8Array | null {
+    return this.inner.hGet(key, field, now);
+  }
+  hDel(key: Uint8Array, fields: Uint8Array[], now: number): number {
+    return this.inner.hDel(key, fields, now);
+  }
+  hGetAll(key: Uint8Array, now: number): Array<[Uint8Array, Uint8Array]> {
+    return this.inner.hGetAll(key, now);
+  }
+  hKeys(key: Uint8Array, now: number): Uint8Array[] {
+    return this.inner.hKeys(key, now);
+  }
+  hVals(key: Uint8Array, now: number): Uint8Array[] {
+    return this.inner.hVals(key, now);
+  }
+  hLen(key: Uint8Array, now: number): number {
+    return this.inner.hLen(key, now);
+  }
+  hExists(key: Uint8Array, field: Uint8Array, now: number): boolean {
+    return this.inner.hExists(key, field, now);
+  }
+  hIncrBy(key: Uint8Array, field: Uint8Array, delta: bigint, now: number): bigint {
+    return this.inner.hIncrBy(key, field, delta, now);
+  }
+  hIncrByFloat(key: Uint8Array, field: Uint8Array, delta: number, now: number): number {
+    return this.inner.hIncrByFloat(key, field, delta, now);
+  }
+  sAdd(key: Uint8Array, members: Uint8Array[], now: number): number {
+    return this.inner.sAdd(key, members, now);
+  }
+  sRem(key: Uint8Array, members: Uint8Array[], now: number): number {
+    return this.inner.sRem(key, members, now);
+  }
+  sIsMember(key: Uint8Array, member: Uint8Array, now: number): boolean {
+    return this.inner.sIsMember(key, member, now);
+  }
+  sMembers(key: Uint8Array, now: number): Uint8Array[] {
+    return this.inner.sMembers(key, now);
+  }
+  sCard(key: Uint8Array, now: number): number {
+    return this.inner.sCard(key, now);
+  }
+  sRandMember(key: Uint8Array, count: number | null, now: number): Uint8Array[] | Uint8Array | null {
+    return this.inner.sRandMember(key, count, now);
+  }
+  sPop(key: Uint8Array, count: number | null, now: number): Uint8Array[] | Uint8Array | null {
+    return this.inner.sPop(key, count, now);
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────-
+
+  /** Live cache entry for key, refreshed as most-recently-used; null if absent/expired. */
+  #liveEntry(key: Uint8Array, now: number): CacheEntry | null {
+    const k = mapKey(key);
+    const entry = this.#cache.get(k);
+    if (!entry) return null;
+    if (entry.expireAtMs !== null && entry.expireAtMs <= now) {
+      // Key TTL passed: drop from cache; the inner lazy path owns row deletion.
+      this.#cache.delete(k);
+      this.#bytes -= entry.bytes;
+      return null;
+    }
+    entry.lastAccess = now;
+    entry.hits++;
+    this.#cache.delete(k); // re-insert → most recently used
+    this.#cache.set(k, entry);
+    return entry;
+  }
+
+  #fill(key: Uint8Array, value: Uint8Array, expireAtMs: number | null, now: number): void {
+    const bytes = key.length + value.byteLength + ENTRY_OVERHEAD;
+    if (bytes > this.#maxEntryBytes) return;
+    const k = mapKey(key);
+    const prev = this.#cache.get(k);
+    if (prev) {
+      this.#bytes -= prev.bytes;
+      this.#cache.delete(k);
+    }
+    this.#cache.set(k, {
+      value,
+      expireAtMs,
+      lastAccess: now,
+      hits: prev ? prev.hits : 0, // overwrite keeps earned popularity
+      bytes,
+    });
+    this.#bytes += bytes;
+    this.#fills++;
+    while (this.#bytes > this.#maxBytes && this.#cache.size > 0) {
+      const oldest = this.#cache.keys().next().value as string;
+      const evicted = this.#cache.get(oldest)!;
+      this.#cache.delete(oldest);
+      this.#bytes -= evicted.bytes;
+      this.#evictedLru++;
+    }
+  }
+
+  /**
+   * Resulting expiry of a just-read/just-written string key: epoch ms, null
+   * for "no expiry", or ABSENT when the key no longer exists (-2) — callers
+   * must skip the fill in that case.
+   */
+  #expireOf(key: Uint8Array, now: number): number | null | typeof ABSENT {
+    const ttl = this.inner.pttl(key, now);
+    if (ttl === -2) return ABSENT;
+    return ttl === -1 ? null : now + ttl;
+  }
+
+  /** Evict idle entries; decay hit counts so popularity is not permanent. */
+  #idleSweep(now: number): void {
+    for (const [k, entry] of this.#cache) {
+      const grown = this.#baseIdleMs * (1 + Math.log2(1 + entry.hits));
+      const tti = Math.min(this.#maxIdleMs, grown);
+      if (now - entry.lastAccess > tti) {
+        this.#cache.delete(k);
+        this.#bytes -= entry.bytes;
+        this.#evictedIdle++;
+      } else {
+        entry.hits >>= 1;
+      }
+    }
+  }
+}
+
+/** Binary-safe Map key for raw key bytes. */
+function mapKey(key: Uint8Array): string {
+  return Buffer.from(key).toString("latin1");
+}

package/src/storage/sqlite.ts

@@ -17,25 +17,57 @@ import {
 } from "../engine/errors";
 import type { RedisType, SetOptions, StorageEngine } from "./types";
 
+const ENC = new TextEncoder();
+
+/** Max expired keys reclaimed per sweep call (bounds reaper-tick stalls). */
+const SWEEP_BATCH = 1000;
+
 export interface SqliteStorageOptions {
   /** Hook invoked with a key whenever it is mutated (drives WATCH versioning). */
   readonly onWrite?: (key: Uint8Array) => void;
+  /** Hook invoked after FLUSHDB/FLUSHALL (per-key hooks can't enumerate). */
+  readonly onFlushAll?: () => void;
+  /** SQLite page-cache size in KB (PRAGMA cache_size). Default: SQLite's own. */
+  readonly pageCacheKb?: number;
 }
 
 export class SqliteStorage implements StorageEngine {
   #db: Database;
   #onWrite: (key: Uint8Array) => void;
+  #onFlushAll: () => void;
 
   constructor(path = ":memory:", opts: SqliteStorageOptions = {}) {
-    this.#db = new Database(path, { create: true, strict: false });
-    this.#onWrite = opts.onWrite ?? (() => {});
-    this.#init();
+    try {
+      this.#db = new Database(path, { create: true, strict: false });
+      this.#onWrite = opts.onWrite ?? (() => {});
+      this.#onFlushAll = opts.onFlushAll ?? (() => {});
+      this.#init(opts.pageCacheKb);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/locked|busy/i.test(msg)) {
+        throw new Error(
+          `database "${path}" is already in use by another bundis process ` +
+            "(the single-writer contract forbids sharing one .db file)",
+        );
+      }
+      throw new Error(`cannot open database "${path}": ${msg}`);
+    }
   }
 
-  #init(): void {
+  #init(pageCacheKb?: number): void {
+    // Enforce the documented single-writer contract (§5.3): EXCLUSIVE locking
+    // holds the file lock for the process lifetime, so a second bundis on the
+    // same .db fails fast here instead of corrupting cache coherence later.
+    // (:memory: is unaffected; WAL+exclusive runs with a heap WAL-index.)
+    this.#db.exec("PRAGMA busy_timeout = 2000;");
+    this.#db.exec("PRAGMA locking_mode = EXCLUSIVE;");
     this.#db.exec("PRAGMA journal_mode = WAL;");
     this.#db.exec("PRAGMA synchronous = NORMAL;");
     this.#db.exec("PRAGMA foreign_keys = ON;");
+    if (pageCacheKb !== undefined && pageCacheKb > 0) {
+      // negative value = size in KB (positive would mean pages)
+      this.#db.exec(`PRAGMA cache_size = -${Math.floor(pageCacheKb)};`);
+    }
     this.#db.exec(`
       CREATE TABLE IF NOT EXISTS keys (
         key          BLOB PRIMARY KEY,
@@ -146,22 +178,43 @@ export class SqliteStorage implements StorageEngine {
     return true;
   }
 
+  /**
+   * One bounded sweep batch per call (the reaper ticks every ~100ms, so a
+   * burst of expirations is reclaimed incrementally instead of blocking every
+   * connection for one giant transaction — measured 380ms p99 before the cap).
+   */
   sweepExpired(now: number): number {
     return this.withTransaction(() => {
       const rows = this.#stmt(
-        "SELECT key FROM keys WHERE expire_at_ms IS NOT NULL AND expire_at_ms <= ?",
+        "DELETE FROM keys WHERE key IN (" +
+          "SELECT key FROM keys WHERE expire_at_ms IS NOT NULL AND expire_at_ms <= ? " +
+          `LIMIT ${SWEEP_BATCH}) RETURNING key`,
       ).all(now) as Array<{ key: Uint8Array }>;
-      for (const r of rows) this.#deleteKey(r.key);
+      for (const r of rows) this.#onWrite(r.key);
       return rows.length;
     });
   }
 
   dbsize(now: number): number {
-    this.sweepExpired(now);
-    const row = this.#stmt("SELECT COUNT(*) AS n FROM keys").get() as { n: number };
+    // Count live keys without sweeping: INFO/DBSIZE polling must never pay
+    // (or trigger) a reclamation pass.
+    const row = this.#stmt(
+      "SELECT COUNT(*) AS n FROM keys WHERE expire_at_ms IS NULL OR expire_at_ms > ?",
+    ).get(now) as { n: number };
     return row.n;
   }
 
+  flushAll(): void {
+    this.withTransaction(() => {
+      // Children first: kv/hash_fields/set_members reference keys.
+      this.#stmt("DELETE FROM kv").run();
+      this.#stmt("DELETE FROM hash_fields").run();
+      this.#stmt("DELETE FROM set_members").run();
+      this.#stmt("DELETE FROM keys").run();
+    });
+    this.#onFlushAll();
+  }
+
   // ── string / kv ─────────────────────────────────────────────────────────--
 
   kvGet(key: Uint8Array, now: number): Uint8Array | null {
@@ -215,7 +268,7 @@ export class SqliteStorage implements StorageEngine {
         n = parseIntStrict(cur);
       }
       const next = n + delta;
-      const buf = new TextEncoder().encode(next.toString());
+      const buf = ENC.encode(next.toString());
       this.#stmt(
         "INSERT INTO keys(key, type, expire_at_ms) VALUES (?, 'string', NULL) " +
           "ON CONFLICT(key) DO UPDATE SET type='string'",
@@ -237,7 +290,7 @@ export class SqliteStorage implements StorageEngine {
       if (!Number.isFinite(next)) {
         throw new RespError("ERR", "increment would produce NaN or Infinity");
       }
-      const buf = new TextEncoder().encode(formatFloat(next));
+      const buf = ENC.encode(formatFloat(next));
       this.#stmt(
         "INSERT INTO keys(key, type, expire_at_ms) VALUES (?, 'string', NULL) " +
           "ON CONFLICT(key) DO UPDATE SET type='string'",
@@ -361,7 +414,7 @@ export class SqliteStorage implements StorageEngine {
       const cur = this.hGet(key, field, now);
       const n = cur === null ? 0n : parseIntStrict(cur);
       const next = n + delta;
-      this.hSet(key, [[field, new TextEncoder().encode(next.toString())]], now);
+      this.hSet(key, [[field, ENC.encode(next.toString())]], now);
       return next;
     });
   }
@@ -371,16 +424,16 @@ export class SqliteStorage implements StorageEngine {
       const cur = this.hGet(key, field, now);
       const n = cur === null ? 0 : parseFloatStrict(cur);
       const next = n + delta;
-      this.hSet(key, [[field, new TextEncoder().encode(formatFloat(next))]], now);
+      this.hSet(key, [[field, ENC.encode(formatFloat(next))]], now);
       return next;
     });
   }
 
   #dropIfEmptyHash(key: Uint8Array): void {
-    const row = this.#stmt(
-      "SELECT COUNT(*) AS n FROM hash_fields WHERE key = ?",
-    ).get(key) as { n: number };
-    if (row.n === 0) this.#stmt("DELETE FROM keys WHERE key = ?").run(key);
+    // Existence probe, not COUNT(*): a 100k-field hash must not pay a full
+    // index scan on every HDEL just to learn it is non-empty.
+    const any = this.#stmt("SELECT 1 FROM hash_fields WHERE key = ? LIMIT 1").get(key);
+    if (any === null) this.#stmt("DELETE FROM keys WHERE key = ?").run(key);
   }
 
   // ── set ────────────────────────────────────────────────────────────────---
@@ -449,15 +502,25 @@ export class SqliteStorage implements StorageEngine {
     count: number | null,
     now: number,
   ): Uint8Array[] | Uint8Array | null {
-    const members = this.sMembers(key, now);
+    if (!this.#expectType(key, "set", now)) {
+      return count === null ? null : [];
+    }
+    // Random selection stays in SQL: materializing all members into JS just to
+    // pick a few measured ~5ms per op on a 100k set.
     if (count === null) {
-      if (members.length === 0) return null;
-      return members[Math.floor(Math.random() * members.length)]!;
+      const row = this.#randomMember(key);
+      return row ?? null;
     }
     if (count >= 0) {
-      return shuffle(members).slice(0, count);
+      return (
+        this.#stmt(
+          "SELECT member FROM set_members WHERE key = ? ORDER BY random() LIMIT ?",
+        ).all(key, count) as Array<{ member: Uint8Array }>
+      ).map((r) => r.member);
     }
-    // Negative count: allow repeats, |count| elements.
+    // Negative count: |count| picks WITH repeats — needs independent draws, so
+    // the full-load path is genuinely required here.
+    const members = this.sMembers(key, now);
     const out: Uint8Array[] = [];
     if (members.length === 0) return out;
     for (let i = 0; i < -count; i++) {
@@ -472,24 +535,53 @@ export class SqliteStorage implements StorageEngine {
     now: number,
   ): Uint8Array[] | Uint8Array | null {
     return this.withTransaction(() => {
-      const members = this.sMembers(key, now);
+      if (!this.#expectType(key, "set", now)) {
+        return count === null ? null : [];
+      }
       if (count === null) {
-        if (members.length === 0) return null;
-        const pick = members[Math.floor(Math.random() * members.length)]!;
-        this.sRem(key, [pick], now);
-        return pick;
+        // Single pop: uniform COUNT+OFFSET pick is ~3x cheaper than
+        // ORDER BY random() (no per-row random + top-k sort).
+        const member = this.#randomMember(key);
+        if (member === undefined) return null;
+        this.#stmt("DELETE FROM set_members WHERE key = ? AND member = ?").run(key, member);
+        this.#dropIfEmptySet(key);
+        this.#onWrite(key);
+        return member;
+      }
+      const k = Math.max(0, count);
+      const rows =
+        k === 0
+          ? []
+          : (this.#stmt(
+              "DELETE FROM set_members WHERE key = ? AND member IN (" +
+                "SELECT member FROM set_members WHERE key = ? ORDER BY random() LIMIT ?" +
+                ") RETURNING member",
+            ).all(key, key, k) as Array<{ member: Uint8Array }>);
+      if (rows.length > 0) {
+        this.#dropIfEmptySet(key);
+        this.#onWrite(key);
       }
-      const picks = shuffle(members).slice(0, Math.max(0, count));
-      if (picks.length > 0) this.sRem(key, picks, now);
-      return picks;
+      return rows.map((r) => r.member);
     });
   }
 
-  #dropIfEmptySet(key: Uint8Array): void {
+  /** Uniform random member of a set key, or undefined when empty. */
+  #randomMember(key: Uint8Array): Uint8Array | undefined {
+    const n = (
+      this.#stmt("SELECT COUNT(*) AS n FROM set_members WHERE key = ?").get(key) as {
+        n: number;
+      }
+    ).n;
+    if (n === 0) return undefined;
     const row = this.#stmt(
-      "SELECT COUNT(*) AS n FROM set_members WHERE key = ?",
-    ).get(key) as { n: number };
-    if (row.n === 0) this.#stmt("DELETE FROM keys WHERE key = ?").run(key);
+      "SELECT member FROM set_members WHERE key = ? LIMIT 1 OFFSET ?",
+    ).get(key, Math.floor(Math.random() * n)) as { member: Uint8Array } | null;
+    return row?.member;
+  }
+
+  #dropIfEmptySet(key: Uint8Array): void {
+    const any = this.#stmt("SELECT 1 FROM set_members WHERE key = ? LIMIT 1").get(key);
+    if (any === null) this.#stmt("DELETE FROM keys WHERE key = ?").run(key);
   }
 
   // ── atomicity / lifecycle ───────────────────────────────────────────────--
@@ -556,12 +648,3 @@ function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
   out.set(b, a.length);
   return out;
 }
-
-function shuffle<T>(arr: T[]): T[] {
-  const a = arr.slice();
-  for (let i = a.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [a[i], a[j]] = [a[j]!, a[i]!];
-  }
-  return a;
-}

package/src/storage/types.ts

@@ -38,6 +38,8 @@ export interface StorageEngine {
   sweepExpired(now: number): number;
   /** Total live key count (after lazy considerations are out of scope here). */
   dbsize(now: number): number;
+  /** Remove every key (FLUSHDB/FLUSHALL). */
+  flushAll(): void;
 
   // ── string / kv ─────────────────────────────────────────────────────────--
   kvGet(key: Uint8Array, now: number): Uint8Array | null;