@iskra-bun/kv-kit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @iskra-bun/kv-kit
 
+## 0.3.0
+
+### Minor Changes
+
+- 87f6de2: `KVManager` throws when its constructor gets `adapter`, `driver` or `connection`: the store is chosen by the App config (`kv: { driver, connection }`), and the README's `new KVManager({ adapter: 'redis' })` was silently ignored, leaving the app on per-process memory. Without a `kv` driver it now logs a warning in production instead of an info line. The READMEs of kv-kit, worker-kit (`connection` and `queueName`, not `queue`), db-kit (the App's `db` config) and process-kit (the App's `processes` config) show working examples.
+- 58d4a8f: `KVManager` registers itself in the app context as `'kv'` (as db-kit does with `'db'`) and exposes the underlying ioredis client as `client` (Redis driver, after `start()`; it bypasses `namespace` and the JSON codec) for commands the KV API does not cover, such as sets. forms-app's services read `app.context.get('kv').client`, which was always `undefined`, so they silently skipped every Redis read and write and no published form could be found.
+- dbf8817: Redis connection fixes for kv-kit (also used by cache-kit's `RedisAdapter`).
+
+    - `connection: { url }`, as shown in the docs, was ignored by ioredis, so the adapter silently connected to `localhost:6379` db 0. The URL is now honored; a plain URL string or regular ioredis options also work.
+    - Fractional TTLs (e.g. `0.5`) use `PX` instead of failing on Redis `EX`, and `mset` reports errors from individual pipelined commands instead of ignoring them.
+    - `disconnect()` uses `QUIT`, so in-flight writes are not dropped.
+    - **Breaking:** operations before `connect()` now throw instead of silently doing nothing, and an unsupported `kv.driver` (such as `"libsql"`, which never had an adapter and fell back to memory) now throws at `init()`. `AppConfig.kv.driver` is `"memory" | "redis"`.
+
+- 938dd41: **Security** fixes from the data-kits audit (round 2).
+
+    - `storage-kit` (**breaking**): files are stored and served with a type from their extension (`contentTypeFor`), and anything but a raster image as a download. The S3 adapter stores a `Content-Disposition` with each object (`attachment` unless it is a PNG, JPEG, GIF, WebP, AVIF, BMP or ICO image; `put(..., { contentDisposition })` to choose), and `url()` signs `response-content-type` and `response-content-disposition` into presigned URLs whatever the object was stored with (`url(path, expiresIn, { contentType, contentDisposition })` to choose): an upload named `logo.svg` or `invoice.html` was stored as `image/svg+xml`/`text/html` and ran its scripts on the bucket's origin. HTML, SVG, XML and JavaScript are now `application/octet-stream`. `put(..., { overwrite: false })` throws the new `FileExistsError` instead of replacing a stored file (S3 `If-None-Match: *`, an exclusive create locally); `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` now need 3.635 or later, the first releases that send `If-None-Match` on a put (earlier ones dropped it, and the file was replaced). The plaintext-endpoint guard parses the endpoint as a URL, as the SDK does: `http:/minio:9000`, `http:minio:9000` and `http:\\minio:9000` were accepted without `useSSL: false`; an endpoint that is not an `http(s)` URL is rejected.
+    - `web-kit` uploads (**breaking**): the upload route stores a file with the type of its extension, never `File.type` (which Bun derives from the name), and `uploadFromRequest()` too. Downloads are streamed with `getStream()` (each one was buffered twice), typed by extension, `attachment` unless a raster image, and sandboxed (`Content-Security-Policy: sandbox`). Without `allowedExtensions`, active web content (`.html`, `.svg`, `.xml`, `.js`...) is refused (400) unless listed. `authorize(c, action, target)` receives what the action touches (`{ key, subfolder, filename, size, type }`), and `upload` is asked again with it before the file is written. An upload no longer replaces a stored file: **409** unless `overwrite: true`.
+    - `mailer-kit` (**breaking**): every `to`, `cc`, `bcc` and `replyTo` entry must be one bare address, or a new `{ name, address }` object for a display name, in every adapter (the mock too); only `from` was checked. One value such as `"bob@example.com <attacker@evil.test>, x@example.com"`, a group (`"undisclosed: a@evil.test; b@x.com"`, `"a@evil.test:b@x.com"`) or `{ address: "bob@example.com\r\nBcc: …" }` mailed other recipients than the ones an allowlist checked. Addresses may not contain whitespace, control characters or `<>()[]\,;:"` and need exactly one `@`; `replyTo` takes one recipient. `checkRecipients()` is exported. Mailgun cuts the `subject` at a CR/LF, as it does header values.
+    - `web-kit` email: `EmailFeature`'s adapter checks recipients with mailer-kit's rules (object recipients were tested as `"[object Object]"`), and rejects through the returned promise instead of throwing synchronously.
+    - `kv-kit`: the `KVAdapter` contract gains an optional `clear(prefix?)` and expiring sets (`sadd(key, member, ttl?)`, `sdrain(key)`), implemented by both adapters and `KVManager`. `KVManager.clear()` deletes its namespace's keys; with Redis it uses `SCAN` + `DEL` (within ioredis' `keyPrefix` too) and, without a namespace, refuses to empty the whole database unless `new KVManager({ flushDb: true })`. Expiring sets are sorted sets scored by expiry, updated by one atomic script: cache-kit's tag index. The memory adapter stores and returns copies (`structuredClone`), as Redis does (**breaking** for values that cannot be cloned, such as functions): it returned the stored object itself, so one request's mutation showed up in every other.
+    - `cache-kit` (**breaking**): `clear()` runs the adapter's `clear()` with the cache's namespace instead of `disconnect()`/`connect()` of the shared adapter, which on Redis deleted nothing (cached permissions stayed), failed concurrent operations meanwhile, and left the adapter dead when the reconnect failed during a Redis blip. A namespaced cache now clears its own entries (it used to throw); an adapter without `clear()` makes it throw. The tag index is kv-kit's expiring set when the adapter has one (one atomic `sadd` per tagged `set()`; each one read and rewrote the whole index, and the last 10k of 40k tagged sets took 30 s), and otherwise a JSON list that drops expired keys, expires with its last entry and keeps at most 10,000 (the oldest are deleted with their data); indexes written before are still drained by `invalidateTag()`. A value with a `__proto__`/`constructor`/`prototype` key is a miss (deleted when read; not stored by `set()`), so `remember()` refetches instead of every read throwing until the TTL ran out. Data keys and namespaces containing `__cache_tag__:`/`__cache_tags__:` (at the start or after a `:`) are rejected: a caller-chosen key could rewrite a tag index, and `invalidateTag()` deleted whatever it listed.
+    - `db-kit` (**breaking**): `MigrationHelper` and the CLI run only the drizzle-kit installed in the project (`node_modules/.bin` of the working directory or a parent), with `bunx --no-install drizzle-kit`, and fail with a `MigrationError` where it is not installed. drizzle-kit is a devDependency, so in a production install `bunx drizzle-kit` downloaded its latest release from npm and ran it with `DATABASE_URL` in its environment.
+
+### Patch Changes
+
+- 840439a: Packages declare the runtime they are tested on: `engines.bun` `>=1.3.0` (the monorepo now builds and tests on Bun 1.3). `create-iskra`, a CLI that also runs under `npm create iskra`, declares `engines.node` `>=18`.
+
+    Every package is published with an npm provenance attestation (`publishConfig.provenance`), linking each version to the commit and CI run that built it.
+
+- cb3ec43: Register what each kit puts on the app with core's new registries: `app.context.get('db' | 'kv' | 'oracle')` returns the kit's driver, and the `process:*`, `socket:connected` / `socket:disconnected` and `worker:dead-letter` events have typed payloads. `ProcessManager.send()` takes `unknown` data.
+- 620da18: `RedisAdapter.disconnect()` (and so `KVManager.stop()`) no longer waits for Redis's reconnect attempts when the server is down: the client is closed at once. ioredis queued `QUIT` behind the pending commands, so it took about 10 s (never returned with `maxRetriesPerRequest: null`) and used up the app's shutdown timeout. When connected, `QUIT` is given at most 2 s.
+- c4ff1e3: The Redis adapter's `sdrain()` returns only the members that have not expired, as the memory adapter does. It returned every member still stored, expired ones included, until the next `sadd()` dropped them; it now reads and deletes the set in one script that filters by Redis time.
+- 7e89103: The Redis driver connects at `start()` and fails it when Redis is unreachable or rejects the password, instead of failing (or hanging) on the first command; ioredis connection errors go to the app's logger. The memory adapter keeps keys whose TTL exceeds `setTimeout`'s ~24.8-day limit (they expired at once), and a negative or non-finite TTL is rejected with a `RangeError` by both adapters. The docs no longer claim that `Date` or `Map` values round-trip through Redis.
+- 9bb254d: **Security** fixes from the plugin audit.
+
+    - `kv-kit`: Redis errors passed to `onError` (and so logged by `KVManager`) and the cause of a failed `connect()` keep only the command's name. ioredis attached its arguments, so a refused login logged the Redis password (`command.args` of AUTH), for example after a password rotation.
+    - `socket-kit`: `ctx.broadcast()` and `ctx.join()` refuse a room or topic that is not a string before calling `canPublish`/`canJoin`. A handler passing the client's value on could be given `["global"]`, which passes a deny-list such as `topic !== 'global'` and which Bun's `publish()` turns into `"global"`. The rate limiter logs one warning per connection and window instead of one per dropped frame (a flooding client wrote ~23 bytes of log per byte sent), and a frame that is not JSON is logged at debug level without a stack.
+    - `process-kit` (**breaking**): `send()` refuses a string with a line break, which the child read as several messages (send an object to have it JSON-encoded). After a stdout line longer than 1 MiB, the rest of that line is dropped instead of being read as a line of its own, which let text a child echoed come out as a JSON `process:message`. The spawn log line has the command and the number of arguments; the arguments, which can carry credentials, are logged at debug level.
+    - `create-iskra`: `scaffold()` only accepts the name of a bundled template (`../x` copied any directory into the new project), and `scripts/sync.ts` refuses symlinks in a template instead of copying their target into the published package.
+
+- Updated dependencies [620da18]
+- Updated dependencies [b635a2c]
+- Updated dependencies [5b2b0fd]
+- Updated dependencies [58d4a8f]
+- Updated dependencies [5c70c5b]
+- Updated dependencies [ec198d4]
+- Updated dependencies [cb3ec43]
+- Updated dependencies [ef2009b]
+- Updated dependencies [840439a]
+- Updated dependencies [dbf8817]
+- Updated dependencies [3dc5581]
+- Updated dependencies [9872d30]
+- Updated dependencies [f2346f5]
+- Updated dependencies [3579944]
+    - @iskra-bun/core@0.2.0
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -14,17 +14,22 @@ bun add @iskra-bun/kv-kit @iskra-bun/core
 import { App } from '@iskra-bun/core'
 import { KVManager } from '@iskra-bun/kv-kit'
 
-const app = new App({ name: 'mi-app' })
-app.register(new KVManager({ adapter: 'memory' }))
+const app = new App({
+  name: 'mi-app',
+  kv: { driver: 'redis', connection: process.env.REDIS_URL }, // o { driver: 'memory' }
+})
+const kv = new KVManager()
+app.register(kv)
 
 await app.start()
+await kv.set('usuario:123', { name: 'Ana' }, 60) // TTL en segundos
 ```
 
-Cambia `adapter: 'redis'` para usar Redis en produccion; la API (`get`/`set`/`del`/`has`, TTL) es identica entre adaptadores.
+El store se elige en la config de la App (`kv.driver`), no en el constructor de `KVManager`. Sin `kv` usa memoria: cada proceso tiene la suya y se pierde al reiniciar (en produccion lo avisa con un warning). La API (`get`/`set`/`del`/`has`, TTL) es identica entre adaptadores.
 
 ## Documentacion
 
-Guia completa: [docs/kv-kit.md](../../docs/kv-kit.md)
+Guia completa: [@iskra-bun/kv-kit](https://iskra-docs.fly.dev/es/packages/kv-kit/)
 
 ## Licencia
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Driver, App } from '@iskra-bun/core';
+import { Redis } from 'ioredis';
 
 interface KVAdapter {
     id: string;
@@ -11,6 +12,20 @@ interface KVAdapter {
     mget?<T = unknown>(keys: string[]): Promise<(T | undefined)[]>;
     mset?<T = unknown>(entries: Array<[string, T]>, ttl?: number): Promise<void>;
     mdel?(keys: string[]): Promise<void>;
+    /**
+     * Deletes every key that starts with `prefix` (every key the adapter holds
+     * without one), without touching the connection. An adapter that cannot
+     * leaves it out, and callers such as cache-kit's `clear()` then fail.
+     */
+    clear?(prefix?: string): Promise<void>;
+    /**
+     * Expiring sets, for cache-kit's tag index: `sadd` adds `member` to the set
+     * at `key` for `ttl` seconds (for good without one), and the set lives as
+     * long as its longest-lived member. `sdrain` deletes the set and returns
+     * its unexpired members in one step, so a member added meanwhile is never lost.
+     */
+    sadd?(key: string, member: string, ttl?: number): Promise<void>;
+    sdrain?(key: string): Promise<string[]>;
 }
 
 interface KVManagerOptions {
@@ -19,6 +34,11 @@ interface KVManagerOptions {
      * 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;
 }
 declare class KVManager implements Driver, KVAdapter {
     name: string;
@@ -26,12 +46,20 @@ declare class KVManager implements Driver, KVAdapter {
     private app;
     private adapter;
     private readonly prefix;
+    private readonly flushDb;
     constructor(options?: KVManagerOptions);
     init(app: App): void;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * 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;
     private prefixed;
     get<T = unknown>(key: string): Promise<T | undefined>;
     set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
@@ -40,6 +68,20 @@ declare class KVManager implements Driver, KVAdapter {
     mget<T = unknown>(keys: string[]): Promise<(T | undefined)[]>;
     mset<T = unknown>(entries: Array<[string, T]> | Record<string, T>, ttl?: number): Promise<void>;
     mdel(keys: string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    clear(prefix?: string): Promise<void>;
+    /** See {@link KVAdapter.sadd}: the member is kept as is, only `key` is namespaced. */
+    sadd(key: string, member: string, ttl?: number): Promise<void>;
+    sdrain(key: string): Promise<string[]>;
+}
+declare module '@iskra-bun/core' {
+    interface AppContextRegistry {
+        kv: KVManager;
+    }
 }
 
 export { type KVAdapter, KVManager };

package/dist/index.js

@@ -1,7 +1,21 @@
+// src/manager.ts
+import { isProductionEnv } from "@iskra-bun/core";
+
+// src/ttl.ts
+function checkTtl(ttl) {
+  if (ttl === void 0 || ttl === null || ttl === 0) return void 0;
+  if (typeof ttl !== "number" || !Number.isFinite(ttl) || ttl < 0) {
+    throw new RangeError(`Invalid TTL ${String(ttl)}: expected a positive number of seconds`);
+  }
+  return ttl;
+}
+
 // src/adapters/memory.ts
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
 var MemoryAdapter = class {
   id = "memory";
   store = /* @__PURE__ */ new Map();
+  sets = /* @__PURE__ */ new Map();
   timers = /* @__PURE__ */ new Map();
   connect() {
   }
@@ -11,36 +25,84 @@ var MemoryAdapter = class {
     }
     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(key) {
-    return this.store.get(key);
+    return structuredClone(this.store.get(key));
   }
   async set(key, value, ttl) {
-    const existing = this.timers.get(key);
-    if (existing !== void 0) {
-      clearTimeout(existing);
+    const seconds = checkTtl(ttl);
+    const copy = structuredClone(value);
+    this.clearTimer(key);
+    this.sets.delete(key);
+    this.store.set(key, copy);
+    if (seconds !== void 0) this.expireIn(key, seconds * 1e3);
+  }
+  /** Arms the expiry timer, in steps when the delay exceeds setTimeout's limit. */
+  expireIn(key, ms) {
+    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);
-    }
-    this.store.set(key, value);
-    if (ttl) {
-      const timer = setTimeout(() => {
-        this.store.delete(key);
-        this.timers.delete(key);
-      }, ttl * 1e3);
-      timer.unref?.();
-      this.timers.set(key, timer);
-    }
+    }, step);
+    timer.unref?.();
+    this.timers.set(key, timer);
   }
-  async del(key) {
+  clearTimer(key) {
     const timer = this.timers.get(key);
     if (timer !== void 0) {
       clearTimeout(timer);
       this.timers.delete(key);
     }
+  }
+  async del(key) {
+    this.clearTimer(key);
     this.store.delete(key);
+    this.sets.delete(key);
   }
   async has(key) {
-    return this.store.has(key);
+    return this.store.has(key) || this.sets.has(key);
+  }
+  async clear(prefix = "") {
+    for (const key of [...this.store.keys(), ...this.sets.keys()]) {
+      if (key.startsWith(prefix)) await this.del(key);
+    }
+  }
+  async sadd(key, member, ttl) {
+    const seconds = checkTtl(ttl);
+    const now = Date.now();
+    const expiresAt = seconds === void 0 ? Infinity : now + seconds * 1e3;
+    let set = this.sets.get(key);
+    if (!set) {
+      this.store.delete(key);
+      set = { members: /* @__PURE__ */ new Map(), expiresAt: 0, pruneAt: 64 };
+      this.sets.set(key, set);
+    }
+    set.members.set(member, Math.max(set.members.get(member) ?? 0, expiresAt));
+    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) {
+    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);
   }
 };
 
@@ -58,66 +120,202 @@ function decode(raw) {
     return raw;
   }
 }
+function ttlArgs(ttl) {
+  return Number.isInteger(ttl) ? ["EX", ttl] : ["PX", Math.max(1, Math.round(ttl * 1e3))];
+}
+var escapeGlob = (prefix) => prefix.replace(/[*?[\]\\]/g, "\\$&");
+var CLEAR_BATCH = 1e3;
+var 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
+`;
+var 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
+`;
+function withoutCommandArgs(error) {
+  const command = error?.command;
+  if (command && typeof command === "object" && "args" in command) {
+    error.command = { name: command.name };
+  }
+  return error;
+}
 var RedisAdapter = class {
   id = "redis";
   client = null;
   options;
-  constructor(options) {
+  hooks;
+  constructor(options, hooks = {}) {
     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() {
+    let client;
+    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) => this.hooks.onError?.(withoutCommandArgs(error)));
+    try {
+      await client.connect();
+    } catch (error) {
+      client.disconnect();
+      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. */
+  quitTimeoutMs = 2e3;
+  /**
+   * 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;
+    const timedOut = new Promise((resolve) => {
+      timer = setTimeout(() => resolve("timeout"), this.quitTimeoutMs);
+    });
+    const outcome = await Promise.race([
+      client.quit().then(
+        () => "quit",
+        () => "error"
+      ),
+      timedOut
+    ]);
+    clearTimeout(timer);
+    if (outcome !== "quit") client.disconnect();
+  }
+  /** The ioredis client once connected (null before connect() and after disconnect()). */
+  get nativeClient() {
+    return this.client;
+  }
+  /** The live client; operations before connect() fail instead of silently doing nothing. */
+  get redis() {
+    if (!this.client) throw new Error("RedisAdapter is not connected; call connect() first");
+    return this.client;
   }
   async get(key) {
-    const val = await this.client?.get(key);
+    const val = await this.redis.get(key);
     if (val === null || val === void 0) return void 0;
     return decode(val);
   }
   async set(key, value, ttl) {
     const val = encode(value);
-    if (ttl) {
-      await this.client?.set(key, val, "EX", ttl);
+    const seconds = checkTtl(ttl);
+    if (seconds !== void 0) {
+      await this.redis.set(key, val, ...ttlArgs(seconds));
     } else {
-      await this.client?.set(key, val);
+      await this.redis.set(key, val);
     }
   }
   async del(key) {
-    await this.client?.del(key);
+    await this.redis.del(key);
   }
   async has(key) {
-    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(keys) {
     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 === void 0 ? void 0 : decode(raw);
     });
   }
   async mset(entries, ttl) {
+    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 !== void 0) {
+        pipeline.set(key, val, ...ttlArgs(seconds));
       } else {
         pipeline.set(key, val);
       }
     }
-    await pipeline.exec();
+    const results = await pipeline.exec();
+    const failed = results?.find(([err]) => err);
+    if (failed) throw failed[0];
   }
   async mdel(keys) {
     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 = "") {
+    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;
+      if (keys.length > 0) await redis.del(...keys.map((key) => key.slice(keyPrefix.length)));
+    } while (cursor !== "0");
+  }
+  async sadd(key, member, ttl) {
+    const seconds = checkTtl(ttl);
+    const ms = seconds === void 0 ? "" : String(Math.max(1, Math.ceil(seconds * 1e3)));
+    await this.redis.eval(SADD_SCRIPT, 1, key, member, ms);
+  }
+  async sdrain(key) {
+    return await this.redis.eval(SDRAIN_SCRIPT, 1, key);
   }
 };
 
@@ -128,19 +326,38 @@ var KVManager = class {
   app = null;
   adapter;
   prefix;
+  flushDb;
   constructor(options = {}) {
+    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 } })`
+      );
+    }
     this.adapter = new MemoryAdapter();
     this.prefix = options.namespace ? `${options.namespace}:` : "";
+    this.flushDb = options.flushDb ?? false;
   }
   init(app) {
     this.app = app;
+    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 {
+      throw new Error(`Unsupported KV driver "${config.driver}" (supported: "memory", "redis")`);
     }
   }
   async connect() {
@@ -157,6 +374,15 @@ var KVManager = class {
   async stop() {
     await this.disconnect();
   }
+  /**
+   * 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() {
+    return this.adapter instanceof RedisAdapter ? this.adapter.nativeClient ?? void 0 : void 0;
+  }
   prefixed(key) {
     return `${this.prefix}${key}`;
   }
@@ -187,9 +413,7 @@ var KVManager = class {
   }
   async mset(entries, ttl) {
     const pairs = Array.isArray(entries) ? entries : Object.entries(entries);
-    const prefixed = pairs.map(
-      ([k, v]) => [this.prefixed(k), v]
-    );
+    const prefixed = pairs.map(([k, v]) => [this.prefixed(k), v]);
     if (this.adapter.mset) {
       await this.adapter.mset(prefixed, ttl);
       return;
@@ -204,7 +428,28 @@ var KVManager = class {
     }
     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 = "") {
+    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, member, ttl) {
+    if (!this.adapter.sadd) throw unsupported(this.adapter, "sadd");
+    await this.adapter.sadd(this.prefixed(key), member, ttl);
+  }
+  async sdrain(key) {
+    if (!this.adapter.sdrain) throw unsupported(this.adapter, "sdrain");
+    return this.adapter.sdrain(this.prefixed(key));
+  }
 };
+function unsupported(adapter, method) {
+  return new Error(`The "${adapter.id}" KV adapter does not support ${method}()`);
+}
 export {
   KVManager
 };