@tekir/redis 0.1.0 → 0.1.1

package/dist/manager.d.ts

@@ -112,6 +112,8 @@ export declare class RedisManager {
     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

@@ -144,6 +144,8 @@ export class RedisManager {
     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,13 @@ export declare class Redis {
      */
     constructor(config?: RedisConnectionConfig);
     private 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;
     /**
      * Open the connection to the Redis server.
      *
@@ -185,6 +192,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 +215,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 +267,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 +281,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

@@ -23,6 +23,14 @@ export class Redis {
         this.prefix = config.prefix || '';
         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,15 @@ export class Redis {
     key(k) {
         return this.prefix ? `${this.prefix}:${k}` : k;
     }
+    /**
+     * 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.
@@ -204,6 +221,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 +247,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 +284,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 +305,15 @@ 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 (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 +324,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 +340,67 @@ 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`);
+        // 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, '1', 'NX', 'EX', '10']);
+        if (acquired == null) {
+            // Another caller is computing it. Briefly poll for the populated value
+            // before falling back to computing it ourselves (lock may have expired).
+            for (let i = 0; i < 50; i++) {
+                await new Promise(r => setTimeout(r, 100));
+                const waited = await this.getJSON(key);
+                if (waited !== null)
+                    return waited;
+            }
+        }
+        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 {
+            await this.del(`${key}:__lock`).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.1",
   "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.34"
   },
   "scripts": {
     "build": "rm -rf dist && tsc --noEmit false",

package/src/manager.ts

@@ -152,6 +152,8 @@ export class RedisManager {
   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

@@ -28,6 +28,17 @@ export class Redis {
     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,16 @@ export class Redis {
     return this.prefix ? `${this.prefix}:${k}` : k
   }
 
+  /**
+   * 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 ────────────────────────────────────────
 
   /**
@@ -236,6 +257,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 +286,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 +321,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 +345,14 @@ 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 (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 +364,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 +379,68 @@ 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`)
+    // 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, '1', 'NX', 'EX', '10'])
+
+    if (acquired == null) {
+      // Another caller is computing it. Briefly poll for the populated value
+      // before falling back to computing it ourselves (lock may have expired).
+      for (let i = 0; i < 50; i++) {
+        await new Promise(r => setTimeout(r, 100))
+        const waited = await this.getJSON<T>(key)
+        if (waited !== null) return waited
+      }
+    }
+
+    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 {
+      await this.del(`${key}:__lock`).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.
    */