@iskra-bun/kv-kit 0.2.0 → 0.3.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/adapters/memory.ts","../src/adapters/redis.ts","../src/manager.ts"],"sourcesContent":["import type { KVAdapter } from '../types';\n\nexport class MemoryAdapter implements KVAdapter {\n    id = 'memory';\n    private store = new Map<string, unknown>();\n    private timers = new Map<string, ReturnType<typeof setTimeout>>();\n\n    connect() {\n        // No-op\n    }\n\n    disconnect() {\n        for (const timer of this.timers.values()) {\n            clearTimeout(timer);\n        }\n        this.timers.clear();\n        this.store.clear();\n    }\n\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        return this.store.get(key) as T | undefined;\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        // Note: storing `null`/`undefined` is undefined behavior across adapters.\n        // This in-memory adapter stores the value verbatim (so `get` returns it\n        // as-is), whereas the RedisAdapter normalizes both to \"absent\" because\n        // they have no faithful JSON round-trip. Callers should not depend on\n        // either form being preserved.\n        //\n        // Clear any existing expiry timer for this key before setting a new one\n        const existing = this.timers.get(key);\n        if (existing !== undefined) {\n            clearTimeout(existing);\n            this.timers.delete(key);\n        }\n\n        this.store.set(key, value);\n\n        if (ttl) {\n            const timer = setTimeout(() => {\n                this.store.delete(key);\n                this.timers.delete(key);\n            }, ttl * 1000);\n\n            // Avoid keeping the process alive just for expiry timers\n            timer.unref?.();\n\n            this.timers.set(key, timer);\n        }\n    }\n\n    async del(key: string): Promise<void> {\n        const timer = this.timers.get(key);\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            this.timers.delete(key);\n        }\n        this.store.delete(key);\n    }\n\n    async has(key: string): Promise<boolean> {\n        return this.store.has(key);\n    }\n}\n","import type { KVAdapter } from '../types';\nimport Redis from 'ioredis';\nimport type { RedisOptions } from 'ioredis';\n\n/**\n * Single consistent codec shared by every write/read path.\n *\n * `undefined` is guarded explicitly: there is no JSON representation for it,\n * so it is stored as the JSON `null` literal and decoded back to `undefined`\n * on read. Every other value is `JSON.stringify`'d on write and `JSON.parse`'d\n * on read, so the string \"123\" round-trips as the string \"123\" (not the number\n * 123) and \"{}\" round-trips as the string \"{}\" (not an empty object).\n */\nfunction encode<T>(value: T): string {\n    if (value === undefined) return 'null';\n    return JSON.stringify(value);\n}\n\nfunction decode<T>(raw: string): T | undefined {\n    try {\n        const parsed = JSON.parse(raw) as T | null;\n        return parsed === null ? undefined : (parsed as T);\n    } catch {\n        // Tolerate values written outside the adapter that are not valid JSON.\n        return raw as unknown as T;\n    }\n}\n\nexport class RedisAdapter implements KVAdapter {\n    id = 'redis';\n    private client: Redis | null = null;\n    private readonly options: RedisOptions | string;\n\n    constructor(options: RedisOptions | string) {\n        this.options = options;\n    }\n\n    connect() {\n        this.client = new Redis(this.options as RedisOptions);\n    }\n\n    disconnect() {\n        this.client?.disconnect();\n    }\n\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        const val = await this.client?.get(key);\n        if (val === null || val === undefined) return undefined;\n        return decode<T>(val);\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        const val = encode(value);\n        if (ttl) {\n            await this.client?.set(key, val, 'EX', ttl);\n        } else {\n            await this.client?.set(key, val);\n        }\n    }\n\n    async del(key: string) {\n        await this.client?.del(key);\n    }\n\n    async has(key: string) {\n        const exists = await this.client?.exists(key);\n        return exists === 1;\n    }\n\n    // Native batch operations. A single MGET / pipelined MSET / variadic DEL\n    // replaces the manager's per-key fan-out (avoids the N+1 round-trips).\n\n    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {\n        if (keys.length === 0) return [];\n        const raws = (await this.client?.mget(...keys)) ?? [];\n        return keys.map((_, i) => {\n            const raw = raws[i];\n            return raw === null || raw === undefined ? undefined : decode<T>(raw);\n        });\n    }\n\n    async mset<T = unknown>(\n        entries: Array<[string, T]>,\n        ttl?: number\n    ): Promise<void> {\n        if (entries.length === 0) return;\n        const pipeline = this.client?.pipeline();\n        if (!pipeline) return;\n\n        for (const [key, value] of entries) {\n            const val = encode(value);\n            if (ttl) {\n                pipeline.set(key, val, 'EX', ttl);\n            } else {\n                pipeline.set(key, val);\n            }\n        }\n\n        await pipeline.exec();\n    }\n\n    async mdel(keys: string[]): Promise<void> {\n        if (keys.length === 0) return;\n        await this.client?.del(...keys);\n    }\n}\n","import type { App, Driver } from '@iskra-bun/core';\nimport type { KVAdapter } from './types';\nimport { MemoryAdapter } from './adapters/memory';\nimport { RedisAdapter } from './adapters/redis';\n\nexport interface KVManagerOptions {\n    /**\n     * Optional namespace prepended to every key as `\"<namespace>:<key>\"`.\n     * Defaults to `\"\"` (no prefix) to preserve existing behavior.\n     */\n    namespace?: string;\n}\n\nexport class KVManager implements Driver, KVAdapter {\n    name = 'KVManager';\n    id = 'manager';\n    private app: App | null = null;\n    private adapter: KVAdapter;\n    private readonly prefix: string;\n\n    constructor(options: KVManagerOptions = {}) {\n        // Default to memory until configured\n        this.adapter = new MemoryAdapter();\n        this.prefix = options.namespace ? `${options.namespace}:` : '';\n    }\n\n    init(app: App) {\n        this.app = app;\n        const config = app.config.kv;\n\n        if (config?.driver === 'redis') {\n            app.logger.info('Initializing KV with Redis');\n            this.adapter = new RedisAdapter(config.connection);\n        } else {\n            app.logger.info('Initializing KV with Memory');\n            this.adapter = new MemoryAdapter();\n        }\n    }\n\n    async connect() {\n        await this.adapter.connect();\n        this.app?.logger.info('KV Store connected');\n    }\n\n    async disconnect() {\n        await this.adapter.disconnect();\n    }\n\n    // Driver Interface\n    async start() {\n        await this.connect();\n    }\n\n    async stop() {\n        await this.disconnect();\n    }\n\n    private prefixed(key: string): string {\n        return `${this.prefix}${key}`;\n    }\n\n    // Proxy methods (namespace-aware)\n    get<T = unknown>(key: string): Promise<T | undefined> {\n        return this.adapter.get<T>(this.prefixed(key));\n    }\n\n    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        return this.adapter.set<T>(this.prefixed(key), value, ttl);\n    }\n\n    del(key: string): Promise<void> {\n        return this.adapter.del(this.prefixed(key));\n    }\n\n    has(key: string): Promise<boolean> {\n        return this.adapter.has(this.prefixed(key));\n    }\n\n    // Batch operations. When the underlying adapter exposes a native batch\n    // method, the manager delegates to it (a single round-trip) after applying\n    // the namespace prefix; otherwise it falls back to a per-key loop. This\n    // keeps the optional adapter methods out of the hot path for adapters that\n    // do not implement them while avoiding the N+1 fan-out for those that do.\n\n    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {\n        const prefixed = keys.map(k => this.prefixed(k));\n\n        if (this.adapter.mget) {\n            return this.adapter.mget<T>(prefixed);\n        }\n\n        return Promise.all(prefixed.map(k => this.adapter.get<T>(k)));\n    }\n\n    async mset<T = unknown>(\n        entries: Array<[string, T]> | Record<string, T>,\n        ttl?: number\n    ): Promise<void> {\n        const pairs: Array<[string, T]> = Array.isArray(entries)\n            ? entries\n            : (Object.entries(entries) as Array<[string, T]>);\n\n        const prefixed: Array<[string, T]> = pairs.map(\n            ([k, v]) => [this.prefixed(k), v] as [string, T]\n        );\n\n        if (this.adapter.mset) {\n            await this.adapter.mset<T>(prefixed, ttl);\n            return;\n        }\n\n        await Promise.all(prefixed.map(([k, v]) => this.adapter.set<T>(k, v, ttl)));\n    }\n\n    async mdel(keys: string[]): Promise<void> {\n        const prefixed = keys.map(k => this.prefixed(k));\n\n        if (this.adapter.mdel) {\n            await this.adapter.mdel(prefixed);\n            return;\n        }\n\n        await Promise.all(prefixed.map(k => this.adapter.del(k)));\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/manager.ts","../src/ttl.ts","../src/adapters/memory.ts","../src/adapters/redis.ts"],"sourcesContent":["import { isProductionEnv, type App, type Driver } from '@iskra-bun/core';\nimport type { Redis } from 'ioredis';\nimport type { KVAdapter } from './types';\nimport { MemoryAdapter } from './adapters/memory';\nimport { RedisAdapter } from './adapters/redis';\n\nexport interface KVManagerOptions {\n    /**\n     * Optional namespace prepended to every key as `\"<namespace>:<key>\"`.\n     * Defaults to `\"\"` (no prefix) to preserve existing behavior.\n     */\n    namespace?: string;\n    /**\n     * Lets `clear()` without a `namespace` empty the whole Redis database\n     * (FLUSHDB). Only for a database no other app or service writes to.\n     */\n    flushDb?: boolean;\n}\n\nexport class KVManager implements Driver, KVAdapter {\n    name = 'KVManager';\n    id = 'manager';\n    private app: App | null = null;\n    private adapter: KVAdapter;\n    private readonly prefix: string;\n    private readonly flushDb: boolean;\n\n    constructor(options: KVManagerOptions = {}) {\n        // The store is chosen by the App's config (`kv.driver`), not here: an\n        // `adapter: 'redis'` copied from an old README was ignored, and the app\n        // silently ran on per-process memory.\n        const misplaced = ['adapter', 'driver', 'connection'].filter((key) => key in options);\n        if (misplaced.length > 0) {\n            throw new Error(\n                `KVManager does not take ${misplaced.map((k) => `\"${k}\"`).join(', ')}: choose the store in the App config, ` +\n                    \"e.g. new App({ name, kv: { driver: 'redis', connection: process.env.REDIS_URL } })\",\n            );\n        }\n        // Default to memory until configured\n        this.adapter = new MemoryAdapter();\n        this.prefix = options.namespace ? `${options.namespace}:` : '';\n        this.flushDb = options.flushDb ?? false;\n    }\n\n    init(app: App) {\n        this.app = app;\n        // Like db-kit's 'db': services look the store up as app.context.get('kv').\n        app.context.set('kv', this);\n        const config = app.config.kv;\n\n        if (config?.driver === 'redis') {\n            app.logger.info('Initializing KV with Redis');\n            this.adapter = new RedisAdapter(config.connection ?? {}, {\n                onError: (err) => app.logger.warn({ err }, 'KV Redis connection error'),\n                flushDb: this.flushDb,\n            });\n        } else if (!config?.driver || config.driver === 'memory') {\n            if (!config?.driver && isProductionEnv()) {\n                app.logger.warn(\n                    'KV has no driver configured: using the in-memory store, which each process keeps on its own ' +\n                        \"and loses on restart. Set kv: { driver: 'redis', connection } in the App config, or \" +\n                        \"kv: { driver: 'memory' } to keep it.\",\n                );\n            }\n            app.logger.info('Initializing KV with Memory');\n            this.adapter = new MemoryAdapter();\n        } else {\n            // Unknown drivers (e.g. 'libsql') used to fall back to memory\n            // silently, losing every value on restart.\n            throw new Error(`Unsupported KV driver \"${config.driver}\" (supported: \"memory\", \"redis\")`);\n        }\n    }\n\n    async connect() {\n        await this.adapter.connect();\n        this.app?.logger.info('KV Store connected');\n    }\n\n    async disconnect() {\n        await this.adapter.disconnect();\n    }\n\n    // Driver Interface\n    async start() {\n        await this.connect();\n    }\n\n    async stop() {\n        await this.disconnect();\n    }\n\n    /**\n     * The underlying ioredis client with the \"redis\" driver, once started: for\n     * commands the KV API does not cover (sets, sorted sets, pipelines). It\n     * bypasses `namespace` and the JSON codec. `undefined` with the memory\n     * driver or before start().\n     */\n    get client(): Redis | undefined {\n        return this.adapter instanceof RedisAdapter ? (this.adapter.nativeClient ?? undefined) : undefined;\n    }\n\n    private prefixed(key: string): string {\n        return `${this.prefix}${key}`;\n    }\n\n    // Proxy methods (namespace-aware)\n    get<T = unknown>(key: string): Promise<T | undefined> {\n        return this.adapter.get<T>(this.prefixed(key));\n    }\n\n    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        return this.adapter.set<T>(this.prefixed(key), value, ttl);\n    }\n\n    del(key: string): Promise<void> {\n        return this.adapter.del(this.prefixed(key));\n    }\n\n    has(key: string): Promise<boolean> {\n        return this.adapter.has(this.prefixed(key));\n    }\n\n    // Batch operations. When the underlying adapter exposes a native batch\n    // method, the manager delegates to it (a single round-trip) after applying\n    // the namespace prefix; otherwise it falls back to a per-key loop. This\n    // keeps the optional adapter methods out of the hot path for adapters that\n    // do not implement them while avoiding the N+1 fan-out for those that do.\n\n    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {\n        const prefixed = keys.map((k) => this.prefixed(k));\n\n        if (this.adapter.mget) {\n            return this.adapter.mget<T>(prefixed);\n        }\n\n        return Promise.all(prefixed.map((k) => this.adapter.get<T>(k)));\n    }\n\n    async mset<T = unknown>(entries: Array<[string, T]> | Record<string, T>, ttl?: number): Promise<void> {\n        const pairs: Array<[string, T]> = Array.isArray(entries)\n            ? entries\n            : (Object.entries(entries) as Array<[string, T]>);\n\n        const prefixed: Array<[string, T]> = pairs.map(([k, v]) => [this.prefixed(k), v] as [string, T]);\n\n        if (this.adapter.mset) {\n            await this.adapter.mset<T>(prefixed, ttl);\n            return;\n        }\n\n        await Promise.all(prefixed.map(([k, v]) => this.adapter.set<T>(k, v, ttl)));\n    }\n\n    async mdel(keys: string[]): Promise<void> {\n        const prefixed = keys.map((k) => this.prefixed(k));\n\n        if (this.adapter.mdel) {\n            await this.adapter.mdel(prefixed);\n            return;\n        }\n\n        await Promise.all(prefixed.map((k) => this.adapter.del(k)));\n    }\n\n    /**\n     * Deletes every key under `prefix` in this manager's namespace (the whole\n     * namespace without one). With the redis driver and no namespace, only\n     * `flushDb: true` lets it empty the database.\n     */\n    async clear(prefix = ''): Promise<void> {\n        if (!this.adapter.clear) throw unsupported(this.adapter, 'clear');\n        await this.adapter.clear(this.prefixed(prefix));\n    }\n\n    /** See {@link KVAdapter.sadd}: the member is kept as is, only `key` is namespaced. */\n    async sadd(key: string, member: string, ttl?: number): Promise<void> {\n        if (!this.adapter.sadd) throw unsupported(this.adapter, 'sadd');\n        await this.adapter.sadd(this.prefixed(key), member, ttl);\n    }\n\n    async sdrain(key: string): Promise<string[]> {\n        if (!this.adapter.sdrain) throw unsupported(this.adapter, 'sdrain');\n        return this.adapter.sdrain(this.prefixed(key));\n    }\n}\n\n/** Both built-in adapters have the optional methods; an injected one may not. */\nfunction unsupported(adapter: KVAdapter, method: string): Error {\n    return new Error(`The \"${adapter.id}\" KV adapter does not support ${method}()`);\n}\n\n// `app.context.get('kv')` is the KVManager registered on the app.\ndeclare module '@iskra-bun/core' {\n    interface AppContextRegistry {\n        kv: KVManager;\n    }\n}\n","/**\n * A TTL in seconds: `undefined`, `null` or `0` mean \"no expiry\". Anything else\n * must be a positive finite number: a negative TTL used to delete the key at\n * once with the memory adapter and fail with Redis.\n */\nexport function checkTtl(ttl: number | null | undefined): number | undefined {\n    if (ttl === undefined || ttl === null || ttl === 0) return undefined;\n    if (typeof ttl !== 'number' || !Number.isFinite(ttl) || ttl < 0) {\n        throw new RangeError(`Invalid TTL ${String(ttl)}: expected a positive number of seconds`);\n    }\n    return ttl;\n}\n","import type { KVAdapter } from '../types';\nimport { checkTtl } from '../ttl';\n\n/** setTimeout's limit: a longer delay (a TTL over ~24.8 days) fires at once. */\nconst MAX_TIMEOUT_MS = 2 ** 31 - 1;\n\n/** An expiring set: each member's expiry (ms since the epoch, Infinity for none). */\ninterface ExpiringSet {\n    members: Map<string, number>;\n    expiresAt: number;\n    /** Size at which expired members are next dropped. */\n    pruneAt: number;\n}\n\nexport class MemoryAdapter implements KVAdapter {\n    id = 'memory';\n    private store = new Map<string, unknown>();\n    private sets = new Map<string, ExpiringSet>();\n    private timers = new Map<string, ReturnType<typeof setTimeout>>();\n\n    connect() {\n        // No-op\n    }\n\n    disconnect() {\n        for (const timer of this.timers.values()) {\n            clearTimeout(timer);\n        }\n        this.timers.clear();\n        this.store.clear();\n        this.sets.clear();\n    }\n\n    // Values are copied in and out, as Redis does: a stored object returned by\n    // reference let one request's mutation show up in every other one.\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        return structuredClone(this.store.get(key)) as T | undefined;\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        const seconds = checkTtl(ttl);\n        const copy = structuredClone(value);\n        // Note: storing `null`/`undefined` is undefined behavior across adapters.\n        // This in-memory adapter stores the value verbatim (so `get` returns it\n        // as-is), whereas the RedisAdapter normalizes both to \"absent\" because\n        // they have no faithful JSON round-trip. Callers should not depend on\n        // either form being preserved.\n        //\n        // Clear any existing expiry timer for this key before setting a new one\n        this.clearTimer(key);\n        this.sets.delete(key);\n        this.store.set(key, copy);\n\n        if (seconds !== undefined) this.expireIn(key, seconds * 1000);\n    }\n\n    /** Arms the expiry timer, in steps when the delay exceeds setTimeout's limit. */\n    private expireIn(key: string, ms: number) {\n        const step = Math.min(ms, MAX_TIMEOUT_MS);\n        const timer = setTimeout(() => {\n            if (ms > step) {\n                this.expireIn(key, ms - step);\n                return;\n            }\n            this.store.delete(key);\n            this.sets.delete(key);\n            this.timers.delete(key);\n        }, step);\n\n        // Avoid keeping the process alive just for expiry timers\n        timer.unref?.();\n\n        this.timers.set(key, timer);\n    }\n\n    private clearTimer(key: string) {\n        const timer = this.timers.get(key);\n        if (timer !== undefined) {\n            clearTimeout(timer);\n            this.timers.delete(key);\n        }\n    }\n\n    async del(key: string): Promise<void> {\n        this.clearTimer(key);\n        this.store.delete(key);\n        this.sets.delete(key);\n    }\n\n    async has(key: string): Promise<boolean> {\n        return this.store.has(key) || this.sets.has(key);\n    }\n\n    async clear(prefix = ''): Promise<void> {\n        for (const key of [...this.store.keys(), ...this.sets.keys()]) {\n            if (key.startsWith(prefix)) await this.del(key);\n        }\n    }\n\n    async sadd(key: string, member: string, ttl?: number): Promise<void> {\n        const seconds = checkTtl(ttl);\n        const now = Date.now();\n        const expiresAt = seconds === undefined ? Infinity : now + seconds * 1000;\n        let set = this.sets.get(key);\n        if (!set) {\n            this.store.delete(key);\n            set = { members: new Map(), expiresAt: 0, pruneAt: 64 };\n            this.sets.set(key, set);\n        }\n        // A member keeps its latest expiry: dropped earlier, an entry written\n        // with a longer TTL would survive an invalidation of its tag.\n        set.members.set(member, Math.max(set.members.get(member) ?? 0, expiresAt));\n        // Expired members go each time the set doubles: O(1) per add on average.\n        if (set.members.size >= set.pruneAt) {\n            for (const [name, at] of set.members) if (at <= now) set.members.delete(name);\n            set.pruneAt = Math.max(64, set.members.size * 2);\n        }\n        if (expiresAt > set.expiresAt) {\n            set.expiresAt = expiresAt;\n            this.clearTimer(key);\n            if (expiresAt !== Infinity) this.expireIn(key, expiresAt - now);\n        }\n    }\n\n    async sdrain(key: string): Promise<string[]> {\n        const set = this.sets.get(key);\n        if (!set) return [];\n        this.sets.delete(key);\n        this.clearTimer(key);\n        const now = Date.now();\n        return [...set.members].filter(([, at]) => at > now).map(([name]) => name);\n    }\n}\n","import type { KVAdapter } from '../types';\nimport { checkTtl } from '../ttl';\nimport Redis from 'ioredis';\nimport type { RedisOptions } from 'ioredis';\n\n/**\n * Single consistent codec shared by every write/read path.\n *\n * `undefined` is guarded explicitly: there is no JSON representation for it,\n * so it is stored as the JSON `null` literal and decoded back to `undefined`\n * on read. Every other value is `JSON.stringify`'d on write and `JSON.parse`'d\n * on read, so the string \"123\" round-trips as the string \"123\" (not the number\n * 123) and \"{}\" round-trips as the string \"{}\" (not an empty object).\n */\nfunction encode<T>(value: T): string {\n    if (value === undefined) return 'null';\n    return JSON.stringify(value);\n}\n\nfunction decode<T>(raw: string): T | undefined {\n    try {\n        const parsed = JSON.parse(raw) as T | null;\n        return parsed === null ? undefined : (parsed as T);\n    } catch {\n        // Tolerate values written outside the adapter that are not valid JSON.\n        return raw as unknown as T;\n    }\n}\n\n/**\n * Connection settings: a `redis://` / `rediss://` URL, ioredis options, or\n * ioredis options with a `url` (the form used in app.config and the docs).\n */\nexport type RedisAdapterOptions = string | (RedisOptions & { url?: string });\n\nexport interface RedisAdapterHooks {\n    /**\n     * Receives the client's `error` events (a dropped connection, each failed\n     * reconnect). Without it they are ignored; ioredis printed them to the\n     * console, outside the app's logger.\n     */\n    onError?: (error: Error) => void;\n    /**\n     * Lets `clear()` with no key prefix at all run FLUSHDB, which empties the\n     * whole Redis database, other apps' keys included.\n     */\n    flushDb?: boolean;\n}\n\n/** `EX` for whole seconds; `PX` for fractional TTLs, which Redis `EX` rejects. */\nfunction ttlArgs(ttl: number): ['EX', number] | ['PX', number] {\n    return Number.isInteger(ttl) ? ['EX', ttl] : ['PX', Math.max(1, Math.round(ttl * 1000))];\n}\n\n/** `prefix` as a literal in a SCAN MATCH pattern. */\nconst escapeGlob = (prefix: string): string => prefix.replace(/[*?[\\]\\\\]/g, '\\\\$&');\n\n/** Keys deleted per DEL while clearing. */\nconst CLEAR_BATCH = 1000;\n\n/**\n * An expiring set is a sorted set scored by each member's expiry (Redis time,\n * in ms; FOREVER for none). Adding a member drops the expired ones and keeps\n * the key alive until its last member expires, in one atomic step.\n * KEYS[1]: the set; ARGV[1]: the member; ARGV[2]: its TTL in ms, '' for none.\n */\nconst SADD_SCRIPT = `\nif redis.replicate_commands then redis.replicate_commands() end\nlocal forever = 9007199254740991\nlocal t = redis.call('TIME')\nlocal now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nlocal expires = forever\nif ARGV[2] ~= '' then expires = now + tonumber(ARGV[2]) end\nlocal current = tonumber(redis.call('ZSCORE', KEYS[1], ARGV[1]) or '0')\nif expires > current then redis.call('ZADD', KEYS[1], expires, ARGV[1]) end\nredis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', '(' .. now)\nlocal last = redis.call('ZRANGE', KEYS[1], -1, -1, 'WITHSCORES')\nif tonumber(last[2]) >= forever then\n    redis.call('PERSIST', KEYS[1])\nelse\n    redis.call('PEXPIREAT', KEYS[1], last[2])\nend\n`;\n\n/**\n * Returns the unexpired members of an expiring set (see SADD_SCRIPT) and\n * deletes it, in one atomic step: members past their expiry are left out, as\n * the memory adapter does. KEYS[1]: the set.\n */\nconst SDRAIN_SCRIPT = `\nif redis.replicate_commands then redis.replicate_commands() end\nlocal t = redis.call('TIME')\nlocal now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nlocal members = redis.call('ZRANGEBYSCORE', KEYS[1], '(' .. now, '+inf')\nredis.call('DEL', KEYS[1])\nreturn members\n`;\n\n/**\n * ioredis errors carry the command they answer with its arguments: AUTH's\n * password on a refused login, which the app then logged. Only the command\n * name is kept.\n */\nfunction withoutCommandArgs<E>(error: E): E {\n    const command = (error as { command?: { name?: unknown; args?: unknown } } | null)?.command;\n    if (command && typeof command === 'object' && 'args' in command) {\n        (error as { command: unknown }).command = { name: command.name };\n    }\n    return error;\n}\n\nexport class RedisAdapter implements KVAdapter {\n    id = 'redis';\n    private client: Redis | null = null;\n    private readonly options: RedisAdapterOptions;\n    private readonly hooks: RedisAdapterHooks;\n\n    constructor(options: RedisAdapterOptions, hooks: RedisAdapterHooks = {}) {\n        this.options = options;\n        this.hooks = hooks;\n    }\n\n    /**\n     * Connects and waits for Redis to answer: an unreachable server or a wrong\n     * password fails here (and so the app's start) instead of on the first\n     * command. Once connected, a dropped connection is retried by ioredis.\n     */\n    async connect() {\n        // ioredis only parses a URL passed as its own argument: an object with\n        // a `url` key was ignored and it silently connected to localhost:6379.\n        let client: Redis;\n        if (typeof this.options === 'string') {\n            client = new Redis(this.options, { lazyConnect: true });\n        } else if (this.options.url) {\n            const { url, ...rest } = this.options;\n            client = new Redis(url, { ...rest, lazyConnect: true });\n        } else {\n            client = new Redis({ ...this.options, lazyConnect: true });\n        }\n        client.on('error', (error: Error) => this.hooks.onError?.(withoutCommandArgs(error)));\n        try {\n            await client.connect();\n        } catch (error) {\n            client.disconnect();\n            // The message, not the URL: it may carry the password.\n            throw new Error(`Could not connect to Redis: ${error instanceof Error ? error.message : String(error)}`, {\n                cause: withoutCommandArgs(error),\n            });\n        }\n        this.client = client;\n    }\n\n    /** Longest wait for QUIT before the connection is closed anyway. */\n    protected quitTimeoutMs = 2000;\n\n    /**\n     * Closes the connection. When connected, QUIT lets pending replies arrive\n     * (in-flight writes are not dropped), for at most `quitTimeoutMs`. When the\n     * connection is down, ioredis would queue QUIT behind the offline queue and\n     * resolve only after its reconnect attempts run out (about 10 s by default,\n     * never with `maxRetriesPerRequest: null`), eating the app's shutdown\n     * timeout: the client is closed at once instead.\n     */\n    async disconnect() {\n        const client = this.client;\n        this.client = null;\n        if (!client) return;\n        if (typeof client.quit !== 'function' || client.status !== 'ready') {\n            client.disconnect();\n            return;\n        }\n        let timer: ReturnType<typeof setTimeout> | undefined;\n        const timedOut = new Promise<'timeout'>((resolve) => {\n            timer = setTimeout(() => resolve('timeout'), this.quitTimeoutMs);\n        });\n        const outcome = await Promise.race([\n            client.quit().then(\n                () => 'quit' as const,\n                () => 'error' as const,\n            ),\n            timedOut,\n        ]);\n        clearTimeout(timer);\n        if (outcome !== 'quit') client.disconnect();\n    }\n\n    /** The ioredis client once connected (null before connect() and after disconnect()). */\n    get nativeClient(): Redis | null {\n        return this.client;\n    }\n\n    /** The live client; operations before connect() fail instead of silently doing nothing. */\n    private get redis(): Redis {\n        if (!this.client) throw new Error('RedisAdapter is not connected; call connect() first');\n        return this.client;\n    }\n\n    async get<T = unknown>(key: string): Promise<T | undefined> {\n        const val = await this.redis.get(key);\n        if (val === null || val === undefined) return undefined;\n        return decode<T>(val);\n    }\n\n    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {\n        const val = encode(value);\n        const seconds = checkTtl(ttl);\n        if (seconds !== undefined) {\n            await this.redis.set(key, val, ...(ttlArgs(seconds) as ['EX', number]));\n        } else {\n            await this.redis.set(key, val);\n        }\n    }\n\n    async del(key: string) {\n        await this.redis.del(key);\n    }\n\n    async has(key: string) {\n        const exists = await this.redis.exists(key);\n        return exists === 1;\n    }\n\n    // Native batch operations. A single MGET / pipelined MSET / variadic DEL\n    // replaces the manager's per-key fan-out (avoids the N+1 round-trips).\n\n    async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {\n        if (keys.length === 0) return [];\n        const raws = (await this.redis.mget(...keys)) ?? [];\n        return keys.map((_, i) => {\n            const raw = raws[i];\n            return raw === null || raw === undefined ? undefined : decode<T>(raw);\n        });\n    }\n\n    async mset<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void> {\n        const seconds = checkTtl(ttl);\n        if (entries.length === 0) return;\n        const pipeline = this.redis.pipeline();\n\n        for (const [key, value] of entries) {\n            const val = encode(value);\n            if (seconds !== undefined) {\n                pipeline.set(key, val, ...(ttlArgs(seconds) as ['EX', number]));\n            } else {\n                pipeline.set(key, val);\n            }\n        }\n\n        // exec() resolves even when individual commands fail; surface them.\n        const results = await pipeline.exec();\n        const failed = results?.find(([err]) => err);\n        if (failed) throw failed[0];\n    }\n\n    async mdel(keys: string[]): Promise<void> {\n        if (keys.length === 0) return;\n        await this.redis.del(...keys);\n    }\n\n    /**\n     * Deletes the keys under `prefix` (after ioredis' own `keyPrefix`, if set)\n     * with SCAN and DEL. With no prefix at all this would be every key in the\n     * database, which only `flushDb: true` allows (as a FLUSHDB).\n     */\n    async clear(prefix = ''): Promise<void> {\n        const redis = this.redis;\n        const keyPrefix = redis.options.keyPrefix ?? '';\n        if (!keyPrefix && !prefix) {\n            if (!this.hooks.flushDb) {\n                throw new Error(\n                    'RedisAdapter.clear() without a key prefix would empty the whole Redis database: ' +\n                        'give the KVManager a namespace, or pass flushDb: true if the database belongs to this app alone',\n                );\n            }\n            await redis.flushdb();\n            return;\n        }\n        const match = `${escapeGlob(keyPrefix + prefix)}*`;\n        let cursor = '0';\n        do {\n            const [next, keys] = await redis.scan(cursor, 'MATCH', match, 'COUNT', CLEAR_BATCH);\n            cursor = next;\n            // SCAN returns whole keys, and ioredis prepends keyPrefix to DEL's.\n            if (keys.length > 0) await redis.del(...keys.map((key) => key.slice(keyPrefix.length)));\n        } while (cursor !== '0');\n    }\n\n    async sadd(key: string, member: string, ttl?: number): Promise<void> {\n        const seconds = checkTtl(ttl);\n        const ms = seconds === undefined ? '' : String(Math.max(1, Math.ceil(seconds * 1000)));\n        await this.redis.eval(SADD_SCRIPT, 1, key, member, ms);\n    }\n\n    async sdrain(key: string): Promise<string[]> {\n        return (await this.redis.eval(SDRAIN_SCRIPT, 1, key)) as string[];\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/kv-kit",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Key-Value store de Iskra con adaptadores de Redis y memoria.",
     "keywords": [
         "iskra",
@@ -20,6 +20,9 @@
     },
     "homepage": "https://github.com/fearful/iskra/tree/main/packages/kv-kit#readme",
     "bugs": "https://github.com/fearful/iskra/issues",
+    "engines": {
+        "bun": ">=1.3.0"
+    },
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",
@@ -47,7 +50,7 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.1",
+        "@iskra-bun/core": "^0.2.0",
         "ioredis": "^5.4.1"
     },
     "devDependencies": {

package/src/adapters/memory.ts

@@ -1,8 +1,21 @@
 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, unknown>();
+    private sets = new Map<string, ExpiringSet>();
     private timers = new Map<string, ReturnType<typeof setTimeout>>();
 
     connect() {
@@ -15,13 +28,18 @@ export class MemoryAdapter implements KVAdapter {
         }
         this.timers.clear();
         this.store.clear();
+        this.sets.clear();
     }
 
+    // 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 this.store.get(key) as 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
@@ -29,37 +47,87 @@ export class MemoryAdapter implements KVAdapter {
         // either form being preserved.
         //
         // Clear any existing expiry timer for this key before setting a new one
-        const existing = this.timers.get(key);
-        if (existing !== undefined) {
-            clearTimeout(existing);
-            this.timers.delete(key);
-        }
+        this.clearTimer(key);
+        this.sets.delete(key);
+        this.store.set(key, copy);
 
-        this.store.set(key, value);
+        if (seconds !== undefined) this.expireIn(key, seconds * 1000);
+    }
 
-        if (ttl) {
-            const timer = setTimeout(() => {
-                this.store.delete(key);
-                this.timers.delete(key);
-            }, ttl * 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?.();
+        // Avoid keeping the process alive just for expiry timers
+        timer.unref?.();
 
-            this.timers.set(key, timer);
-        }
+        this.timers.set(key, timer);
     }
 
-    async del(key: string): Promise<void> {
+    private clearTimer(key: string) {
         const timer = this.timers.get(key);
         if (timer !== undefined) {
             clearTimeout(timer);
             this.timers.delete(key);
         }
+    }
+
+    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);
+        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 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,4 +1,5 @@
 import type { KVAdapter } from '../types';
+import { checkTtl } from '../ttl';
 import Redis from 'ioredis';
 import type { RedisOptions } from 'ioredis';
 
@@ -26,44 +27,196 @@ function decode<T>(raw: string): T | undefined {
     }
 }
 
+/**
+ * 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 readonly options: RedisOptions | string;
+    private readonly options: RedisAdapterOptions;
+    private readonly hooks: RedisAdapterHooks;
 
-    constructor(options: RedisOptions | string) {
+    constructor(options: RedisAdapterOptions, hooks: RedisAdapterHooks = {}) {
         this.options = options;
+        this.hooks = hooks;
+    }
+
+    /**
+     * 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;
     }
 
-    connect() {
-        this.client = new Redis(this.options as RedisOptions);
+    /** Longest wait for QUIT before the connection is closed anyway. */
+    protected quitTimeoutMs = 2000;
+
+    /**
+     * 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();
     }
 
-    disconnect() {
-        this.client?.disconnect();
+    /** 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.client?.get(key);
+        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);
-        if (ttl) {
-            await this.client?.set(key, val, 'EX', ttl);
+        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;
     }
 
@@ -72,35 +225,73 @@ export class RedisAdapter implements KVAdapter {
 
     async mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]> {
         if (keys.length === 0) return [];
-        const raws = (await this.client?.mget(...keys)) ?? [];
+        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> {
+    async mset<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void> {
+        const seconds = checkTtl(ttl);
         if (entries.length === 0) return;
-        const pipeline = this.client?.pipeline();
-        if (!pipeline) return;
+        const pipeline = this.redis.pipeline();
 
         for (const [key, value] of entries) {
             const val = encode(value);
-            if (ttl) {
-                pipeline.set(key, val, 'EX', ttl);
+            if (seconds !== undefined) {
+                pipeline.set(key, val, ...(ttlArgs(seconds) as ['EX', number]));
             } else {
                 pipeline.set(key, val);
             }
         }
 
-        await pipeline.exec();
+        // 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.client?.del(...keys);
+        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[];
     }
 }