@tekir/redis 0.1.0 → 0.1.2

package/dist/manager.d.ts

@@ -106,12 +106,18 @@ export declare class RedisManager {
     unsubscribe(channel?: string): Promise<void>;
     /** @see {@link Redis.send} */
     send(command: string, args?: string[]): Promise<any>;
+    /** @see {@link Redis.keyName} */
+    keyName(key: string): string;
     /** @see {@link Redis.getJSON} */
     getJSON<T = any>(key: string): Promise<T | null>;
+    /** @see {@link Redis.setEx} */
+    setEx(key: string, value: string | number, seconds: number): Promise<void>;
     /** @see {@link Redis.setJSON} */
     setJSON(key: string, value: any, expireSeconds?: number): Promise<void>;
     /** @see {@link Redis.remember} */
     remember<T>(key: string, seconds: number, callback: () => Promise<T>): Promise<T>;
+    /** @see {@link Redis.clearPrefix} */
+    clearPrefix(): Promise<number>;
     /** @see {@link Redis.flushdb} */
     flushdb(): Promise<void>;
     /** @see {@link Redis.connected} */

package/dist/manager.js

@@ -138,12 +138,18 @@ export class RedisManager {
     unsubscribe(channel) { return this.connection().unsubscribe(channel); }
     /** @see {@link Redis.send} */
     send(command, args = []) { return this.connection().send(command, args); }
+    /** @see {@link Redis.keyName} */
+    keyName(key) { return this.connection().keyName(key); }
     /** @see {@link Redis.getJSON} */
     getJSON(key) { return this.connection().getJSON(key); }
+    /** @see {@link Redis.setEx} */
+    setEx(key, value, seconds) { return this.connection().setEx(key, value, seconds); }
     /** @see {@link Redis.setJSON} */
     setJSON(key, value, expireSeconds) { return this.connection().setJSON(key, value, expireSeconds); }
     /** @see {@link Redis.remember} */
     remember(key, seconds, callback) { return this.connection().remember(key, seconds, callback); }
+    /** @see {@link Redis.clearPrefix} */
+    clearPrefix() { return this.connection().clearPrefix(); }
     /** @see {@link Redis.flushdb} */
     flushdb() { return this.connection().flushdb(); }
     /** @see {@link Redis.connected} */

package/dist/redis.d.ts

@@ -21,6 +21,15 @@ export declare class Redis {
      */
     constructor(config?: RedisConnectionConfig);
     private key;
+    /** Resolve the actual Redis key after applying this connection's namespace. */
+    keyName(key: string): string;
+    /**
+     * Strip any credentials embedded in a Redis URL so it is safe to log.
+     *
+     * @param url - The connection URL, possibly containing `user:pass@host`.
+     * @returns The URL with the userinfo component masked.
+     */
+    private static maskUrl;
     /**
      * Open the connection to the Redis server.
      *
@@ -66,6 +75,8 @@ export declare class Redis {
      * ```
      */
     set(key: string, value: string | number): Promise<void>;
+    /** Atomically set a value and its expiration time. */
+    setEx(key: string, value: string | number, seconds: number): Promise<void>;
     /**
      * Delete one or more keys.
      *
@@ -185,6 +196,11 @@ export declare class Redis {
     /**
      * Subscribe to a channel and receive messages via a callback.
      *
+     * The message passed to the callback is the raw string received from Redis and
+     * is NOT deserialized by this wrapper. Treat it as untrusted input: validate
+     * it and never `eval` it. If you `JSON.parse` it, wrap the parse in a
+     * try/catch to guard against poisoned payloads.
+     *
      * @param channel - The channel name to subscribe to.
      * @param callback - Invoked for each message received on the channel.
      *
@@ -203,10 +219,16 @@ export declare class Redis {
      */
     unsubscribe(channel?: string): Promise<void>;
     /**
-     * Send a raw Redis command.
+     * Send a raw Redis command. ADVANCED / INTERNAL escape hatch.
+     *
+     * This bypasses the key prefix and every higher-level safeguard. The `command`
+     * and `args` are passed straight to Redis, so they MUST be trusted, statically
+     * known values. Never build a command name or its arguments from user input:
+     * doing so allows execution of dangerous commands (`FLUSHALL`, `CONFIG`,
+     * `EVAL`, `KEYS *`, ...) and lets callers escape the prefix namespace.
      *
-     * @param command - The Redis command string (e.g. `'PING'`, `'INFO'`).
-     * @param args - Arguments for the command.
+     * @param command - A trusted, statically-known Redis command (e.g. `'PING'`, `'INFO'`).
+     * @param args - Arguments for the command. Must not contain untrusted input.
      * @returns The raw response from Redis.
      *
      * @example
@@ -249,6 +271,11 @@ export declare class Redis {
      * @param callback - Async function invoked to compute the value on a cache miss.
      * @returns The cached or freshly computed value.
      *
+     * On a cache miss this acquires a short-lived `SET NX` lock so that, under
+     * concurrent misses, only one caller runs `callback()` while the others wait
+     * for the freshly-populated value. This protects the backend from a stampede
+     * (thundering herd) when a hot key expires.
+     *
      * @example
      * ```ts
      * const users = await redis.remember('all-users', 60, async () => {
@@ -258,7 +285,24 @@ export declare class Redis {
      */
     remember<T>(key: string, seconds: number, callback: () => Promise<T>): Promise<T>;
     /**
-     * Delete all keys in the currently selected database.
+     * Delete every key under this connection's prefix using a non-blocking SCAN.
+     *
+     * Unlike {@link Redis.flushdb}, this is scoped: it only removes keys that
+     * belong to this logical store (`<prefix>:*`), leaving other stores that
+     * share the same Redis database (sessions, queues, ...) untouched. If no
+     * prefix is configured this deletes nothing and returns `0`, to avoid
+     * accidentally wiping the whole database.
+     *
+     * @returns The number of keys deleted.
+     */
+    clearPrefix(): Promise<number>;
+    /**
+     * Delete ALL keys in the currently selected database. DANGEROUS.
+     *
+     * This ignores the key prefix and removes every key in the database, including
+     * data owned by other logical stores (sessions, queues, other caches) that
+     * share the same Redis database. Prefer {@link Redis.clearPrefix} to delete
+     * only this store's keys. Never expose this to user-triggered code paths.
      *
      * @returns A promise that resolves once the database has been flushed.
      */

package/dist/redis.js

@@ -20,9 +20,17 @@ export class Redis {
      */
     constructor(config = {}) {
         this.config = config;
-        this.prefix = config.prefix || '';
+        this.prefix = (config.prefix || '').replace(/:+$/, '');
         const { RedisClient } = Bun;
         const url = config.url || process.env.REDIS_URL || 'redis://localhost:6379';
+        // Encourage TLS in production: a plaintext redis:// connection exposes
+        // credentials and data to network observers. Warn once instead of throwing
+        // to stay backward compatible with local/dev setups.
+        const isTls = config.tls != null || url.startsWith('rediss://');
+        if (!isTls && process.env.NODE_ENV === 'production') {
+            console.warn(`[@tekir/redis] Connecting to ${Redis.maskUrl(url)} without TLS in production. ` +
+                `Use a rediss:// URL or set tls to encrypt credentials and data in transit.`);
+        }
         this.client = new RedisClient(url, {
             connectionTimeout: config.connectionTimeout,
             idleTimeout: config.idleTimeout,
@@ -35,6 +43,17 @@ export class Redis {
     key(k) {
         return this.prefix ? `${this.prefix}:${k}` : k;
     }
+    /** Resolve the actual Redis key after applying this connection's namespace. */
+    keyName(key) { return this.key(key); }
+    /**
+     * Strip any credentials embedded in a Redis URL so it is safe to log.
+     *
+     * @param url - The connection URL, possibly containing `user:pass@host`.
+     * @returns The URL with the userinfo component masked.
+     */
+    static maskUrl(url) {
+        return url.replace(/(\w+:\/\/)([^@/]+)@/, '$1***@');
+    }
     // ─── Connection ────────────────────────────────────────
     /**
      * Open the connection to the Redis server.
@@ -82,6 +101,12 @@ export class Redis {
      * ```
      */
     async set(key, value) { await this.client.set(this.key(key), String(value)); }
+    /** Atomically set a value and its expiration time. */
+    async setEx(key, value, seconds) {
+        if (!Number.isFinite(seconds) || seconds <= 0)
+            throw new Error('Redis setEx seconds must be a positive number');
+        await this.client.send('SET', [this.key(key), String(value), 'EX', String(Math.floor(seconds))]);
+    }
     /**
      * Delete one or more keys.
      *
@@ -204,6 +229,11 @@ export class Redis {
     /**
      * Subscribe to a channel and receive messages via a callback.
      *
+     * The message passed to the callback is the raw string received from Redis and
+     * is NOT deserialized by this wrapper. Treat it as untrusted input: validate
+     * it and never `eval` it. If you `JSON.parse` it, wrap the parse in a
+     * try/catch to guard against poisoned payloads.
+     *
      * @param channel - The channel name to subscribe to.
      * @param callback - Invoked for each message received on the channel.
      *
@@ -225,10 +255,16 @@ export class Redis {
     async unsubscribe(channel) { await this.client.unsubscribe(channel); }
     // ─── Raw command ──────────────────────────────────────
     /**
-     * Send a raw Redis command.
+     * Send a raw Redis command. ADVANCED / INTERNAL escape hatch.
+     *
+     * This bypasses the key prefix and every higher-level safeguard. The `command`
+     * and `args` are passed straight to Redis, so they MUST be trusted, statically
+     * known values. Never build a command name or its arguments from user input:
+     * doing so allows execution of dangerous commands (`FLUSHALL`, `CONFIG`,
+     * `EVAL`, `KEYS *`, ...) and lets callers escape the prefix namespace.
      *
-     * @param command - The Redis command string (e.g. `'PING'`, `'INFO'`).
-     * @param args - Arguments for the command.
+     * @param command - A trusted, statically-known Redis command (e.g. `'PING'`, `'INFO'`).
+     * @param args - Arguments for the command. Must not contain untrusted input.
      * @returns The raw response from Redis.
      *
      * @example
@@ -256,7 +292,11 @@ export class Redis {
         try {
             return JSON.parse(val);
         }
-        catch {
+        catch (e) {
+            // Surface corrupt/poisoned payloads instead of silently masking them as a
+            // cache miss. Returning null still preserves the previous behaviour for
+            // callers, but the warning makes the problem diagnosable.
+            console.warn(`[@tekir/redis] Failed to parse JSON for key "${key}": ${e.message}`);
             return null;
         }
     }
@@ -273,9 +313,17 @@ export class Redis {
      * ```
      */
     async setJSON(key, value, expireSeconds) {
-        await this.set(key, JSON.stringify(value));
-        if (expireSeconds)
-            await this.expire(key, expireSeconds);
+        const payload = JSON.stringify(value);
+        if (payload === undefined)
+            throw new Error(`Redis cannot serialize undefined for key "${key}"`);
+        if (expireSeconds && expireSeconds > 0) {
+            // Atomic SET ... EX so a crash between writing the value and setting the
+            // TTL can never leave a permanent (TTL-less) key behind.
+            await this.client.send('SET', [this.key(key), payload, 'EX', String(Math.floor(expireSeconds))]);
+        }
+        else {
+            await this.client.set(this.key(key), payload);
+        }
     }
     /**
      * Cache-aside helper: return the cached value if it exists, otherwise execute
@@ -286,6 +334,11 @@ export class Redis {
      * @param callback - Async function invoked to compute the value on a cache miss.
      * @returns The cached or freshly computed value.
      *
+     * On a cache miss this acquires a short-lived `SET NX` lock so that, under
+     * concurrent misses, only one caller runs `callback()` while the others wait
+     * for the freshly-populated value. This protects the backend from a stampede
+     * (thundering herd) when a hot key expires.
+     *
      * @example
      * ```ts
      * const users = await redis.remember('all-users', 60, async () => {
@@ -297,12 +350,93 @@ export class Redis {
         const cached = await this.getJSON(key);
         if (cached !== null)
             return cached;
-        const value = await callback();
-        await this.setJSON(key, value, seconds);
-        return value;
+        const lockKey = this.key(`${key}:__lock`);
+        const lockToken = crypto.randomUUID();
+        // Try to become the single flight that computes the value. SET NX EX gives
+        // a self-expiring lock so a crashed holder cannot deadlock other callers.
+        const acquired = await this.client.send('SET', [lockKey, lockToken, 'NX', 'EX', '10']);
+        if (acquired == null) {
+            // Another caller is computing it. Wait for the populated value, but do
+            // not run the callback without owning the lock: doing so would turn slow
+            // cache fills back into a stampede. A bounded timeout keeps callers from
+            // hanging forever if Redis itself is unhealthy.
+            for (let i = 0; i < 300; i++) {
+                await new Promise(r => setTimeout(r, 100));
+                const waited = await this.getJSON(key);
+                if (waited !== null)
+                    return waited;
+            }
+            throw new Error(`Redis remember timed out waiting for lock on "${key}"`);
+        }
+        const renewScript = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('EXPIRE', KEYS[1], 10)
+end
+return 0
+`;
+        const renewTimer = setInterval(() => {
+            void this.client.send('EVAL', [renewScript, '1', lockKey, lockToken]).catch(() => { });
+        }, 3000);
+        renewTimer.unref?.();
+        try {
+            // Re-check after acquiring the lock: a racing holder may have populated it.
+            const fresh = await this.getJSON(key);
+            if (fresh !== null)
+                return fresh;
+            const value = await callback();
+            await this.setJSON(key, value, seconds);
+            return value;
+        }
+        finally {
+            clearInterval(renewTimer);
+            // Only the owner may release the lock. A plain DEL lets a slow callback
+            // delete a successor's lock after its own 10s lease expired, reopening
+            // the stampede window. Waiters that never acquired it release nothing.
+            if (acquired != null) {
+                const releaseScript = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+`;
+                await this.client.send('EVAL', [releaseScript, '1', lockKey, lockToken]).catch(() => { });
+            }
+        }
+    }
+    /**
+     * Delete every key under this connection's prefix using a non-blocking SCAN.
+     *
+     * Unlike {@link Redis.flushdb}, this is scoped: it only removes keys that
+     * belong to this logical store (`<prefix>:*`), leaving other stores that
+     * share the same Redis database (sessions, queues, ...) untouched. If no
+     * prefix is configured this deletes nothing and returns `0`, to avoid
+     * accidentally wiping the whole database.
+     *
+     * @returns The number of keys deleted.
+     */
+    async clearPrefix() {
+        if (!this.prefix)
+            return 0;
+        const pattern = `${this.prefix}:*`;
+        let cursor = '0';
+        let deleted = 0;
+        do {
+            const [next, batch] = await this.client.send('SCAN', [cursor, 'MATCH', pattern, 'COUNT', '100']);
+            cursor = next;
+            if (batch.length) {
+                await this.client.send('DEL', batch);
+                deleted += batch.length;
+            }
+        } while (cursor !== '0');
+        return deleted;
     }
     /**
-     * Delete all keys in the currently selected database.
+     * Delete ALL keys in the currently selected database. DANGEROUS.
+     *
+     * This ignores the key prefix and removes every key in the database, including
+     * data owned by other logical stores (sessions, queues, other caches) that
+     * share the same Redis database. Prefer {@link Redis.clearPrefix} to delete
+     * only this store's keys. Never expose this to user-triggered code paths.
      *
      * @returns A promise that resolves once the database has been flushed.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekir/redis",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Redis connection and client management",
   "author": "dev@tekir.io",
   "license": "MIT",
@@ -39,7 +39,7 @@
     }
   },
   "dependencies": {
-    "@tekir/core": "^0.1.0"
+    "@tekir/core": "^0.1.35"
   },
   "scripts": {
     "build": "rm -rf dist && tsc --noEmit false",

package/src/manager.ts

@@ -146,12 +146,18 @@ export class RedisManager {
   unsubscribe(channel?: string) { return this.connection().unsubscribe(channel) }
   /** @see {@link Redis.send} */
   send(command: string, args: string[] = []) { return this.connection().send(command, args) }
+  /** @see {@link Redis.keyName} */
+  keyName(key: string) { return this.connection().keyName(key) }
   /** @see {@link Redis.getJSON} */
   getJSON<T = any>(key: string) { return this.connection().getJSON<T>(key) }
+  /** @see {@link Redis.setEx} */
+  setEx(key: string, value: string | number, seconds: number) { return this.connection().setEx(key, value, seconds) }
   /** @see {@link Redis.setJSON} */
   setJSON(key: string, value: any, expireSeconds?: number) { return this.connection().setJSON(key, value, expireSeconds) }
   /** @see {@link Redis.remember} */
   remember<T>(key: string, seconds: number, callback: () => Promise<T>) { return this.connection().remember<T>(key, seconds, callback) }
+  /** @see {@link Redis.clearPrefix} */
+  clearPrefix() { return this.connection().clearPrefix() }
   /** @see {@link Redis.flushdb} */
   flushdb() { return this.connection().flushdb() }
   /** @see {@link Redis.connected} */

package/src/redis.ts

@@ -23,11 +23,22 @@ export class Redis {
    */
   constructor(config: RedisConnectionConfig = {}) {
     this.config = config
-    this.prefix = config.prefix || ''
+    this.prefix = (config.prefix || '').replace(/:+$/, '')
 
     const { RedisClient } = Bun as any
     const url = config.url || process.env.REDIS_URL || 'redis://localhost:6379'
 
+    // Encourage TLS in production: a plaintext redis:// connection exposes
+    // credentials and data to network observers. Warn once instead of throwing
+    // to stay backward compatible with local/dev setups.
+    const isTls = config.tls != null || url.startsWith('rediss://')
+    if (!isTls && process.env.NODE_ENV === 'production') {
+      console.warn(
+        `[@tekir/redis] Connecting to ${Redis.maskUrl(url)} without TLS in production. ` +
+        `Use a rediss:// URL or set tls to encrypt credentials and data in transit.`
+      )
+    }
+
     this.client = new RedisClient(url, {
       connectionTimeout: config.connectionTimeout,
       idleTimeout: config.idleTimeout,
@@ -42,6 +53,19 @@ export class Redis {
     return this.prefix ? `${this.prefix}:${k}` : k
   }
 
+  /** Resolve the actual Redis key after applying this connection's namespace. */
+  keyName(key: string): string { return this.key(key) }
+
+  /**
+   * Strip any credentials embedded in a Redis URL so it is safe to log.
+   *
+   * @param url - The connection URL, possibly containing `user:pass@host`.
+   * @returns The URL with the userinfo component masked.
+   */
+  private static maskUrl(url: string): string {
+    return url.replace(/(\w+:\/\/)([^@/]+)@/, '$1***@')
+  }
+
   // ─── Connection ────────────────────────────────────────
 
   /**
@@ -96,6 +120,12 @@ export class Redis {
    */
   async set(key: string, value: string | number): Promise<void> { await this.client.set(this.key(key), String(value)) }
 
+  /** Atomically set a value and its expiration time. */
+  async setEx(key: string, value: string | number, seconds: number): Promise<void> {
+    if (!Number.isFinite(seconds) || seconds <= 0) throw new Error('Redis setEx seconds must be a positive number')
+    await this.client.send('SET', [this.key(key), String(value), 'EX', String(Math.floor(seconds))])
+  }
+
   /**
    * Delete one or more keys.
    *
@@ -236,6 +266,11 @@ export class Redis {
   /**
    * Subscribe to a channel and receive messages via a callback.
    *
+   * The message passed to the callback is the raw string received from Redis and
+   * is NOT deserialized by this wrapper. Treat it as untrusted input: validate
+   * it and never `eval` it. If you `JSON.parse` it, wrap the parse in a
+   * try/catch to guard against poisoned payloads.
+   *
    * @param channel - The channel name to subscribe to.
    * @param callback - Invoked for each message received on the channel.
    *
@@ -260,10 +295,16 @@ export class Redis {
   // ─── Raw command ──────────────────────────────────────
 
   /**
-   * Send a raw Redis command.
+   * Send a raw Redis command. ADVANCED / INTERNAL escape hatch.
    *
-   * @param command - The Redis command string (e.g. `'PING'`, `'INFO'`).
-   * @param args - Arguments for the command.
+   * This bypasses the key prefix and every higher-level safeguard. The `command`
+   * and `args` are passed straight to Redis, so they MUST be trusted, statically
+   * known values. Never build a command name or its arguments from user input:
+   * doing so allows execution of dangerous commands (`FLUSHALL`, `CONFIG`,
+   * `EVAL`, `KEYS *`, ...) and lets callers escape the prefix namespace.
+   *
+   * @param command - A trusted, statically-known Redis command (e.g. `'PING'`, `'INFO'`).
+   * @param args - Arguments for the command. Must not contain untrusted input.
    * @returns The raw response from Redis.
    *
    * @example
@@ -289,7 +330,15 @@ export class Redis {
   async getJSON<T = any>(key: string): Promise<T | null> {
     const val = await this.get(key)
     if (val === null) return null
-    try { return JSON.parse(val) } catch { return null }
+    try {
+      return JSON.parse(val)
+    } catch (e) {
+      // Surface corrupt/poisoned payloads instead of silently masking them as a
+      // cache miss. Returning null still preserves the previous behaviour for
+      // callers, but the warning makes the problem diagnosable.
+      console.warn(`[@tekir/redis] Failed to parse JSON for key "${key}": ${(e as Error).message}`)
+      return null
+    }
   }
 
   /**
@@ -305,8 +354,15 @@ export class Redis {
    * ```
    */
   async setJSON(key: string, value: any, expireSeconds?: number): Promise<void> {
-    await this.set(key, JSON.stringify(value))
-    if (expireSeconds) await this.expire(key, expireSeconds)
+    const payload = JSON.stringify(value)
+    if (payload === undefined) throw new Error(`Redis cannot serialize undefined for key "${key}"`)
+    if (expireSeconds && expireSeconds > 0) {
+      // Atomic SET ... EX so a crash between writing the value and setting the
+      // TTL can never leave a permanent (TTL-less) key behind.
+      await this.client.send('SET', [this.key(key), payload, 'EX', String(Math.floor(expireSeconds))])
+    } else {
+      await this.client.set(this.key(key), payload)
+    }
   }
 
   /**
@@ -318,6 +374,11 @@ export class Redis {
    * @param callback - Async function invoked to compute the value on a cache miss.
    * @returns The cached or freshly computed value.
    *
+   * On a cache miss this acquires a short-lived `SET NX` lock so that, under
+   * concurrent misses, only one caller runs `callback()` while the others wait
+   * for the freshly-populated value. This protects the backend from a stampede
+   * (thundering herd) when a hot key expires.
+   *
    * @example
    * ```ts
    * const users = await redis.remember('all-users', 60, async () => {
@@ -328,13 +389,95 @@ export class Redis {
   async remember<T>(key: string, seconds: number, callback: () => Promise<T>): Promise<T> {
     const cached = await this.getJSON<T>(key)
     if (cached !== null) return cached
-    const value = await callback()
-    await this.setJSON(key, value, seconds)
-    return value
+
+    const lockKey = this.key(`${key}:__lock`)
+    const lockToken = crypto.randomUUID()
+    // Try to become the single flight that computes the value. SET NX EX gives
+    // a self-expiring lock so a crashed holder cannot deadlock other callers.
+    const acquired = await this.client.send('SET', [lockKey, lockToken, 'NX', 'EX', '10'])
+
+    if (acquired == null) {
+      // Another caller is computing it. Wait for the populated value, but do
+      // not run the callback without owning the lock: doing so would turn slow
+      // cache fills back into a stampede. A bounded timeout keeps callers from
+      // hanging forever if Redis itself is unhealthy.
+      for (let i = 0; i < 300; i++) {
+        await new Promise(r => setTimeout(r, 100))
+        const waited = await this.getJSON<T>(key)
+        if (waited !== null) return waited
+      }
+      throw new Error(`Redis remember timed out waiting for lock on "${key}"`)
+    }
+
+    const renewScript = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('EXPIRE', KEYS[1], 10)
+end
+return 0
+`
+    const renewTimer = setInterval(() => {
+      void this.client.send('EVAL', [renewScript, '1', lockKey, lockToken]).catch(() => {})
+    }, 3000)
+    ;(renewTimer as any).unref?.()
+
+    try {
+      // Re-check after acquiring the lock: a racing holder may have populated it.
+      const fresh = await this.getJSON<T>(key)
+      if (fresh !== null) return fresh
+      const value = await callback()
+      await this.setJSON(key, value, seconds)
+      return value
+    } finally {
+      clearInterval(renewTimer)
+      // Only the owner may release the lock. A plain DEL lets a slow callback
+      // delete a successor's lock after its own 10s lease expired, reopening
+      // the stampede window. Waiters that never acquired it release nothing.
+      if (acquired != null) {
+        const releaseScript = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+`
+        await this.client.send('EVAL', [releaseScript, '1', lockKey, lockToken]).catch(() => {})
+      }
+    }
+  }
+
+  /**
+   * Delete every key under this connection's prefix using a non-blocking SCAN.
+   *
+   * Unlike {@link Redis.flushdb}, this is scoped: it only removes keys that
+   * belong to this logical store (`<prefix>:*`), leaving other stores that
+   * share the same Redis database (sessions, queues, ...) untouched. If no
+   * prefix is configured this deletes nothing and returns `0`, to avoid
+   * accidentally wiping the whole database.
+   *
+   * @returns The number of keys deleted.
+   */
+  async clearPrefix(): Promise<number> {
+    if (!this.prefix) return 0
+    const pattern = `${this.prefix}:*`
+    let cursor = '0'
+    let deleted = 0
+    do {
+      const [next, batch]: [string, string[]] = await this.client.send('SCAN', [cursor, 'MATCH', pattern, 'COUNT', '100'])
+      cursor = next
+      if (batch.length) {
+        await this.client.send('DEL', batch)
+        deleted += batch.length
+      }
+    } while (cursor !== '0')
+    return deleted
   }
 
   /**
-   * Delete all keys in the currently selected database.
+   * Delete ALL keys in the currently selected database. DANGEROUS.
+   *
+   * This ignores the key prefix and removes every key in the database, including
+   * data owned by other logical stores (sessions, queues, other caches) that
+   * share the same Redis database. Prefer {@link Redis.clearPrefix} to delete
+   * only this store's keys. Never expose this to user-triggered code paths.
    *
    * @returns A promise that resolves once the database has been flushed.
    */