@iskra-bun/kv-kit 0.1.0 → 0.3.0

package/src/adapters/memory.ts

@@ -1,32 +1,133 @@
 import type { KVAdapter } from '../types';
+import { checkTtl } from '../ttl';
+
+/** setTimeout's limit: a longer delay (a TTL over ~24.8 days) fires at once. */
+const MAX_TIMEOUT_MS = 2 ** 31 - 1;
+
+/** An expiring set: each member's expiry (ms since the epoch, Infinity for none). */
+interface ExpiringSet {
+    members: Map<string, number>;
+    expiresAt: number;
+    /** Size at which expired members are next dropped. */
+    pruneAt: number;
+}
 
 export class MemoryAdapter implements KVAdapter {
     id = 'memory';
-    private store = new Map<string, any>();
+    private store = new Map<string, unknown>();
+    private sets = new Map<string, ExpiringSet>();
+    private timers = new Map<string, ReturnType<typeof setTimeout>>();
 
     connect() {
         // No-op
     }
+
     disconnect() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
         this.store.clear();
+        this.sets.clear();
     }
 
-    async get(key: string) {
-        return this.store.get(key);
+    // Values are copied in and out, as Redis does: a stored object returned by
+    // reference let one request's mutation show up in every other one.
+    async get<T = unknown>(key: string): Promise<T | undefined> {
+        return structuredClone(this.store.get(key)) as T | undefined;
+    }
+
+    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        const seconds = checkTtl(ttl);
+        const copy = structuredClone(value);
+        // Note: storing `null`/`undefined` is undefined behavior across adapters.
+        // This in-memory adapter stores the value verbatim (so `get` returns it
+        // as-is), whereas the RedisAdapter normalizes both to "absent" because
+        // they have no faithful JSON round-trip. Callers should not depend on
+        // either form being preserved.
+        //
+        // Clear any existing expiry timer for this key before setting a new one
+        this.clearTimer(key);
+        this.sets.delete(key);
+        this.store.set(key, copy);
+
+        if (seconds !== undefined) this.expireIn(key, seconds * 1000);
+    }
+
+    /** Arms the expiry timer, in steps when the delay exceeds setTimeout's limit. */
+    private expireIn(key: string, ms: number) {
+        const step = Math.min(ms, MAX_TIMEOUT_MS);
+        const timer = setTimeout(() => {
+            if (ms > step) {
+                this.expireIn(key, ms - step);
+                return;
+            }
+            this.store.delete(key);
+            this.sets.delete(key);
+            this.timers.delete(key);
+        }, step);
+
+        // Avoid keeping the process alive just for expiry timers
+        timer.unref?.();
+
+        this.timers.set(key, timer);
     }
 
-    async set(key: string, value: any, ttl?: number) {
-        this.store.set(key, value);
-        if (ttl) {
-            setTimeout(() => this.store.delete(key), ttl * 1000);
+    private clearTimer(key: string) {
+        const timer = this.timers.get(key);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.timers.delete(key);
         }
     }
 
-    async del(key: string) {
+    async del(key: string): Promise<void> {
+        this.clearTimer(key);
         this.store.delete(key);
+        this.sets.delete(key);
+    }
+
+    async has(key: string): Promise<boolean> {
+        return this.store.has(key) || this.sets.has(key);
+    }
+
+    async clear(prefix = ''): Promise<void> {
+        for (const key of [...this.store.keys(), ...this.sets.keys()]) {
+            if (key.startsWith(prefix)) await this.del(key);
+        }
+    }
+
+    async sadd(key: string, member: string, ttl?: number): Promise<void> {
+        const seconds = checkTtl(ttl);
+        const now = Date.now();
+        const expiresAt = seconds === undefined ? Infinity : now + seconds * 1000;
+        let set = this.sets.get(key);
+        if (!set) {
+            this.store.delete(key);
+            set = { members: new Map(), expiresAt: 0, pruneAt: 64 };
+            this.sets.set(key, set);
+        }
+        // A member keeps its latest expiry: dropped earlier, an entry written
+        // with a longer TTL would survive an invalidation of its tag.
+        set.members.set(member, Math.max(set.members.get(member) ?? 0, expiresAt));
+        // Expired members go each time the set doubles: O(1) per add on average.
+        if (set.members.size >= set.pruneAt) {
+            for (const [name, at] of set.members) if (at <= now) set.members.delete(name);
+            set.pruneAt = Math.max(64, set.members.size * 2);
+        }
+        if (expiresAt > set.expiresAt) {
+            set.expiresAt = expiresAt;
+            this.clearTimer(key);
+            if (expiresAt !== Infinity) this.expireIn(key, expiresAt - now);
+        }
     }
 
-    async has(key: string) {
-        return this.store.has(key);
+    async sdrain(key: string): Promise<string[]> {
+        const set = this.sets.get(key);
+        if (!set) return [];
+        this.sets.delete(key);
+        this.clearTimer(key);
+        const now = Date.now();
+        return [...set.members].filter(([, at]) => at > now).map(([name]) => name);
     }
 }

package/src/adapters/redis.ts

@@ -1,47 +1,297 @@
 import type { KVAdapter } from '../types';
+import { checkTtl } from '../ttl';
 import Redis from 'ioredis';
+import type { RedisOptions } from 'ioredis';
+
+/**
+ * Single consistent codec shared by every write/read path.
+ *
+ * `undefined` is guarded explicitly: there is no JSON representation for it,
+ * so it is stored as the JSON `null` literal and decoded back to `undefined`
+ * on read. Every other value is `JSON.stringify`'d on write and `JSON.parse`'d
+ * on read, so the string "123" round-trips as the string "123" (not the number
+ * 123) and "{}" round-trips as the string "{}" (not an empty object).
+ */
+function encode<T>(value: T): string {
+    if (value === undefined) return 'null';
+    return JSON.stringify(value);
+}
+
+function decode<T>(raw: string): T | undefined {
+    try {
+        const parsed = JSON.parse(raw) as T | null;
+        return parsed === null ? undefined : (parsed as T);
+    } catch {
+        // Tolerate values written outside the adapter that are not valid JSON.
+        return raw as unknown as T;
+    }
+}
+
+/**
+ * Connection settings: a `redis://` / `rediss://` URL, ioredis options, or
+ * ioredis options with a `url` (the form used in app.config and the docs).
+ */
+export type RedisAdapterOptions = string | (RedisOptions & { url?: string });
+
+export interface RedisAdapterHooks {
+    /**
+     * Receives the client's `error` events (a dropped connection, each failed
+     * reconnect). Without it they are ignored; ioredis printed them to the
+     * console, outside the app's logger.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Lets `clear()` with no key prefix at all run FLUSHDB, which empties the
+     * whole Redis database, other apps' keys included.
+     */
+    flushDb?: boolean;
+}
+
+/** `EX` for whole seconds; `PX` for fractional TTLs, which Redis `EX` rejects. */
+function ttlArgs(ttl: number): ['EX', number] | ['PX', number] {
+    return Number.isInteger(ttl) ? ['EX', ttl] : ['PX', Math.max(1, Math.round(ttl * 1000))];
+}
+
+/** `prefix` as a literal in a SCAN MATCH pattern. */
+const escapeGlob = (prefix: string): string => prefix.replace(/[*?[\]\\]/g, '\\$&');
+
+/** Keys deleted per DEL while clearing. */
+const CLEAR_BATCH = 1000;
+
+/**
+ * An expiring set is a sorted set scored by each member's expiry (Redis time,
+ * in ms; FOREVER for none). Adding a member drops the expired ones and keeps
+ * the key alive until its last member expires, in one atomic step.
+ * KEYS[1]: the set; ARGV[1]: the member; ARGV[2]: its TTL in ms, '' for none.
+ */
+const SADD_SCRIPT = `
+if redis.replicate_commands then redis.replicate_commands() end
+local forever = 9007199254740991
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+local expires = forever
+if ARGV[2] ~= '' then expires = now + tonumber(ARGV[2]) end
+local current = tonumber(redis.call('ZSCORE', KEYS[1], ARGV[1]) or '0')
+if expires > current then redis.call('ZADD', KEYS[1], expires, ARGV[1]) end
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', '(' .. now)
+local last = redis.call('ZRANGE', KEYS[1], -1, -1, 'WITHSCORES')
+if tonumber(last[2]) >= forever then
+    redis.call('PERSIST', KEYS[1])
+else
+    redis.call('PEXPIREAT', KEYS[1], last[2])
+end
+`;
+
+/**
+ * Returns the unexpired members of an expiring set (see SADD_SCRIPT) and
+ * deletes it, in one atomic step: members past their expiry are left out, as
+ * the memory adapter does. KEYS[1]: the set.
+ */
+const SDRAIN_SCRIPT = `
+if redis.replicate_commands then redis.replicate_commands() end
+local t = redis.call('TIME')
+local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+local members = redis.call('ZRANGEBYSCORE', KEYS[1], '(' .. now, '+inf')
+redis.call('DEL', KEYS[1])
+return members
+`;
+
+/**
+ * ioredis errors carry the command they answer with its arguments: AUTH's
+ * password on a refused login, which the app then logged. Only the command
+ * name is kept.
+ */
+function withoutCommandArgs<E>(error: E): E {
+    const command = (error as { command?: { name?: unknown; args?: unknown } } | null)?.command;
+    if (command && typeof command === 'object' && 'args' in command) {
+        (error as { command: unknown }).command = { name: command.name };
+    }
+    return error;
+}
 
 export class RedisAdapter implements KVAdapter {
     id = 'redis';
     private client: Redis | null = null;
-    private options: any;
+    private readonly options: RedisAdapterOptions;
+    private readonly hooks: RedisAdapterHooks;
 
-    constructor(options: any) {
+    constructor(options: RedisAdapterOptions, hooks: RedisAdapterHooks = {}) {
         this.options = options;
+        this.hooks = hooks;
     }
 
-    connect() {
-        this.client = new Redis(this.options);
+    /**
+     * Connects and waits for Redis to answer: an unreachable server or a wrong
+     * password fails here (and so the app's start) instead of on the first
+     * command. Once connected, a dropped connection is retried by ioredis.
+     */
+    async connect() {
+        // ioredis only parses a URL passed as its own argument: an object with
+        // a `url` key was ignored and it silently connected to localhost:6379.
+        let client: Redis;
+        if (typeof this.options === 'string') {
+            client = new Redis(this.options, { lazyConnect: true });
+        } else if (this.options.url) {
+            const { url, ...rest } = this.options;
+            client = new Redis(url, { ...rest, lazyConnect: true });
+        } else {
+            client = new Redis({ ...this.options, lazyConnect: true });
+        }
+        client.on('error', (error: Error) => this.hooks.onError?.(withoutCommandArgs(error)));
+        try {
+            await client.connect();
+        } catch (error) {
+            client.disconnect();
+            // The message, not the URL: it may carry the password.
+            throw new Error(`Could not connect to Redis: ${error instanceof Error ? error.message : String(error)}`, {
+                cause: withoutCommandArgs(error),
+            });
+        }
+        this.client = client;
     }
 
-    disconnect() {
-        this.client?.disconnect();
-    }
+    /** Longest wait for QUIT before the connection is closed anyway. */
+    protected quitTimeoutMs = 2000;
 
-    async get(key: string) {
-        const val = await this.client?.get(key);
-        try {
-            return val ? JSON.parse(val) : null;
-        } catch {
-            return val;
+    /**
+     * Closes the connection. When connected, QUIT lets pending replies arrive
+     * (in-flight writes are not dropped), for at most `quitTimeoutMs`. When the
+     * connection is down, ioredis would queue QUIT behind the offline queue and
+     * resolve only after its reconnect attempts run out (about 10 s by default,
+     * never with `maxRetriesPerRequest: null`), eating the app's shutdown
+     * timeout: the client is closed at once instead.
+     */
+    async disconnect() {
+        const client = this.client;
+        this.client = null;
+        if (!client) return;
+        if (typeof client.quit !== 'function' || client.status !== 'ready') {
+            client.disconnect();
+            return;
         }
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const timedOut = new Promise<'timeout'>((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), this.quitTimeoutMs);
+        });
+        const outcome = await Promise.race([
+            client.quit().then(
+                () => 'quit' as const,
+                () => 'error' as const,
+            ),
+            timedOut,
+        ]);
+        clearTimeout(timer);
+        if (outcome !== 'quit') client.disconnect();
     }
 
-    async set(key: string, value: any, ttl?: number) {
-        const val = typeof value === 'object' ? JSON.stringify(value) : value;
-        if (ttl) {
-            await this.client?.set(key, val, 'EX', ttl);
+    /** The ioredis client once connected (null before connect() and after disconnect()). */
+    get nativeClient(): Redis | null {
+        return this.client;
+    }
+
+    /** The live client; operations before connect() fail instead of silently doing nothing. */
+    private get redis(): Redis {
+        if (!this.client) throw new Error('RedisAdapter is not connected; call connect() first');
+        return this.client;
+    }
+
+    async get<T = unknown>(key: string): Promise<T | undefined> {
+        const val = await this.redis.get(key);
+        if (val === null || val === undefined) return undefined;
+        return decode<T>(val);
+    }
+
+    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        const val = encode(value);
+        const seconds = checkTtl(ttl);
+        if (seconds !== undefined) {
+            await this.redis.set(key, val, ...(ttlArgs(seconds) as ['EX', number]));
         } else {
-            await this.client?.set(key, val);
+            await this.redis.set(key, val);
         }
     }
 
     async del(key: string) {
-        await this.client?.del(key);
+        await this.redis.del(key);
     }
 
     async has(key: string) {
-        const exists = await this.client?.exists(key);
+        const exists = await this.redis.exists(key);
         return exists === 1;
     }
+
+    // Native batch operations. A single MGET / pipelined MSET / variadic DEL
+    // replaces the manager's per-key fan-out (avoids the N+1 round-trips).
+
+    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {
+        if (keys.length === 0) return [];
+        const raws = (await this.redis.mget(...keys)) ?? [];
+        return keys.map((_, i) => {
+            const raw = raws[i];
+            return raw === null || raw === undefined ? undefined : decode<T>(raw);
+        });
+    }
+
+    async mset<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void> {
+        const seconds = checkTtl(ttl);
+        if (entries.length === 0) return;
+        const pipeline = this.redis.pipeline();
+
+        for (const [key, value] of entries) {
+            const val = encode(value);
+            if (seconds !== undefined) {
+                pipeline.set(key, val, ...(ttlArgs(seconds) as ['EX', number]));
+            } else {
+                pipeline.set(key, val);
+            }
+        }
+
+        // exec() resolves even when individual commands fail; surface them.
+        const results = await pipeline.exec();
+        const failed = results?.find(([err]) => err);
+        if (failed) throw failed[0];
+    }
+
+    async mdel(keys: string[]): Promise<void> {
+        if (keys.length === 0) return;
+        await this.redis.del(...keys);
+    }
+
+    /**
+     * Deletes the keys under `prefix` (after ioredis' own `keyPrefix`, if set)
+     * with SCAN and DEL. With no prefix at all this would be every key in the
+     * database, which only `flushDb: true` allows (as a FLUSHDB).
+     */
+    async clear(prefix = ''): Promise<void> {
+        const redis = this.redis;
+        const keyPrefix = redis.options.keyPrefix ?? '';
+        if (!keyPrefix && !prefix) {
+            if (!this.hooks.flushDb) {
+                throw new Error(
+                    'RedisAdapter.clear() without a key prefix would empty the whole Redis database: ' +
+                        'give the KVManager a namespace, or pass flushDb: true if the database belongs to this app alone',
+                );
+            }
+            await redis.flushdb();
+            return;
+        }
+        const match = `${escapeGlob(keyPrefix + prefix)}*`;
+        let cursor = '0';
+        do {
+            const [next, keys] = await redis.scan(cursor, 'MATCH', match, 'COUNT', CLEAR_BATCH);
+            cursor = next;
+            // SCAN returns whole keys, and ioredis prepends keyPrefix to DEL's.
+            if (keys.length > 0) await redis.del(...keys.map((key) => key.slice(keyPrefix.length)));
+        } while (cursor !== '0');
+    }
+
+    async sadd(key: string, member: string, ttl?: number): Promise<void> {
+        const seconds = checkTtl(ttl);
+        const ms = seconds === undefined ? '' : String(Math.max(1, Math.ceil(seconds * 1000)));
+        await this.redis.eval(SADD_SCRIPT, 1, key, member, ms);
+    }
+
+    async sdrain(key: string): Promise<string[]> {
+        return (await this.redis.eval(SDRAIN_SCRIPT, 1, key)) as string[];
+    }
 }

package/src/manager.ts

@@ -1,29 +1,73 @@
-import type { App, Driver } from '@iskra-bun/core';
+import { isProductionEnv, type App, type Driver } from '@iskra-bun/core';
+import type { Redis } from 'ioredis';
 import type { KVAdapter } from './types';
 import { MemoryAdapter } from './adapters/memory';
 import { RedisAdapter } from './adapters/redis';
 
+export interface KVManagerOptions {
+    /**
+     * Optional namespace prepended to every key as `"<namespace>:<key>"`.
+     * Defaults to `""` (no prefix) to preserve existing behavior.
+     */
+    namespace?: string;
+    /**
+     * Lets `clear()` without a `namespace` empty the whole Redis database
+     * (FLUSHDB). Only for a database no other app or service writes to.
+     */
+    flushDb?: boolean;
+}
+
 export class KVManager implements Driver, KVAdapter {
     name = 'KVManager';
     id = 'manager';
     private app: App | null = null;
     private adapter: KVAdapter;
+    private readonly prefix: string;
+    private readonly flushDb: boolean;
 
-    constructor() {
+    constructor(options: KVManagerOptions = {}) {
+        // The store is chosen by the App's config (`kv.driver`), not here: an
+        // `adapter: 'redis'` copied from an old README was ignored, and the app
+        // silently ran on per-process memory.
+        const misplaced = ['adapter', 'driver', 'connection'].filter((key) => key in options);
+        if (misplaced.length > 0) {
+            throw new Error(
+                `KVManager does not take ${misplaced.map((k) => `"${k}"`).join(', ')}: choose the store in the App config, ` +
+                    "e.g. new App({ name, kv: { driver: 'redis', connection: process.env.REDIS_URL } })",
+            );
+        }
         // Default to memory until configured
         this.adapter = new MemoryAdapter();
+        this.prefix = options.namespace ? `${options.namespace}:` : '';
+        this.flushDb = options.flushDb ?? false;
     }
 
     init(app: App) {
         this.app = app;
+        // Like db-kit's 'db': services look the store up as app.context.get('kv').
+        app.context.set('kv', this);
         const config = app.config.kv;
 
         if (config?.driver === 'redis') {
             app.logger.info('Initializing KV with Redis');
-            this.adapter = new RedisAdapter(config.connection);
-        } else {
+            this.adapter = new RedisAdapter(config.connection ?? {}, {
+                onError: (err) => app.logger.warn({ err }, 'KV Redis connection error'),
+                flushDb: this.flushDb,
+            });
+        } else if (!config?.driver || config.driver === 'memory') {
+            if (!config?.driver && isProductionEnv()) {
+                app.logger.warn(
+                    'KV has no driver configured: using the in-memory store, which each process keeps on its own ' +
+                        "and loses on restart. Set kv: { driver: 'redis', connection } in the App config, or " +
+                        "kv: { driver: 'memory' } to keep it.",
+                );
+            }
             app.logger.info('Initializing KV with Memory');
             this.adapter = new MemoryAdapter();
+        } else {
+            // Unknown drivers (e.g. 'libsql') used to fall back to memory
+            // silently, losing every value on restart.
+            throw new Error(`Unsupported KV driver "${config.driver}" (supported: "memory", "redis")`);
         }
     }
 
@@ -45,9 +89,109 @@ export class KVManager implements Driver, KVAdapter {
         await this.disconnect();
     }
 
-    // Proxy methods
-    get(key: string) { return this.adapter.get(key); }
-    set(key: string, value: any, ttl?: number) { return this.adapter.set(key, value, ttl); }
-    del(key: string) { return this.adapter.del(key); }
-    has(key: string) { return this.adapter.has(key); }
+    /**
+     * The underlying ioredis client with the "redis" driver, once started: for
+     * commands the KV API does not cover (sets, sorted sets, pipelines). It
+     * bypasses `namespace` and the JSON codec. `undefined` with the memory
+     * driver or before start().
+     */
+    get client(): Redis | undefined {
+        return this.adapter instanceof RedisAdapter ? (this.adapter.nativeClient ?? undefined) : undefined;
+    }
+
+    private prefixed(key: string): string {
+        return `${this.prefix}${key}`;
+    }
+
+    // Proxy methods (namespace-aware)
+    get<T = unknown>(key: string): Promise<T | undefined> {
+        return this.adapter.get<T>(this.prefixed(key));
+    }
+
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
+        return this.adapter.set<T>(this.prefixed(key), value, ttl);
+    }
+
+    del(key: string): Promise<void> {
+        return this.adapter.del(this.prefixed(key));
+    }
+
+    has(key: string): Promise<boolean> {
+        return this.adapter.has(this.prefixed(key));
+    }
+
+    // Batch operations. When the underlying adapter exposes a native batch
+    // method, the manager delegates to it (a single round-trip) after applying
+    // the namespace prefix; otherwise it falls back to a per-key loop. This
+    // keeps the optional adapter methods out of the hot path for adapters that
+    // do not implement them while avoiding the N+1 fan-out for those that do.
+
+    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {
+        const prefixed = keys.map((k) => this.prefixed(k));
+
+        if (this.adapter.mget) {
+            return this.adapter.mget<T>(prefixed);
+        }
+
+        return Promise.all(prefixed.map((k) => this.adapter.get<T>(k)));
+    }
+
+    async mset<T = unknown>(entries: Array<[string, T]> | Record<string, T>, ttl?: number): Promise<void> {
+        const pairs: Array<[string, T]> = Array.isArray(entries)
+            ? entries
+            : (Object.entries(entries) as Array<[string, T]>);
+
+        const prefixed: Array<[string, T]> = pairs.map(([k, v]) => [this.prefixed(k), v] as [string, T]);
+
+        if (this.adapter.mset) {
+            await this.adapter.mset<T>(prefixed, ttl);
+            return;
+        }
+
+        await Promise.all(prefixed.map(([k, v]) => this.adapter.set<T>(k, v, ttl)));
+    }
+
+    async mdel(keys: string[]): Promise<void> {
+        const prefixed = keys.map((k) => this.prefixed(k));
+
+        if (this.adapter.mdel) {
+            await this.adapter.mdel(prefixed);
+            return;
+        }
+
+        await Promise.all(prefixed.map((k) => this.adapter.del(k)));
+    }
+
+    /**
+     * Deletes every key under `prefix` in this manager's namespace (the whole
+     * namespace without one). With the redis driver and no namespace, only
+     * `flushDb: true` lets it empty the database.
+     */
+    async clear(prefix = ''): Promise<void> {
+        if (!this.adapter.clear) throw unsupported(this.adapter, 'clear');
+        await this.adapter.clear(this.prefixed(prefix));
+    }
+
+    /** See {@link KVAdapter.sadd}: the member is kept as is, only `key` is namespaced. */
+    async sadd(key: string, member: string, ttl?: number): Promise<void> {
+        if (!this.adapter.sadd) throw unsupported(this.adapter, 'sadd');
+        await this.adapter.sadd(this.prefixed(key), member, ttl);
+    }
+
+    async sdrain(key: string): Promise<string[]> {
+        if (!this.adapter.sdrain) throw unsupported(this.adapter, 'sdrain');
+        return this.adapter.sdrain(this.prefixed(key));
+    }
+}
+
+/** Both built-in adapters have the optional methods; an injected one may not. */
+function unsupported(adapter: KVAdapter, method: string): Error {
+    return new Error(`The "${adapter.id}" KV adapter does not support ${method}()`);
+}
+
+// `app.context.get('kv')` is the KVManager registered on the app.
+declare module '@iskra-bun/core' {
+    interface AppContextRegistry {
+        kv: KVManager;
+    }
 }

package/src/ttl.ts

@@ -0,0 +1,12 @@
+/**
+ * A TTL in seconds: `undefined`, `null` or `0` mean "no expiry". Anything else
+ * must be a positive finite number: a negative TTL used to delete the key at
+ * once with the memory adapter and fail with Redis.
+ */
+export function checkTtl(ttl: number | null | undefined): number | undefined {
+    if (ttl === undefined || ttl === null || ttl === 0) return undefined;
+    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || ttl < 0) {
+        throw new RangeError(`Invalid TTL ${String(ttl)}: expected a positive number of seconds`);
+    }
+    return ttl;
+}