@tekir/cache 0.1.7 → 0.1.9

package/dist/cache.d.ts

@@ -15,6 +15,7 @@ export declare class Cache {
     private stores;
     private defaultStore;
     private defaultTtl;
+    private inFlight;
     /**
      * Create a new Cache instance.
      *
@@ -76,6 +77,10 @@ export declare class Cache {
      * @param factory - An async function that produces the value when not cached.
      * @returns The cached or freshly-computed value.
      *
+     * Concurrent misses for the same key share a single `factory()` execution
+     * (single-flight) so a popular key expiring does not trigger a stampede
+     * (thundering herd) against the backend.
+     *
      * @example
      * ```ts
      * const users = await cache.getOrSet('users', 300, () => db.query('SELECT * FROM users'))

package/dist/cache.js

@@ -15,6 +15,9 @@ export class Cache {
     stores;
     defaultStore;
     defaultTtl;
+    // In-flight factory promises keyed by `<store>:<key>` for single-flight
+    // stampede protection in getOrSet.
+    inFlight = new Map();
     /**
      * Create a new Cache instance.
      *
@@ -86,6 +89,10 @@ export class Cache {
      * @param factory - An async function that produces the value when not cached.
      * @returns The cached or freshly-computed value.
      *
+     * Concurrent misses for the same key share a single `factory()` execution
+     * (single-flight) so a popular key expiring does not trigger a stampede
+     * (thundering herd) against the backend.
+     *
      * @example
      * ```ts
      * const users = await cache.getOrSet('users', 300, () => db.query('SELECT * FROM users'))
@@ -95,9 +102,17 @@ export class Cache {
         const cached = await this.get(key);
         if (cached !== null)
             return cached;
-        const value = await factory();
-        await this.set(key, value, ttl);
-        return value;
+        const flightKey = `${this.defaultStore}:${key}`;
+        const existing = this.inFlight.get(flightKey);
+        if (existing)
+            return existing;
+        const promise = (async () => {
+            const value = await factory();
+            await this.set(key, value, ttl);
+            return value;
+        })().finally(() => this.inFlight.delete(flightKey));
+        this.inFlight.set(flightKey, promise);
+        return promise;
     }
     /**
      * Get a value and immediately delete it from the cache (atomic get-and-remove).
@@ -112,7 +127,10 @@ export class Cache {
      */
     async pull(key) {
         const value = await this.get(key);
-        if (value !== null)
+        // Use has() rather than a null-check so that an explicitly cached `null`
+        // value is still evicted (get() alone cannot distinguish "absent" from
+        // "stored null").
+        if (value !== null || (await this.has(key)))
             await this.delete(key);
         return value;
     }

package/dist/http-cache.d.ts

@@ -59,6 +59,25 @@ export type HttpCacheOptions = {
      * responses. Default: true.
      */
     setCacheControl?: boolean;
+    /**
+     * How to handle requests that carry credentials (`Authorization` or `Cookie`).
+     *
+     * Caching a per-user response under a shared key leaks one user's response to
+     * another. To prevent that, the default behaviour is `'bypass'`: authenticated
+     * requests skip the cache entirely unless you opt in.
+     *
+     * - `'bypass'` (default): never read or write the cache for credentialed
+     *   requests.
+     * - `'vary'`: include the credential headers in the cache key so each
+     *   identity gets its own entry. Use this only when you understand the cache
+     *   size implications.
+     * - `'allow'`: cache credentialed requests under the same key as anonymous
+     *   ones. DANGEROUS: only safe when the response is identical for every user.
+     *
+     * Note: providing a custom `key` builder that already incorporates identity
+     * overrides this and is always honoured.
+     */
+    authenticated?: "bypass" | "vary" | "allow";
 };
 export type HttpCacheCtx = {
     request: {

package/dist/http-cache.js

@@ -23,6 +23,8 @@
  * ```
  */
 import { Cache } from "./cache";
+/** Request headers that indicate a credentialed/per-user request. */
+const CREDENTIAL_HEADERS = ["authorization", "cookie"];
 const SAFE_METHODS = ["GET", "HEAD"];
 const isStore = (s) => !!s &&
     typeof s.get === "function" &&
@@ -101,12 +103,25 @@ const entryToResponse = (e, opts) => {
     headers["x-tekir-cache"] = "HIT";
     return new Response(e.body, { status: e.status, headers });
 };
+/** True if the request carries an Authorization or Cookie header. */
+const hasCredentials = (req) => {
+    for (const h of CREDENTIAL_HEADERS) {
+        if (req.headers?.get?.(h))
+            return true;
+    }
+    return false;
+};
 export function cache(opts = {}) {
     const ttl = opts.ttl ?? 60;
     const methods = new Set((opts.methods ?? SAFE_METHODS).map((m) => m.toUpperCase()));
     const vary = opts.vary ?? [];
     const prefix = opts.prefix ?? "http:";
-    const buildKey = opts.key ?? ((ctx) => defaultKey(ctx, vary));
+    const hasCustomKey = typeof opts.key === "function";
+    const authMode = opts.authenticated ?? "bypass";
+    // When varying by credentials, fold the credential headers into the key so
+    // each identity gets a private entry.
+    const effectiveVary = authMode === "vary" ? [...vary, ...CREDENTIAL_HEADERS] : vary;
+    const buildKey = opts.key ?? ((ctx) => defaultKey(ctx, effectiveVary));
     const directStore = resolveStore(opts.store);
     return async function cacheMiddleware(ctx, next) {
         const req = ctx.request;
@@ -123,6 +138,14 @@ export function cache(opts = {}) {
             await next();
             return;
         }
+        // Secure-by-default: a credentialed (Authorization/Cookie) request usually
+        // produces a per-user response. Caching it under a shared key would leak it
+        // to other users. Unless the caller opted into 'vary'/'allow' or supplied a
+        // custom identity-aware key, bypass the cache for such requests.
+        if (authMode === "bypass" && !hasCustomKey && hasCredentials(req)) {
+            await next();
+            return;
+        }
         // Resolve store: option > module-level default (set by CacheProvider).
         // No store anywhere → middleware acts as a transparent no-op so the
         // route still works without a registered cache backend.

package/dist/stores/database.d.ts

@@ -51,6 +51,13 @@ export declare class DatabaseCacheStore implements CacheStore {
      * @returns Always returns `true`.
      */
     delete(key: string): Promise<boolean>;
+    /**
+     * Delete all expired entries. Entries are otherwise only removed when read,
+     * so call this periodically to stop never-read expired rows from accumulating.
+     *
+     * @returns A promise that resolves once expired rows have been removed.
+     */
+    prune(): Promise<void>;
     /**
      * Remove all entries from the cache table.
      *

package/dist/stores/database.js

@@ -32,7 +32,13 @@ export class DatabaseCacheStore {
             await this.db.exec(`CREATE TABLE IF NOT EXISTS "${this.table}" (key TEXT PRIMARY KEY, value TEXT, expires_at INTEGER)`);
             this._ready = true;
         }
-        catch { }
+        catch (e) {
+            // Don't silently swallow: an unset _ready means every later get/set blows
+            // up with a confusing SQL error. Surface the real cause and rethrow so the
+            // misconfiguration is visible at the point of failure.
+            console.error(`[@tekir/cache] Failed to create cache table "${this.table}": ${e.message}`);
+            throw e;
+        }
     }
     /**
      * Retrieve a cached value by key. Expired entries are deleted and `null` is returned.
@@ -76,7 +82,16 @@ export class DatabaseCacheStore {
      * @returns `true` if the key exists and has not expired.
      */
     async has(key) {
-        return (await this.get(key)) !== null;
+        await this._ensureTable();
+        const row = await this.db.queryOne(`SELECT expires_at FROM "${this.table}" WHERE key = ?`, [key]);
+        if (!row)
+            return false;
+        if (row.expires_at && Date.now() > row.expires_at) {
+            await this.db.run(`DELETE FROM "${this.table}" WHERE key = ?`, [key]);
+            return false;
+        }
+        // Present even if the stored value is `null` (negative caching).
+        return true;
     }
     /**
      * Delete a key from the database.
@@ -89,6 +104,16 @@ export class DatabaseCacheStore {
         await this.db.run(`DELETE FROM "${this.table}" WHERE key = ?`, [key]);
         return true;
     }
+    /**
+     * Delete all expired entries. Entries are otherwise only removed when read,
+     * so call this periodically to stop never-read expired rows from accumulating.
+     *
+     * @returns A promise that resolves once expired rows have been removed.
+     */
+    async prune() {
+        await this._ensureTable();
+        await this.db.run(`DELETE FROM "${this.table}" WHERE expires_at IS NOT NULL AND expires_at < ?`, [Date.now()]);
+    }
     /**
      * Remove all entries from the cache table.
      *

package/dist/stores/memory.d.ts

@@ -12,6 +12,19 @@ import type { CacheStore } from '../types';
  */
 export declare class MemoryCacheStore implements CacheStore {
     private data;
+    private maxEntries;
+    private writes;
+    /**
+     * @param options.maxEntries - Hard cap on stored entries. When exceeded, the
+     *   oldest insertion-order entry is evicted (after pruning expired ones).
+     *   Defaults to 10000 to bound memory growth from never-read keys. Set to 0
+     *   to disable the cap.
+     */
+    constructor(options?: {
+        maxEntries?: number;
+    });
+    /** Remove every entry whose TTL has elapsed. */
+    prune(): void;
     /**
      * Retrieve a cached value by key. Returns `null` if the key does not exist
      * or has expired.

package/dist/stores/memory.js

@@ -11,6 +11,25 @@
  */
 export class MemoryCacheStore {
     data = new Map();
+    maxEntries;
+    writes = 0;
+    /**
+     * @param options.maxEntries - Hard cap on stored entries. When exceeded, the
+     *   oldest insertion-order entry is evicted (after pruning expired ones).
+     *   Defaults to 10000 to bound memory growth from never-read keys. Set to 0
+     *   to disable the cap.
+     */
+    constructor(options = {}) {
+        this.maxEntries = options.maxEntries ?? 10000;
+    }
+    /** Remove every entry whose TTL has elapsed. */
+    prune() {
+        const now = Date.now();
+        for (const [k, entry] of this.data) {
+            if (entry.expiresAt && now > entry.expiresAt)
+                this.data.delete(k);
+        }
+    }
     /**
      * Retrieve a cached value by key. Returns `null` if the key does not exist
      * or has expired.
@@ -40,6 +59,18 @@ export class MemoryCacheStore {
             value,
             expiresAt: ttlSeconds ? Date.now() + ttlSeconds * 1000 : null,
         });
+        // Periodically sweep expired entries so keys that are never read again don't
+        // accumulate unbounded, then enforce the size cap.
+        if (this.maxEntries > 0) {
+            if (++this.writes % 256 === 0)
+                this.prune();
+            while (this.data.size > this.maxEntries) {
+                const oldest = this.data.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.data.delete(oldest);
+            }
+        }
     }
     /**
      * Check whether a key exists and is not expired.
@@ -48,7 +79,16 @@ export class MemoryCacheStore {
      * @returns `true` if the key exists and has not expired.
      */
     async has(key) {
-        return (await this.get(key)) !== null;
+        // Check the map directly so an explicitly stored `null` value still counts
+        // as present (get() alone can't distinguish stored-null from absent).
+        const entry = this.data.get(key);
+        if (!entry)
+            return false;
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.data.delete(key);
+            return false;
+        }
+        return true;
     }
     /**
      * Delete a key from the store.

package/dist/stores/redis.d.ts

@@ -79,8 +79,13 @@ export declare class RedisCacheStore implements CacheStore {
      */
     delete(key: string): Promise<boolean>;
     /**
-     * Flush the entire Redis database. Use with caution as this removes all keys,
-     * not just those managed by this store.
+     * Remove only this store's keys (those under its prefix) using a non-blocking
+     * SCAN + DEL. This no longer flushes the entire Redis database, so data owned
+     * by other stores sharing the same database (sessions, queues, ...) is left
+     * intact.
+     *
+     * If the prefix is empty (which would match every key) this throws rather than
+     * risk wiping unrelated data; configure a non-empty prefix to use flush.
      *
      * @example
      * ```ts

package/dist/stores/redis.js

@@ -60,12 +60,22 @@ export class RedisCacheStore {
      */
     async set(key, value, ttlSeconds) {
         const val = JSON.stringify(value);
+        const fullKey = this.prefix + key;
         if (ttlSeconds) {
-            await this.redis.set(this.prefix + key, val);
-            await this.redis.expire(this.prefix + key, ttlSeconds);
+            const sendable = this.redis;
+            if (typeof sendable.send === "function") {
+                // Atomic SET ... EX so a crash between SET and EXPIRE can never leave a
+                // permanent (TTL-less) key behind.
+                await sendable.send("SET", [fullKey, val, "EX", String(Math.floor(ttlSeconds))]);
+            }
+            else {
+                // Fallback for clients without a raw `send`: best-effort two-step.
+                await this.redis.set(fullKey, val);
+                await this.redis.expire(fullKey, ttlSeconds);
+            }
         }
         else {
-            await this.redis.set(this.prefix + key, val);
+            await this.redis.set(fullKey, val);
         }
     }
     /**
@@ -100,8 +110,13 @@ export class RedisCacheStore {
         return true;
     }
     /**
-     * Flush the entire Redis database. Use with caution as this removes all keys,
-     * not just those managed by this store.
+     * Remove only this store's keys (those under its prefix) using a non-blocking
+     * SCAN + DEL. This no longer flushes the entire Redis database, so data owned
+     * by other stores sharing the same database (sessions, queues, ...) is left
+     * intact.
+     *
+     * If the prefix is empty (which would match every key) this throws rather than
+     * risk wiping unrelated data; configure a non-empty prefix to use flush.
      *
      * @example
      * ```ts
@@ -109,8 +124,20 @@ export class RedisCacheStore {
      * ```
      */
     async flush() {
+        if (!this.prefix) {
+            throw new Error('[@tekir/cache] RedisCacheStore.flush() refused: an empty prefix would delete every key in the database. Configure a non-empty prefix.');
+        }
         // Structural cast: callers may pass clients with varying `send` arg
         // types. We only need it to accept a string command and an array.
-        await this.redis.send('FLUSHDB', []);
+        const client = this.redis;
+        const pattern = `${this.prefix}*`;
+        let cursor = '0';
+        do {
+            const reply = (await client.send('SCAN', [cursor, 'MATCH', pattern, 'COUNT', '100']));
+            const [next, batch] = reply;
+            cursor = next;
+            if (batch && batch.length)
+                await client.send('DEL', batch);
+        } while (cursor !== '0');
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekir/cache",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "In-memory, Redis, and database caching abstraction",
   "author": "dev@tekir.io",
   "license": "MIT",
@@ -39,7 +39,7 @@
     }
   },
   "dependencies": {
-    "@tekir/core": "^0.1.27"
+    "@tekir/core": "^0.1.0"
   },
   "peerDependencies": {
     "@tekir/redis": "^0.1.0"

package/src/cache.ts

@@ -18,6 +18,9 @@ export class Cache {
   private stores: Record<string, CacheStore>
   private defaultStore: string
   private defaultTtl: number
+  // In-flight factory promises keyed by `<store>:<key>` for single-flight
+  // stampede protection in getOrSet.
+  private inFlight = new Map<string, Promise<unknown>>()
 
   /**
    * Create a new Cache instance.
@@ -96,6 +99,10 @@ export class Cache {
    * @param factory - An async function that produces the value when not cached.
    * @returns The cached or freshly-computed value.
    *
+   * Concurrent misses for the same key share a single `factory()` execution
+   * (single-flight) so a popular key expiring does not trigger a stampede
+   * (thundering herd) against the backend.
+   *
    * @example
    * ```ts
    * const users = await cache.getOrSet('users', 300, () => db.query('SELECT * FROM users'))
@@ -104,9 +111,19 @@ export class Cache {
   async getOrSet<T>(key: string, ttl: number, factory: () => Promise<T>): Promise<T> {
     const cached = await this.get<T>(key)
     if (cached !== null) return cached
-    const value = await factory()
-    await this.set(key, value, ttl)
-    return value
+
+    const flightKey = `${this.defaultStore}:${key}`
+    const existing = this.inFlight.get(flightKey)
+    if (existing) return existing as Promise<T>
+
+    const promise = (async () => {
+      const value = await factory()
+      await this.set(key, value, ttl)
+      return value
+    })().finally(() => this.inFlight.delete(flightKey))
+
+    this.inFlight.set(flightKey, promise)
+    return promise
   }
 
   /**
@@ -122,7 +139,10 @@ export class Cache {
    */
   async pull<T = unknown>(key: string): Promise<T | null> {
     const value = await this.get<T>(key)
-    if (value !== null) await this.delete(key)
+    // Use has() rather than a null-check so that an explicitly cached `null`
+    // value is still evicted (get() alone cannot distinguish "absent" from
+    // "stored null").
+    if (value !== null || (await this.has(key))) await this.delete(key)
     return value
   }
 }

package/src/http-cache.ts

@@ -60,8 +60,30 @@ export type HttpCacheOptions = {
    * responses. Default: true.
    */
   setCacheControl?: boolean
+  /**
+   * How to handle requests that carry credentials (`Authorization` or `Cookie`).
+   *
+   * Caching a per-user response under a shared key leaks one user's response to
+   * another. To prevent that, the default behaviour is `'bypass'`: authenticated
+   * requests skip the cache entirely unless you opt in.
+   *
+   * - `'bypass'` (default): never read or write the cache for credentialed
+   *   requests.
+   * - `'vary'`: include the credential headers in the cache key so each
+   *   identity gets its own entry. Use this only when you understand the cache
+   *   size implications.
+   * - `'allow'`: cache credentialed requests under the same key as anonymous
+   *   ones. DANGEROUS: only safe when the response is identical for every user.
+   *
+   * Note: providing a custom `key` builder that already incorporates identity
+   * overrides this and is always honoured.
+   */
+  authenticated?: "bypass" | "vary" | "allow"
 }
 
+/** Request headers that indicate a credentialed/per-user request. */
+const CREDENTIAL_HEADERS = ["authorization", "cookie"]
+
 export type HttpCacheCtx = {
   request: { url: string; method: string; headers: Headers; raw?: Request }
   params?: Record<string, string>
@@ -162,12 +184,26 @@ const entryToResponse = (e: CachedEntry, opts: HttpCacheOptions): Response => {
   return new Response(e.body, { status: e.status, headers })
 }
 
+/** True if the request carries an Authorization or Cookie header. */
+const hasCredentials = (req: HttpCacheCtx["request"]): boolean => {
+  for (const h of CREDENTIAL_HEADERS) {
+    if (req.headers?.get?.(h)) return true
+  }
+  return false
+}
+
 export function cache(opts: HttpCacheOptions = {}) {
   const ttl = opts.ttl ?? 60
   const methods = new Set((opts.methods ?? SAFE_METHODS).map((m) => m.toUpperCase()))
   const vary = opts.vary ?? []
   const prefix = opts.prefix ?? "http:"
-  const buildKey = opts.key ?? ((ctx: HttpCacheCtx) => defaultKey(ctx, vary))
+  const hasCustomKey = typeof opts.key === "function"
+  const authMode = opts.authenticated ?? "bypass"
+  // When varying by credentials, fold the credential headers into the key so
+  // each identity gets a private entry.
+  const effectiveVary =
+    authMode === "vary" ? [...vary, ...CREDENTIAL_HEADERS] : vary
+  const buildKey = opts.key ?? ((ctx: HttpCacheCtx) => defaultKey(ctx, effectiveVary))
   const directStore = resolveStore(opts.store)
 
   return async function cacheMiddleware(ctx: any, next: () => Promise<void>) {
@@ -188,6 +224,15 @@ export function cache(opts: HttpCacheOptions = {}) {
       return
     }
 
+    // Secure-by-default: a credentialed (Authorization/Cookie) request usually
+    // produces a per-user response. Caching it under a shared key would leak it
+    // to other users. Unless the caller opted into 'vary'/'allow' or supplied a
+    // custom identity-aware key, bypass the cache for such requests.
+    if (authMode === "bypass" && !hasCustomKey && hasCredentials(req)) {
+      await next()
+      return
+    }
+
     // Resolve store: option > module-level default (set by CacheProvider).
     // No store anywhere → middleware acts as a transparent no-op so the
     // route still works without a registered cache backend.

package/src/stores/database.ts

@@ -35,7 +35,13 @@ export class DatabaseCacheStore implements CacheStore {
     try {
       await this.db.exec(`CREATE TABLE IF NOT EXISTS "${this.table}" (key TEXT PRIMARY KEY, value TEXT, expires_at INTEGER)`)
       this._ready = true
-    } catch {}
+    } catch (e) {
+      // Don't silently swallow: an unset _ready means every later get/set blows
+      // up with a confusing SQL error. Surface the real cause and rethrow so the
+      // misconfiguration is visible at the point of failure.
+      console.error(`[@tekir/cache] Failed to create cache table "${this.table}": ${(e as Error).message}`)
+      throw e
+    }
   }
 
   /**
@@ -79,7 +85,15 @@ export class DatabaseCacheStore implements CacheStore {
    * @returns `true` if the key exists and has not expired.
    */
   async has(key: string): Promise<boolean> {
-    return (await this.get(key)) !== null
+    await this._ensureTable()
+    const row = await this.db.queryOne(`SELECT expires_at FROM "${this.table}" WHERE key = ?`, [key]) as { expires_at: number | null } | null
+    if (!row) return false
+    if (row.expires_at && Date.now() > row.expires_at) {
+      await this.db.run(`DELETE FROM "${this.table}" WHERE key = ?`, [key])
+      return false
+    }
+    // Present even if the stored value is `null` (negative caching).
+    return true
   }
 
   /**
@@ -94,6 +108,17 @@ export class DatabaseCacheStore implements CacheStore {
     return true
   }
 
+  /**
+   * Delete all expired entries. Entries are otherwise only removed when read,
+   * so call this periodically to stop never-read expired rows from accumulating.
+   *
+   * @returns A promise that resolves once expired rows have been removed.
+   */
+  async prune(): Promise<void> {
+    await this._ensureTable()
+    await this.db.run(`DELETE FROM "${this.table}" WHERE expires_at IS NOT NULL AND expires_at < ?`, [Date.now()])
+  }
+
   /**
    * Remove all entries from the cache table.
    *

package/src/stores/memory.ts

@@ -13,6 +13,26 @@ import type { CacheStore } from '../types'
  */
 export class MemoryCacheStore implements CacheStore {
   private data = new Map<string, { value: unknown; expiresAt: number | null }>()
+  private maxEntries: number
+  private writes = 0
+
+  /**
+   * @param options.maxEntries - Hard cap on stored entries. When exceeded, the
+   *   oldest insertion-order entry is evicted (after pruning expired ones).
+   *   Defaults to 10000 to bound memory growth from never-read keys. Set to 0
+   *   to disable the cap.
+   */
+  constructor(options: { maxEntries?: number } = {}) {
+    this.maxEntries = options.maxEntries ?? 10000
+  }
+
+  /** Remove every entry whose TTL has elapsed. */
+  prune(): void {
+    const now = Date.now()
+    for (const [k, entry] of this.data) {
+      if (entry.expiresAt && now > entry.expiresAt) this.data.delete(k)
+    }
+  }
 
   /**
    * Retrieve a cached value by key. Returns `null` if the key does not exist
@@ -43,6 +63,16 @@ export class MemoryCacheStore implements CacheStore {
       value,
       expiresAt: ttlSeconds ? Date.now() + ttlSeconds * 1000 : null,
     })
+    // Periodically sweep expired entries so keys that are never read again don't
+    // accumulate unbounded, then enforce the size cap.
+    if (this.maxEntries > 0) {
+      if (++this.writes % 256 === 0) this.prune()
+      while (this.data.size > this.maxEntries) {
+        const oldest = this.data.keys().next().value
+        if (oldest === undefined) break
+        this.data.delete(oldest)
+      }
+    }
   }
 
   /**
@@ -52,7 +82,15 @@ export class MemoryCacheStore implements CacheStore {
    * @returns `true` if the key exists and has not expired.
    */
   async has(key: string): Promise<boolean> {
-    return (await this.get(key)) !== null
+    // Check the map directly so an explicitly stored `null` value still counts
+    // as present (get() alone can't distinguish stored-null from absent).
+    const entry = this.data.get(key)
+    if (!entry) return false
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.data.delete(key)
+      return false
+    }
+    return true
   }
 
   /**

package/src/stores/redis.ts

@@ -77,11 +77,20 @@ export class RedisCacheStore implements CacheStore {
    */
   async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
     const val = JSON.stringify(value)
+    const fullKey = this.prefix + key
     if (ttlSeconds) {
-      await this.redis.set(this.prefix + key, val)
-      await this.redis.expire(this.prefix + key, ttlSeconds)
+      const sendable = this.redis as unknown as Partial<RawSendable>
+      if (typeof sendable.send === "function") {
+        // Atomic SET ... EX so a crash between SET and EXPIRE can never leave a
+        // permanent (TTL-less) key behind.
+        await sendable.send("SET", [fullKey, val, "EX", String(Math.floor(ttlSeconds))])
+      } else {
+        // Fallback for clients without a raw `send`: best-effort two-step.
+        await this.redis.set(fullKey, val)
+        await this.redis.expire(fullKey, ttlSeconds)
+      }
     } else {
-      await this.redis.set(this.prefix + key, val)
+      await this.redis.set(fullKey, val)
     }
   }
 
@@ -119,8 +128,13 @@ export class RedisCacheStore implements CacheStore {
   }
 
   /**
-   * Flush the entire Redis database. Use with caution as this removes all keys,
-   * not just those managed by this store.
+   * Remove only this store's keys (those under its prefix) using a non-blocking
+   * SCAN + DEL. This no longer flushes the entire Redis database, so data owned
+   * by other stores sharing the same database (sessions, queues, ...) is left
+   * intact.
+   *
+   * If the prefix is empty (which would match every key) this throws rather than
+   * risk wiping unrelated data; configure a non-empty prefix to use flush.
    *
    * @example
    * ```ts
@@ -128,8 +142,21 @@ export class RedisCacheStore implements CacheStore {
    * ```
    */
   async flush(): Promise<void> {
+    if (!this.prefix) {
+      throw new Error(
+        '[@tekir/cache] RedisCacheStore.flush() refused: an empty prefix would delete every key in the database. Configure a non-empty prefix.'
+      )
+    }
     // Structural cast: callers may pass clients with varying `send` arg
     // types. We only need it to accept a string command and an array.
-    await (this.redis as unknown as RawSendable).send('FLUSHDB', [])
+    const client = this.redis as unknown as RawSendable
+    const pattern = `${this.prefix}*`
+    let cursor = '0'
+    do {
+      const reply = (await client.send('SCAN', [cursor, 'MATCH', pattern, 'COUNT', '100'])) as [string, string[]]
+      const [next, batch] = reply
+      cursor = next
+      if (batch && batch.length) await client.send('DEL', batch)
+    } while (cursor !== '0')
   }
 }