@keyv/redis 4.0.2 → 4.2.0

package/README.md

@@ -26,6 +26,7 @@ Redis storage adapter for [Keyv](https://github.com/jaredwray/keyv).
 # Table of Contents
 * [Usage](#usage)
 * [Namespaces](#namespaces)
+* [Typescript](#typescript)
 * [Performance Considerations](#performance-considerations)
 * [High Memory Usage on Redis Server](#high-memory-usage-on-redis-server)
 * [Using Cacheable with Redis](#using-cacheable-with-redis)
@@ -110,14 +111,42 @@ keyv.namespace = 'my-namespace';
 
 NOTE: If you plan to do many clears or deletes, it is recommended to read the [Performance Considerations](#performance-considerations) section.
 
+## Typescript
+
+When initializing `KeyvRedis`, you can specify the type of the values you are storing and you can also specify types when calling methods:
+
+```typescript
+import Keyv from 'keyv';
+import KeyvRedis, { createClient } from '@keyv/redis';
+
+
+interface User {
+  id: number
+  name: string
+}
+
+const redis = createClient('redis://user:pass@localhost:6379');
+
+const keyvRedis = new KeyvRedis<User>(redis);
+const keyv = new Keyv({ store: keyvRedis });
+
+await keyv.set("user:1", { id: 1, name: "Alice" })
+const user = await keyv.get("user:1")
+console.log(user.name) // 'Alice'
+
+// specify types when calling methods
+const user = await keyv.get<User>("user:1")
+console.log(user.name) // 'Alice'
+```
+
 # Performance Considerations
 
 With namespaces being prefix based it is critical to understand some of the performance considerations we have made:
-* `clear()` - We use the `SCAN` command to iterate over keys. This is a non-blocking command that is more efficient than `KEYS`. In addition we are using `UNLINK` by default instead of `DEL`. Even with that if you are iterating over a large dataset it can still be slow. It is highly recommended to use the `namespace` option to limit the keys that are being cleared and if possible to not use the `clear()` method in high performance environments.
+* `clear()` - We use the `SCAN` command to iterate over keys. This is a non-blocking command that is more efficient than `KEYS`. In addition we are using `UNLINK` by default instead of `DEL`. Even with that if you are iterating over a large dataset it can still be slow. It is highly recommended to use the `namespace` option to limit the keys that are being cleared and if possible to not use the `clear()` method in high performance environments. If you don't set namespaces, you can enable `noNamespaceAffectsAll` to clear all keys using the `FLUSHDB` command which is faster and can be used in production environments.
 
 * `delete()` - By default we are now using `UNLINK` instead of `DEL` for deleting keys. This is a non-blocking command that is more efficient than `DEL`. If you are deleting a large number of keys it is recommended to use the `deleteMany()` method instead of `delete()`.
 
-* `clearBatchSize` - The `clearBatchSize` option is set to `1000` by default. This is because Redis has a limit of 1000 keys that can be deleted in a single batch. 
+* `clearBatchSize` - The `clearBatchSize` option is set to `1000` by default. This is because Redis has a limit of 1000 keys that can be deleted in a single batch. If no namespace is defined and noNamespaceAffectsAll is set to `true` this option will be ignored and the `FLUSHDB` command will be used instead.
 
 * `useUnlink` - This option is set to `true` by default. This is because `UNLINK` is a non-blocking command that is more efficient than `DEL`. If you are not using `UNLINK` and are doing a lot of deletes it is recommended to set this option to `true`.
 
@@ -183,8 +212,6 @@ const cluster = createCluster({
 const keyv = new Keyv({ store: new KeyvRedis(cluster) });
 ```
 
-There are some features that are not supported in clustering such as `clear()` and `iterator()`. This is because the `SCAN` command is not supported in clustering. If you need to clear or delete keys you can use the `deleteMany()` method.
-
 You can learn more about the `createCluster` function in the [documentation](https://github.com/redis/node-redis/blob/master/docs/clustering.md) at https://github.com/redis/node-redis/tree/master/docs. 
 
 Here is an example of how to use TLS:
@@ -217,6 +244,7 @@ const keyv = new Keyv({ store: new KeyvRedis(tlsOptions) });
 * **keyPrefixSeparator** - The separator to use between the namespace and key.
 * **clearBatchSize** - The number of keys to delete in a single batch.
 * **useUnlink** - Use the `UNLINK` command for deleting keys isntead of `DEL`.
+* **noNamespaceAffectsAll**: Whether to allow clearing all keys when no namespace is set (default is `false`).
 * **set** - Set a key.
 * **setMany** - Set multiple keys.
 * **get** - Get a key.
@@ -225,9 +253,9 @@ const keyv = new Keyv({ store: new KeyvRedis(tlsOptions) });
 * **hasMany** - Check if multiple keys exist.
 * **delete** - Delete a key.
 * **deleteMany** - Delete multiple keys.
-* **clear** - Clear all keys. If the `namespace` is set it will only clear keys with that namespace.
+* **clear** - Clear all keys in the namespace. If the namespace is not set it will clear all keys that are not prefixed with a namespace unless `noNamespaceAffectsAll` is set to `true`.
 * **disconnect** - Disconnect from the Redis server.
-* **iterator** - Create a new iterator for the keys.
+* **iterator** - Create a new iterator for the keys. If the namespace is not set it will iterate over all keys that are not prefixed with a namespace unless `noNamespaceAffectsAll` is set to `true`.
 
 # Migrating from v3 to v4
 

package/dist/index.cjs

@@ -40,6 +40,7 @@ module.exports = __toCommonJS(src_exports);
 var import_node_events = __toESM(require("events"), 1);
 var import_redis = require("redis");
 var import_keyv = require("keyv");
+var import_cluster_key_slot = __toESM(require("cluster-key-slot"), 1);
 var import_redis2 = require("redis");
 var import_keyv2 = require("keyv");
 var KeyvRedis = class extends import_node_events.default {
@@ -48,6 +49,7 @@ var KeyvRedis = class extends import_node_events.default {
   _keyPrefixSeparator = "::";
   _clearBatchSize = 1e3;
   _useUnlink = true;
+  _noNamespaceAffectsAll = false;
   /**
    * KeyvRedis constructor.
    * @param {string | RedisClientOptions | RedisClientType} [connect] How to connect to the Redis server. If string pass in the url, if object pass in the options, if RedisClient pass in the client.
@@ -92,6 +94,7 @@ var KeyvRedis = class extends import_node_events.default {
       namespace: this._namespace,
       keyPrefixSeparator: this._keyPrefixSeparator,
       clearBatchSize: this._clearBatchSize,
+      noNamespaceAffectsAll: this._noNamespaceAffectsAll,
       dialect: "redis",
       url
     };
@@ -155,6 +158,21 @@ var KeyvRedis = class extends import_node_events.default {
   set useUnlink(value) {
     this._useUnlink = value;
   }
+  /**
+   * Get if no namespace affects all keys.
+   * Whether to allow clearing all keys when no namespace is set.
+   * If set to true and no namespace is set, iterate() will return all keys.
+   * @default false
+   */
+  get noNamespaceAffectsAll() {
+    return this._noNamespaceAffectsAll;
+  }
+  /**
+   * Set if not namespace affects all keys.
+   */
+  set noNamespaceAffectsAll(value) {
+    this._noNamespaceAffectsAll = value;
+  }
   /**
    * Get the Redis URL used to connect to the server. This is used to get a connected client.
    */
@@ -242,14 +260,12 @@ var KeyvRedis = class extends import_node_events.default {
    * @returns {Promise<Array<string | undefined>>} - array of values or undefined if the key does not exist
    */
   async getMany(keys) {
-    const client = await this.getClient();
-    const multi = client.multi();
-    for (const key of keys) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      multi.get(prefixedKey);
+    if (keys.length === 0) {
+      return [];
     }
-    const values = await multi.exec();
-    return values.map((value) => value === null ? void 0 : value);
+    keys = keys.map((key) => this.createKeyPrefix(key, this._namespace));
+    const values = await this.mget(keys);
+    return values;
   }
   /**
    * Delete a key from the store.
@@ -329,42 +345,44 @@ var KeyvRedis = class extends import_node_events.default {
     return this.isClientCluster(this._client);
   }
   /**
-   * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
-   * @param {string} [namespace] - the namespace to iterate over
-   * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
+   * Get the master nodes in the cluster. If not a cluster, it will return the single client.
+   *
+   * @returns {Promise<RedisClientType[]>} - array of master nodes
    */
-  async *iterator(namespace) {
+  async getMasterNodes() {
     if (this.isCluster()) {
-      throw new Error("Iterating over keys in a cluster is not supported.");
-    } else {
-      yield* this.iteratorClient(namespace);
+      const cluster = await this.getClient();
+      return Promise.all(cluster.masters.map(async (main) => cluster.nodeClient(main)));
     }
+    return [await this.getClient()];
   }
   /**
    * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
    * @param {string} [namespace] - the namespace to iterate over
    * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
    */
-  async *iteratorClient(namespace) {
-    const client = await this.getClient();
-    const match = namespace ? `${namespace}${this._keyPrefixSeparator}*` : "*";
-    let cursor = "0";
-    do {
-      const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, TYPE: "string" });
-      cursor = result.cursor.toString();
-      let { keys } = result;
-      if (!namespace) {
-        keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
-      }
-      if (keys.length > 0) {
-        const values = await client.mGet(keys);
-        for (const [i] of keys.entries()) {
-          const key = this.getKeyWithoutPrefix(keys[i], namespace);
-          const value = values ? values[i] : void 0;
-          yield [key, value];
+  async *iterator(namespace) {
+    const clients = await this.getMasterNodes();
+    for (const client of clients) {
+      const match = namespace ? `${namespace}${this._keyPrefixSeparator}*` : "*";
+      let cursor = "0";
+      do {
+        const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, TYPE: "string" });
+        cursor = result.cursor.toString();
+        let { keys } = result;
+        if (!namespace && !this._noNamespaceAffectsAll) {
+          keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
         }
-      }
-    } while (cursor !== "0");
+        if (keys.length > 0) {
+          const values = await this.mget(keys);
+          for (const i of keys.keys()) {
+            const key = this.getKeyWithoutPrefix(keys[i], namespace);
+            const value = values[i];
+            yield [key, value];
+          }
+        }
+      } while (cursor !== "0");
+    }
   }
   /**
    * Clear all keys in the store.
@@ -374,38 +392,95 @@ var KeyvRedis = class extends import_node_events.default {
    * @returns {Promise<void>}
    */
   async clear() {
-    await (this.isCluster() ? this.clearNamespaceCluster(this._namespace) : this.clearNamespace(this._namespace));
-  }
-  async clearNamespace(namespace) {
     try {
-      let cursor = "0";
-      const batchSize = this._clearBatchSize;
-      const match = namespace ? `${namespace}${this._keyPrefixSeparator}*` : "*";
-      const client = await this.getClient();
-      do {
-        const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, COUNT: batchSize, TYPE: "string" });
-        cursor = result.cursor.toString();
-        let { keys } = result;
-        if (keys.length === 0) {
-          continue;
-        }
-        if (!namespace) {
-          keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
+      const clients = await this.getMasterNodes();
+      await Promise.all(clients.map(async (client) => {
+        if (!this._namespace && this._noNamespaceAffectsAll) {
+          await client.flushDb();
+          return;
         }
-        if (keys.length > 0) {
-          if (this._useUnlink) {
-            await client.unlink(keys);
-          } else {
-            await client.del(keys);
+        let cursor = "0";
+        const batchSize = this._clearBatchSize;
+        const match = this._namespace ? `${this._namespace}${this._keyPrefixSeparator}*` : "*";
+        const deletePromises = [];
+        do {
+          const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, COUNT: batchSize, TYPE: "string" });
+          cursor = result.cursor.toString();
+          let { keys } = result;
+          if (keys.length === 0) {
+            continue;
           }
-        }
-      } while (cursor !== "0");
+          if (!this._namespace) {
+            keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
+          }
+          deletePromises.push(this.clearWithClusterSupport(keys));
+        } while (cursor !== "0");
+        await Promise.all(deletePromises);
+      }));
     } catch (error) {
       this.emit("error", error);
     }
   }
-  async clearNamespaceCluster(namespace) {
-    throw new Error("Clearing all keys in a cluster is not supported.");
+  /**
+   * Get many keys. If the instance is a cluster, it will do multiple MGET calls
+   * by separating the keys by slot to solve the CROSS-SLOT restriction.
+   */
+  async mget(keys) {
+    const slotMap = this.getSlotMap(keys);
+    const valueMap = /* @__PURE__ */ new Map();
+    await Promise.all(Array.from(slotMap.entries(), async ([slot, keys2]) => {
+      const client = await this.getSlotMaster(slot);
+      const values = await client.mGet(keys2);
+      for (const [index, value] of values.entries()) {
+        valueMap.set(keys2[index], value ?? void 0);
+      }
+    }));
+    return keys.map((key) => valueMap.get(key));
+  }
+  /**
+   * Clear all keys in the store with a specific namespace. If the instance is a cluster, it will clear all keys
+   * by separating the keys by slot to solve the CROSS-SLOT restriction.
+   */
+  async clearWithClusterSupport(keys) {
+    if (keys.length > 0) {
+      const slotMap = this.getSlotMap(keys);
+      await Promise.all(Array.from(slotMap.entries(), async ([slot, keys2]) => {
+        const client = await this.getSlotMaster(slot);
+        return this._useUnlink ? client.unlink(keys2) : client.del(keys2);
+      }));
+    }
+  }
+  /**
+   * Returns the master node client for a given slot or the instance's client if it's not a cluster.
+   */
+  async getSlotMaster(slot) {
+    const connection = await this.getClient();
+    if (this.isCluster()) {
+      const cluster = connection;
+      const mainNode = cluster.slots[slot].master;
+      return cluster.nodeClient(mainNode);
+    }
+    return connection;
+  }
+  /**
+   * Group keys by their slot.
+   *
+   * @param {string[]} keys - the keys to group
+   * @returns {Map<number, string[]>} - map of slot to keys
+   */
+  getSlotMap(keys) {
+    const slotMap = /* @__PURE__ */ new Map();
+    if (this.isCluster()) {
+      for (const key of keys) {
+        const slot = (0, import_cluster_key_slot.default)(key);
+        const slotKeys = slotMap.get(slot) ?? [];
+        slotKeys.push(key);
+        slotMap.set(slot, slotKeys);
+      }
+    } else {
+      slotMap.set(0, keys);
+    }
+    return slotMap;
   }
   isClientCluster(client) {
     if (client.options === void 0 && client.scan === void 0) {
@@ -429,6 +504,9 @@ var KeyvRedis = class extends import_node_events.default {
     if (options.useUnlink !== void 0) {
       this._useUnlink = options.useUnlink;
     }
+    if (options.noNamespaceAffectsAll !== void 0) {
+      this._noNamespaceAffectsAll = options.noNamespaceAffectsAll;
+    }
   }
   initClient() {
     this._client.on("error", (error) => {

package/dist/index.d.cts

@@ -21,6 +21,12 @@ type KeyvRedisOptions = {
      * Enable Unlink instead of using Del for clearing keys. This is more performant but may not be supported by all Redis versions.
      */
     useUnlink?: boolean;
+    /**
+     * Whether to allow clearing all keys when no namespace is set.
+     * If set to true and no namespace is set, iterate() will return all keys.
+     * Defaults to `false`.
+     */
+    noNamespaceAffectsAll?: boolean;
 };
 type KeyvRedisPropertyOptions = KeyvRedisOptions & {
     /**
@@ -47,12 +53,13 @@ type KeyvRedisEntry<T> = {
     ttl?: number;
 };
 type RedisClientConnectionType = RedisClientType | RedisClusterType<RedisModules, RedisFunctions, RedisScripts>;
-declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
+declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
     private _client;
     private _namespace;
     private _keyPrefixSeparator;
     private _clearBatchSize;
     private _useUnlink;
+    private _noNamespaceAffectsAll;
     /**
      * KeyvRedis constructor.
      * @param {string | RedisClientOptions | RedisClientType} [connect] How to connect to the Redis server. If string pass in the url, if object pass in the options, if RedisClient pass in the client.
@@ -111,6 +118,17 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * Set if Unlink is used instead of Del for clearing keys. This is more performant but may not be supported by all Redis versions.
      */
     set useUnlink(value: boolean);
+    /**
+     * Get if no namespace affects all keys.
+     * Whether to allow clearing all keys when no namespace is set.
+     * If set to true and no namespace is set, iterate() will return all keys.
+     * @default false
+     */
+    get noNamespaceAffectsAll(): boolean;
+    /**
+     * Set if not namespace affects all keys.
+     */
+    set noNamespaceAffectsAll(value: boolean);
     /**
      * Get the Redis URL used to connect to the server. This is used to get a connected client.
      */
@@ -144,13 +162,13 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * @param {string} key - the key to get
      * @returns {Promise<string | undefined>} - the value or undefined if the key does not exist
      */
-    get<T>(key: string): Promise<T | undefined>;
+    get<U = T>(key: string): Promise<U | undefined>;
     /**
      * Get many values from the store. If a key does not exist, it will return undefined.
      * @param {Array<string>} keys - the keys to get
      * @returns {Promise<Array<string | undefined>>} - array of values or undefined if the key does not exist
      */
-    getMany<T>(keys: string[]): Promise<Array<T | undefined>>;
+    getMany<U = T>(keys: string[]): Promise<Array<U | undefined>>;
     /**
      * Delete a key from the store.
      * @param {string} key - the key to delete
@@ -188,17 +206,17 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      */
     isCluster(): boolean;
     /**
-     * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
-     * @param {string} [namespace] - the namespace to iterate over
-     * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
+     * Get the master nodes in the cluster. If not a cluster, it will return the single client.
+     *
+     * @returns {Promise<RedisClientType[]>} - array of master nodes
      */
-    iterator<Value>(namespace?: string): AsyncGenerator<[string, Value | undefined], void, unknown>;
+    getMasterNodes(): Promise<RedisClientType[]>;
     /**
      * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
      * @param {string} [namespace] - the namespace to iterate over
      * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
      */
-    iteratorClient<Value>(namespace?: string): AsyncGenerator<[string, Value | undefined], void, unknown>;
+    iterator<U = T>(namespace?: string): AsyncGenerator<[string, U | undefined], void, unknown>;
     /**
      * Clear all keys in the store.
      * IMPORTANT: this can cause performance issues if there are a large number of keys in the store and worse with clusters. Use with caution as not recommended for production.
@@ -207,8 +225,27 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * @returns {Promise<void>}
      */
     clear(): Promise<void>;
-    private clearNamespace;
-    private clearNamespaceCluster;
+    /**
+     * Get many keys. If the instance is a cluster, it will do multiple MGET calls
+     * by separating the keys by slot to solve the CROSS-SLOT restriction.
+     */
+    private mget;
+    /**
+     * Clear all keys in the store with a specific namespace. If the instance is a cluster, it will clear all keys
+     * by separating the keys by slot to solve the CROSS-SLOT restriction.
+     */
+    private clearWithClusterSupport;
+    /**
+     * Returns the master node client for a given slot or the instance's client if it's not a cluster.
+     */
+    private getSlotMaster;
+    /**
+     * Group keys by their slot.
+     *
+     * @param {string[]} keys - the keys to group
+     * @returns {Map<number, string[]>} - map of slot to keys
+     */
+    private getSlotMap;
     private isClientCluster;
     private setOptions;
     private initClient;

package/dist/index.d.ts

@@ -21,6 +21,12 @@ type KeyvRedisOptions = {
      * Enable Unlink instead of using Del for clearing keys. This is more performant but may not be supported by all Redis versions.
      */
     useUnlink?: boolean;
+    /**
+     * Whether to allow clearing all keys when no namespace is set.
+     * If set to true and no namespace is set, iterate() will return all keys.
+     * Defaults to `false`.
+     */
+    noNamespaceAffectsAll?: boolean;
 };
 type KeyvRedisPropertyOptions = KeyvRedisOptions & {
     /**
@@ -47,12 +53,13 @@ type KeyvRedisEntry<T> = {
     ttl?: number;
 };
 type RedisClientConnectionType = RedisClientType | RedisClusterType<RedisModules, RedisFunctions, RedisScripts>;
-declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
+declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
     private _client;
     private _namespace;
     private _keyPrefixSeparator;
     private _clearBatchSize;
     private _useUnlink;
+    private _noNamespaceAffectsAll;
     /**
      * KeyvRedis constructor.
      * @param {string | RedisClientOptions | RedisClientType} [connect] How to connect to the Redis server. If string pass in the url, if object pass in the options, if RedisClient pass in the client.
@@ -111,6 +118,17 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * Set if Unlink is used instead of Del for clearing keys. This is more performant but may not be supported by all Redis versions.
      */
     set useUnlink(value: boolean);
+    /**
+     * Get if no namespace affects all keys.
+     * Whether to allow clearing all keys when no namespace is set.
+     * If set to true and no namespace is set, iterate() will return all keys.
+     * @default false
+     */
+    get noNamespaceAffectsAll(): boolean;
+    /**
+     * Set if not namespace affects all keys.
+     */
+    set noNamespaceAffectsAll(value: boolean);
     /**
      * Get the Redis URL used to connect to the server. This is used to get a connected client.
      */
@@ -144,13 +162,13 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * @param {string} key - the key to get
      * @returns {Promise<string | undefined>} - the value or undefined if the key does not exist
      */
-    get<T>(key: string): Promise<T | undefined>;
+    get<U = T>(key: string): Promise<U | undefined>;
     /**
      * Get many values from the store. If a key does not exist, it will return undefined.
      * @param {Array<string>} keys - the keys to get
      * @returns {Promise<Array<string | undefined>>} - array of values or undefined if the key does not exist
      */
-    getMany<T>(keys: string[]): Promise<Array<T | undefined>>;
+    getMany<U = T>(keys: string[]): Promise<Array<U | undefined>>;
     /**
      * Delete a key from the store.
      * @param {string} key - the key to delete
@@ -188,17 +206,17 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      */
     isCluster(): boolean;
     /**
-     * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
-     * @param {string} [namespace] - the namespace to iterate over
-     * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
+     * Get the master nodes in the cluster. If not a cluster, it will return the single client.
+     *
+     * @returns {Promise<RedisClientType[]>} - array of master nodes
      */
-    iterator<Value>(namespace?: string): AsyncGenerator<[string, Value | undefined], void, unknown>;
+    getMasterNodes(): Promise<RedisClientType[]>;
     /**
      * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
      * @param {string} [namespace] - the namespace to iterate over
      * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
      */
-    iteratorClient<Value>(namespace?: string): AsyncGenerator<[string, Value | undefined], void, unknown>;
+    iterator<U = T>(namespace?: string): AsyncGenerator<[string, U | undefined], void, unknown>;
     /**
      * Clear all keys in the store.
      * IMPORTANT: this can cause performance issues if there are a large number of keys in the store and worse with clusters. Use with caution as not recommended for production.
@@ -207,8 +225,27 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * @returns {Promise<void>}
      */
     clear(): Promise<void>;
-    private clearNamespace;
-    private clearNamespaceCluster;
+    /**
+     * Get many keys. If the instance is a cluster, it will do multiple MGET calls
+     * by separating the keys by slot to solve the CROSS-SLOT restriction.
+     */
+    private mget;
+    /**
+     * Clear all keys in the store with a specific namespace. If the instance is a cluster, it will clear all keys
+     * by separating the keys by slot to solve the CROSS-SLOT restriction.
+     */
+    private clearWithClusterSupport;
+    /**
+     * Returns the master node client for a given slot or the instance's client if it's not a cluster.
+     */
+    private getSlotMaster;
+    /**
+     * Group keys by their slot.
+     *
+     * @param {string[]} keys - the keys to group
+     * @returns {Map<number, string[]>} - map of slot to keys
+     */
+    private getSlotMap;
     private isClientCluster;
     private setOptions;
     private initClient;

package/dist/index.js

@@ -5,6 +5,7 @@ import {
   createCluster
 } from "redis";
 import { Keyv } from "keyv";
+import calculateSlot from "cluster-key-slot";
 import {
   createClient as createClient2,
   createCluster as createCluster2
@@ -18,6 +19,7 @@ var KeyvRedis = class extends EventEmitter {
   _keyPrefixSeparator = "::";
   _clearBatchSize = 1e3;
   _useUnlink = true;
+  _noNamespaceAffectsAll = false;
   /**
    * KeyvRedis constructor.
    * @param {string | RedisClientOptions | RedisClientType} [connect] How to connect to the Redis server. If string pass in the url, if object pass in the options, if RedisClient pass in the client.
@@ -62,6 +64,7 @@ var KeyvRedis = class extends EventEmitter {
       namespace: this._namespace,
       keyPrefixSeparator: this._keyPrefixSeparator,
       clearBatchSize: this._clearBatchSize,
+      noNamespaceAffectsAll: this._noNamespaceAffectsAll,
       dialect: "redis",
       url
     };
@@ -125,6 +128,21 @@ var KeyvRedis = class extends EventEmitter {
   set useUnlink(value) {
     this._useUnlink = value;
   }
+  /**
+   * Get if no namespace affects all keys.
+   * Whether to allow clearing all keys when no namespace is set.
+   * If set to true and no namespace is set, iterate() will return all keys.
+   * @default false
+   */
+  get noNamespaceAffectsAll() {
+    return this._noNamespaceAffectsAll;
+  }
+  /**
+   * Set if not namespace affects all keys.
+   */
+  set noNamespaceAffectsAll(value) {
+    this._noNamespaceAffectsAll = value;
+  }
   /**
    * Get the Redis URL used to connect to the server. This is used to get a connected client.
    */
@@ -212,14 +230,12 @@ var KeyvRedis = class extends EventEmitter {
    * @returns {Promise<Array<string | undefined>>} - array of values or undefined if the key does not exist
    */
   async getMany(keys) {
-    const client = await this.getClient();
-    const multi = client.multi();
-    for (const key of keys) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      multi.get(prefixedKey);
+    if (keys.length === 0) {
+      return [];
     }
-    const values = await multi.exec();
-    return values.map((value) => value === null ? void 0 : value);
+    keys = keys.map((key) => this.createKeyPrefix(key, this._namespace));
+    const values = await this.mget(keys);
+    return values;
   }
   /**
    * Delete a key from the store.
@@ -299,42 +315,44 @@ var KeyvRedis = class extends EventEmitter {
     return this.isClientCluster(this._client);
   }
   /**
-   * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
-   * @param {string} [namespace] - the namespace to iterate over
-   * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
+   * Get the master nodes in the cluster. If not a cluster, it will return the single client.
+   *
+   * @returns {Promise<RedisClientType[]>} - array of master nodes
    */
-  async *iterator(namespace) {
+  async getMasterNodes() {
     if (this.isCluster()) {
-      throw new Error("Iterating over keys in a cluster is not supported.");
-    } else {
-      yield* this.iteratorClient(namespace);
+      const cluster = await this.getClient();
+      return Promise.all(cluster.masters.map(async (main) => cluster.nodeClient(main)));
     }
+    return [await this.getClient()];
   }
   /**
    * Get an async iterator for the keys and values in the store. If a namespace is provided, it will only iterate over keys with that namespace.
    * @param {string} [namespace] - the namespace to iterate over
    * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
    */
-  async *iteratorClient(namespace) {
-    const client = await this.getClient();
-    const match = namespace ? `${namespace}${this._keyPrefixSeparator}*` : "*";
-    let cursor = "0";
-    do {
-      const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, TYPE: "string" });
-      cursor = result.cursor.toString();
-      let { keys } = result;
-      if (!namespace) {
-        keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
-      }
-      if (keys.length > 0) {
-        const values = await client.mGet(keys);
-        for (const [i] of keys.entries()) {
-          const key = this.getKeyWithoutPrefix(keys[i], namespace);
-          const value = values ? values[i] : void 0;
-          yield [key, value];
+  async *iterator(namespace) {
+    const clients = await this.getMasterNodes();
+    for (const client of clients) {
+      const match = namespace ? `${namespace}${this._keyPrefixSeparator}*` : "*";
+      let cursor = "0";
+      do {
+        const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, TYPE: "string" });
+        cursor = result.cursor.toString();
+        let { keys } = result;
+        if (!namespace && !this._noNamespaceAffectsAll) {
+          keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
         }
-      }
-    } while (cursor !== "0");
+        if (keys.length > 0) {
+          const values = await this.mget(keys);
+          for (const i of keys.keys()) {
+            const key = this.getKeyWithoutPrefix(keys[i], namespace);
+            const value = values[i];
+            yield [key, value];
+          }
+        }
+      } while (cursor !== "0");
+    }
   }
   /**
    * Clear all keys in the store.
@@ -344,38 +362,95 @@ var KeyvRedis = class extends EventEmitter {
    * @returns {Promise<void>}
    */
   async clear() {
-    await (this.isCluster() ? this.clearNamespaceCluster(this._namespace) : this.clearNamespace(this._namespace));
-  }
-  async clearNamespace(namespace) {
     try {
-      let cursor = "0";
-      const batchSize = this._clearBatchSize;
-      const match = namespace ? `${namespace}${this._keyPrefixSeparator}*` : "*";
-      const client = await this.getClient();
-      do {
-        const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, COUNT: batchSize, TYPE: "string" });
-        cursor = result.cursor.toString();
-        let { keys } = result;
-        if (keys.length === 0) {
-          continue;
-        }
-        if (!namespace) {
-          keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
+      const clients = await this.getMasterNodes();
+      await Promise.all(clients.map(async (client) => {
+        if (!this._namespace && this._noNamespaceAffectsAll) {
+          await client.flushDb();
+          return;
         }
-        if (keys.length > 0) {
-          if (this._useUnlink) {
-            await client.unlink(keys);
-          } else {
-            await client.del(keys);
+        let cursor = "0";
+        const batchSize = this._clearBatchSize;
+        const match = this._namespace ? `${this._namespace}${this._keyPrefixSeparator}*` : "*";
+        const deletePromises = [];
+        do {
+          const result = await client.scan(Number.parseInt(cursor, 10), { MATCH: match, COUNT: batchSize, TYPE: "string" });
+          cursor = result.cursor.toString();
+          let { keys } = result;
+          if (keys.length === 0) {
+            continue;
           }
-        }
-      } while (cursor !== "0");
+          if (!this._namespace) {
+            keys = keys.filter((key) => !key.includes(this._keyPrefixSeparator));
+          }
+          deletePromises.push(this.clearWithClusterSupport(keys));
+        } while (cursor !== "0");
+        await Promise.all(deletePromises);
+      }));
     } catch (error) {
       this.emit("error", error);
     }
   }
-  async clearNamespaceCluster(namespace) {
-    throw new Error("Clearing all keys in a cluster is not supported.");
+  /**
+   * Get many keys. If the instance is a cluster, it will do multiple MGET calls
+   * by separating the keys by slot to solve the CROSS-SLOT restriction.
+   */
+  async mget(keys) {
+    const slotMap = this.getSlotMap(keys);
+    const valueMap = /* @__PURE__ */ new Map();
+    await Promise.all(Array.from(slotMap.entries(), async ([slot, keys2]) => {
+      const client = await this.getSlotMaster(slot);
+      const values = await client.mGet(keys2);
+      for (const [index, value] of values.entries()) {
+        valueMap.set(keys2[index], value ?? void 0);
+      }
+    }));
+    return keys.map((key) => valueMap.get(key));
+  }
+  /**
+   * Clear all keys in the store with a specific namespace. If the instance is a cluster, it will clear all keys
+   * by separating the keys by slot to solve the CROSS-SLOT restriction.
+   */
+  async clearWithClusterSupport(keys) {
+    if (keys.length > 0) {
+      const slotMap = this.getSlotMap(keys);
+      await Promise.all(Array.from(slotMap.entries(), async ([slot, keys2]) => {
+        const client = await this.getSlotMaster(slot);
+        return this._useUnlink ? client.unlink(keys2) : client.del(keys2);
+      }));
+    }
+  }
+  /**
+   * Returns the master node client for a given slot or the instance's client if it's not a cluster.
+   */
+  async getSlotMaster(slot) {
+    const connection = await this.getClient();
+    if (this.isCluster()) {
+      const cluster = connection;
+      const mainNode = cluster.slots[slot].master;
+      return cluster.nodeClient(mainNode);
+    }
+    return connection;
+  }
+  /**
+   * Group keys by their slot.
+   *
+   * @param {string[]} keys - the keys to group
+   * @returns {Map<number, string[]>} - map of slot to keys
+   */
+  getSlotMap(keys) {
+    const slotMap = /* @__PURE__ */ new Map();
+    if (this.isCluster()) {
+      for (const key of keys) {
+        const slot = calculateSlot(key);
+        const slotKeys = slotMap.get(slot) ?? [];
+        slotKeys.push(key);
+        slotMap.set(slot, slotKeys);
+      }
+    } else {
+      slotMap.set(0, keys);
+    }
+    return slotMap;
   }
   isClientCluster(client) {
     if (client.options === void 0 && client.scan === void 0) {
@@ -399,6 +474,9 @@ var KeyvRedis = class extends EventEmitter {
     if (options.useUnlink !== void 0) {
       this._useUnlink = options.useUnlink;
     }
+    if (options.noNamespaceAffectsAll !== void 0) {
+      this._noNamespaceAffectsAll = options.noNamespaceAffectsAll;
+    }
   }
   initClient() {
     this._client.on("error", (error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyv/redis",
-  "version": "4.0.2",
+  "version": "4.2.0",
   "description": "Redis storage adapter for Keyv",
   "type": "module",
   "main": "dist/index.cjs",
@@ -34,17 +34,18 @@
   },
   "homepage": "https://github.com/jaredwray/keyv",
   "dependencies": {
-    "keyv": "*",
-    "redis": "^4.7.0"
+    "cluster-key-slot": "^1.1.2",
+    "redis": "^4.7.0",
+    "keyv": "^5.2.2"
   },
   "devDependencies": {
-    "@keyv/test-suite": "*",
-    "@vitest/coverage-v8": "^2.1.5",
+    "@vitest/coverage-v8": "^2.1.8",
     "rimraf": "^6.0.1",
     "timekeeper": "^2.3.1",
     "tsd": "^0.31.2",
-    "vitest": "^2.1.5",
-    "xo": "^0.59.3"
+    "vitest": "^2.1.8",
+    "xo": "^0.60.0",
+    "@keyv/test-suite": "^2.0.3"
   },
   "tsd": {
     "directory": "test"
@@ -58,8 +59,8 @@
   ],
   "scripts": {
     "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
-    "test": "xo --fix && vitest run --coverage",
-    "test:ci": "xo && vitest --run --sequence.setupFiles=list",
+    "test": "xo --fix && vitest run --coverage --typecheck",
+    "test:ci": "xo && vitest --run --sequence.setupFiles=list --typecheck",
     "clean": "rimraf ./node_modules ./coverage ./dist"
   }
 }