@keyv/redis 4.4.1 → 4.6.0

package/README.md

@@ -26,9 +26,10 @@ Redis storage adapter for [Keyv](https://github.com/jaredwray/keyv).
 # Table of Contents
 * [Usage](#usage)
 * [Namespaces](#namespaces)
-* [Typescript](#typescript)
+* [Using Generic Types](#using-generic-types)
 * [Performance Considerations](#performance-considerations)
 * [High Memory Usage on Redis Server](#high-memory-usage-on-redis-server)
+* [Gracefully Handling Errors and Timeouts](#gracefully-handling-errors-and-timeouts)
 * [Using Cacheable with Redis](#using-cacheable-with-redis)
 * [Clustering and TLS Support](#clustering-and-tls-support)
 * [API](#api)
@@ -99,6 +100,87 @@ const keyvRedis = new KeyvRedis(redis);
 const keyv = new Keyv({ store: keyvRedis});
 ```
 
+# Keyv Redis Options
+
+You can pass in options to the `KeyvRedis` constructor. Here are the available options:
+
+```typescript
+export type KeyvRedisOptions = {
+	/**
+	 * Namespace for the current instance.
+	 */
+	namespace?: string;
+	/**
+	 * Separator to use between namespace and key.
+	 */
+	keyPrefixSeparator?: string;
+	/**
+	 * Number of keys to delete in a single batch.
+	 */
+	clearBatchSize?: number;
+	/**
+	 * 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;
+
+	/**
+	 * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+	 * set to true so that it throws an error when trying to connect to the Redis server fails.
+	 */
+	throwOnConnectError?: boolean;
+
+	/**
+	 * This is used to throw an error if at any point there is a failure. Use this if you want to
+	 * ensure that all operations are successful and you want to handle errors. By default, this is
+	 * set to false so that it does not throw an error on every operation and instead emits an error event
+	 * and returns no-op responses.
+	 * @default false
+	 */
+	throwErrors?: boolean;
+
+	/**
+	 * Timeout in milliseconds for the connection. Default is undefined, which uses the default timeout of the Redis client.
+	 * If set, it will throw an error if the connection does not succeed within the specified time.
+   * @default undefined
+	 */
+	connectionTimeout?: number;
+};
+```
+You can pass these options when creating a new `KeyvRedis` instance:
+
+```js
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+const keyvRedis = new KeyvRedis({
+  namespace: 'my-namespace',
+  keyPrefixSeparator: ':',
+  clearBatchSize: 1000,
+  useUnlink: true,
+  noNamespaceAffectsAll: false,
+  connectTimeout: 200
+});
+
+const keyv = new Keyv({ store: keyvRedis });
+```
+
+You can also set these options after the fact by using the `KeyvRedis` instance properties:
+
+```js
+import {createKeyv} from '@keyv/redis';
+
+const keyv = createKeyv('redis://user:pass@localhost:6379');
+keyv.store.namespace = 'my-namespace';
+```
+
+
 # Namespaces
 
 You can set a namespace for your keys. This is useful if you want to manage your keys in a more organized way. Here is an example of how to set a `namespace` with the `store` option:
@@ -120,7 +202,7 @@ 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
+## Using Generic Types
 
 When initializing `KeyvRedis`, you can specify the type of the values you are storing and you can also specify types when calling methods:
 
@@ -129,7 +211,7 @@ import Keyv from 'keyv';
 import KeyvRedis, { createClient } from '@keyv/redis';
 
 
-interface User {
+type User {
   id: number
   name: string
 }
@@ -175,6 +257,40 @@ const keyv = new Keyv(new KeyvRedis('redis://user:pass@localhost:6379', { useUnl
 keyv.useUnlink = false;
 ```
 
+# Gracefully Handling Errors and Timeouts
+
+When using `@keyv/redis`, it is important to handle connection errors gracefully. You can do this by listening to the `error` event on the `KeyvRedis` instance. Here is an example of how to do that:
+
+```js
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+const keyv = new Keyv(new KeyvRedis('redis://user:pass@localhost:6379'));
+keyv.on('error', (error) => {
+  console.error('error', error);
+});
+```
+
+By default, the `KeyvRedis` instance will `throw an error` if the connection fails to connect. You can disable this behavior by setting the `throwOnConnectError` option to `false` when creating the `KeyvRedis` instance:
+
+On `get`, `getMany`, `set`, `setMany`, `delete`, and `deleteMany`, if the connection is lost, it will emit an error and return a no-op value. You can catch this error and handle it accordingly. This is important to ensure that your application does not crash due to a lost connection to Redis.
+
+If you want to handle connection errors, retries, and timeouts more gracefully, you can use the `throwErrors` option. This will throw an error if any operation fails, allowing you to catch it and handle it accordingly:
+
+There is a default `Reconnect Strategy` if you pass in just a `uri` connection string we will automatically create a Redis client for you with the following reconnect strategy:
+
+```typescript
+export const defaultReconnectStrategy = (attempts: number): number | Error => {
+	// Exponential backoff base: double each time, capped at 2s.
+	// Parentheses make it clear we do (2 ** attempts) first, then * 100
+	const backoff = Math.min((2 ** attempts) * 100, 2000);
+
+	// Add random jitter of up to ±50ms to avoid thundering herds:
+	const jitter = (Math.random() - 0.5) * 100;
+
+	return backoff + jitter;
+};
+```
+
 # Using Cacheable with Redis
 
 If you are wanting to see even better performance with Redis, you can use [Cacheable](https://npmjs.org/package/cacheable) which is a multi-layered cache library that has in-memory primary caching and non-blocking secondary caching. Here is an example of how to use it with Redis:

package/dist/index.cjs

@@ -31,25 +31,39 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Keyv: () => import_keyv2.Keyv,
+  RedisErrorMessages: () => RedisErrorMessages,
   createClient: () => import_client2.createClient,
   createCluster: () => import_client2.createCluster,
   createKeyv: () => createKeyv,
-  default: () => KeyvRedis
+  default: () => KeyvRedis,
+  defaultReconnectStrategy: () => defaultReconnectStrategy
 });
 module.exports = __toCommonJS(index_exports);
-var import_node_events = __toESM(require("events"), 1);
 var import_client = require("@redis/client");
+var import_hookified = require("hookified");
 var import_keyv = require("keyv");
 var import_cluster_key_slot = __toESM(require("cluster-key-slot"), 1);
 var import_client2 = require("@redis/client");
 var import_keyv2 = require("keyv");
-var KeyvRedis = class extends import_node_events.default {
+var RedisErrorMessages = /* @__PURE__ */ ((RedisErrorMessages2) => {
+  RedisErrorMessages2["RedisClientNotConnectedThrown"] = "Redis client is not connected or has failed to connect. This is thrown because throwOnConnectError is set to true.";
+  return RedisErrorMessages2;
+})(RedisErrorMessages || {});
+var defaultReconnectStrategy = (attempts) => {
+  const backoff = Math.min(2 ** attempts * 100, 2e3);
+  const jitter = (Math.random() - 0.5) * 100;
+  return backoff + jitter;
+};
+var KeyvRedis = class extends import_hookified.Hookified {
   _client = (0, import_client.createClient)();
   _namespace;
   _keyPrefixSeparator = "::";
   _clearBatchSize = 1e3;
   _useUnlink = true;
   _noNamespaceAffectsAll = false;
+  _throwOnConnectError = true;
+  _throwErrors = false;
+  _connectionTimeout;
   /**
    * 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.
@@ -57,9 +71,13 @@ var KeyvRedis = class extends import_node_events.default {
    */
   constructor(connect, options) {
     super();
+    const socket = {
+      reconnectStrategy: defaultReconnectStrategy
+      // Default timeout for the connection
+    };
     if (connect) {
       if (typeof connect === "string") {
-        this._client = (0, import_client.createClient)({ url: connect });
+        this._client = (0, import_client.createClient)({ url: connect, socket });
       } else if (connect.connect !== void 0) {
         this._client = this.isClientCluster(connect) ? connect : connect;
       } else if (connect instanceof Object) {
@@ -98,6 +116,10 @@ var KeyvRedis = class extends import_node_events.default {
       keyPrefixSeparator: this._keyPrefixSeparator,
       clearBatchSize: this._clearBatchSize,
       noNamespaceAffectsAll: this._noNamespaceAffectsAll,
+      useUnlink: this._useUnlink,
+      throwOnConnectError: this._throwOnConnectError,
+      throwErrors: this._throwErrors,
+      connectionTimeout: this._connectionTimeout,
       dialect: "redis",
       url
     };
@@ -180,17 +202,82 @@ var KeyvRedis = class extends import_node_events.default {
   set noNamespaceAffectsAll(value) {
     this._noNamespaceAffectsAll = value;
   }
+  /**
+   * Get if throwOnConnectError is set to true.
+   * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+   * set to true so that it throws an error when trying to connect to the Redis server fails.
+   * @default true
+   */
+  get throwOnConnectError() {
+    return this._throwOnConnectError;
+  }
+  /**
+   * Set if throwOnConnectError is set to true.
+   * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+   * set to true so that it throws an error when trying to connect to the Redis server fails.
+   */
+  set throwOnConnectError(value) {
+    this._throwOnConnectError = value;
+  }
+  /**
+   * Get if throwErrors is set to true.
+   * This is used to throw an error if at any point there is a failure. Use this if you want to
+   * ensure that all operations are successful and you want to handle errors. By default, this is
+   * set to false so that it does not throw an error on every operation and instead emits an error event
+   * and returns no-op responses.
+   * @default false
+   */
+  get throwErrors() {
+    return this._throwErrors;
+  }
+  /**
+   * Set if throwErrors is set to true.
+   * This is used to throw an error if at any point there is a failure. Use this if you want to
+   * ensure that all operations are successful and you want to handle errors. By default, this is
+   * set to false so that it does not throw an error on every operation and instead emits an error event
+   * and returns no-op responses.
+   */
+  set throwErrors(value) {
+    this._throwErrors = value;
+  }
+  /**
+   * Get the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+   * @default undefined
+   */
+  get connectionTimeout() {
+    return this._connectionTimeout;
+  }
+  /**
+   * Set the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+   * @default undefined
+   */
+  set connectionTimeout(value) {
+    this._connectionTimeout = value;
+  }
   /**
    * Get the Redis URL used to connect to the server. This is used to get a connected client.
    */
   async getClient() {
+    if (this._client.isOpen) {
+      return this._client;
+    }
     try {
-      if (!this._client.isOpen) {
+      if (this._connectionTimeout === void 0) {
         await this._client.connect();
+      } else {
+        await Promise.race([
+          this._client.connect(),
+          this.createTimeoutPromise(this._connectionTimeout)
+        ]);
       }
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnConnectError) {
+        throw new Error("Redis client is not connected or has failed to connect. This is thrown because throwOnConnectError is set to true." /* RedisClientNotConnectedThrown */);
+      }
+      await this.disconnect(true);
     }
+    this.initClient();
     return this._client;
   }
   /**
@@ -201,11 +288,18 @@ var KeyvRedis = class extends import_node_events.default {
    */
   async set(key, value, ttl) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    if (ttl) {
-      await client.set(key, value, { PX: ttl });
-    } else {
-      await client.set(key, value);
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      if (ttl) {
+        await client.set(key, value, { PX: ttl });
+      } else {
+        await client.set(key, value);
+      }
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
     }
   }
   /**
@@ -214,16 +308,23 @@ var KeyvRedis = class extends import_node_events.default {
    */
   async setMany(entries) {
     const client = await this.getClient();
-    const multi = client.multi();
-    for (const { key, value, ttl } of entries) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      if (ttl) {
-        multi.set(prefixedKey, value, { PX: ttl });
-      } else {
-        multi.set(prefixedKey, value);
+    try {
+      const multi = client.multi();
+      for (const { key, value, ttl } of entries) {
+        const prefixedKey = this.createKeyPrefix(key, this._namespace);
+        if (ttl) {
+          multi.set(prefixedKey, value, { PX: ttl });
+        } else {
+          multi.set(prefixedKey, value);
+        }
+      }
+      await multi.exec();
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
       }
     }
-    await multi.exec();
   }
   /**
    * Check if a key exists in the store.
@@ -232,9 +333,17 @@ var KeyvRedis = class extends import_node_events.default {
    */
   async has(key) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    const exists = await client.exists(key);
-    return exists === 1;
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      const exists = await client.exists(key);
+      return exists === 1;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return false;
+    }
   }
   /**
    * Check if many keys exist in the store. This will be done as a single transaction.
@@ -243,13 +352,21 @@ var KeyvRedis = class extends import_node_events.default {
    */
   async hasMany(keys) {
     const client = await this.getClient();
-    const multi = client.multi();
-    for (const key of keys) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      multi.exists(prefixedKey);
+    try {
+      const multi = client.multi();
+      for (const key of keys) {
+        const prefixedKey = this.createKeyPrefix(key, this._namespace);
+        multi.exists(prefixedKey);
+      }
+      const results = await multi.exec();
+      return results.map((result) => result === 1);
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return Array.from({ length: keys.length }).fill(false);
     }
-    const results = await multi.exec();
-    return results.map((result) => result === 1);
   }
   /**
    * Get a value from the store. If the key does not exist, it will return undefined.
@@ -258,12 +375,20 @@ var KeyvRedis = class extends import_node_events.default {
    */
   async get(key) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    const value = await client.get(key);
-    if (value === null) {
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      const value = await client.get(key);
+      if (value === null) {
+        return void 0;
+      }
+      return value;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
       return void 0;
     }
-    return value;
   }
   /**
    * Get many values from the store. If a key does not exist, it will return undefined.
@@ -275,8 +400,16 @@ var KeyvRedis = class extends import_node_events.default {
       return [];
     }
     keys = keys.map((key) => this.createKeyPrefix(key, this._namespace));
-    const values = await this.mget(keys);
-    return values;
+    try {
+      const values = await this.mget(keys);
+      return values;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return Array.from({ length: keys.length }).fill(void 0);
+    }
   }
   /**
    * Delete a key from the store.
@@ -285,10 +418,18 @@ var KeyvRedis = class extends import_node_events.default {
    */
   async delete(key) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    let deleted = 0;
-    deleted = await (this._useUnlink ? client.unlink(key) : client.del(key));
-    return deleted > 0;
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      let deleted = 0;
+      deleted = await (this._useUnlink ? client.unlink(key) : client.del(key));
+      return deleted > 0;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return false;
+    }
   }
   /**
    * Delete many keys from the store. This will be done as a single transaction.
@@ -298,19 +439,26 @@ var KeyvRedis = class extends import_node_events.default {
   async deleteMany(keys) {
     let result = false;
     const client = await this.getClient();
-    const multi = client.multi();
-    for (const key of keys) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      if (this._useUnlink) {
-        multi.unlink(prefixedKey);
-      } else {
-        multi.del(prefixedKey);
+    try {
+      const multi = client.multi();
+      for (const key of keys) {
+        const prefixedKey = this.createKeyPrefix(key, this._namespace);
+        if (this._useUnlink) {
+          multi.unlink(prefixedKey);
+        } else {
+          multi.del(prefixedKey);
+        }
       }
-    }
-    const results = await multi.exec();
-    for (const deleted of results) {
-      if (typeof deleted === "number" && deleted > 0) {
-        result = true;
+      const results = await multi.exec();
+      for (const deleted of results) {
+        if (typeof deleted === "number" && deleted > 0) {
+          result = true;
+        }
+      }
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
       }
     }
     return result;
@@ -520,11 +668,37 @@ var KeyvRedis = class extends import_node_events.default {
     if (options.noNamespaceAffectsAll !== void 0) {
       this._noNamespaceAffectsAll = options.noNamespaceAffectsAll;
     }
+    if (options.throwOnConnectError !== void 0) {
+      this._throwOnConnectError = options.throwOnConnectError;
+    }
+    if (options.throwErrors !== void 0) {
+      this._throwErrors = options.throwErrors;
+    }
+    if (options.connectionTimeout !== void 0) {
+      this._connectionTimeout = options.connectionTimeout;
+    }
   }
   initClient() {
-    this._client.on("error", (error) => {
-      this.emit("error", error);
+    this._client.on("connect", () => {
+      this.emit("connect", this._client);
+    });
+    this._client.on("disconnect", () => {
+      this.emit("disconnect", this._client);
     });
+    this._client.on("reconnecting", (reconnectInfo) => {
+      this.emit("reconnecting", reconnectInfo);
+    });
+  }
+  async createTimeoutPromise(timeoutMs) {
+    return new Promise((_, reject) => (
+      // eslint-disable-next-line no-promise-executor-return
+      setTimeout(
+        () => {
+          reject(new Error(`Redis timed out after ${timeoutMs}ms`));
+        },
+        timeoutMs
+      )
+    ));
   }
 };
 function createKeyv(connect, options) {
@@ -536,7 +710,9 @@ function createKeyv(connect, options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Keyv,
+  RedisErrorMessages,
   createClient,
   createCluster,
-  createKeyv
+  createKeyv,
+  defaultReconnectStrategy
 });

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import EventEmitter from 'node:events';
 import { RedisClientOptions, RedisClusterOptions, RedisClientType, RedisClusterType, RedisModules, RedisFunctions, RedisScripts } from '@redis/client';
 export { RedisClientOptions, RedisClientType, RedisClusterOptions, RedisClusterType, createClient, createCluster } from '@redis/client';
+import { Hookified } from 'hookified';
 import { KeyvStoreAdapter, KeyvEntry, Keyv } from 'keyv';
 export { Keyv } from 'keyv';
 
@@ -27,6 +27,25 @@ type KeyvRedisOptions = {
      * Defaults to `false`.
      */
     noNamespaceAffectsAll?: boolean;
+    /**
+     * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+     * set to true so that it throws an error when trying to connect to the Redis server fails.
+     */
+    throwOnConnectError?: boolean;
+    /**
+     * This is used to throw an error if at any point there is a failure. Use this if you want to
+     * ensure that all operations are successful and you want to handle errors. By default, this is
+     * set to false so that it does not throw an error on every operation and instead emits an error event
+     * and returns no-op responses.
+     * @default false
+     */
+    throwErrors?: boolean;
+    /**
+     * Timeout in milliseconds for the connection. Default is undefined, which uses the default timeout of the Redis client.
+     * If set, it will throw an error if the connection does not succeed within the specified time.
+     * @default undefined
+     */
+    connectionTimeout?: number;
 };
 type KeyvRedisPropertyOptions = KeyvRedisOptions & {
     /**
@@ -52,14 +71,24 @@ type KeyvRedisEntry<T> = {
      */
     ttl?: number;
 };
+declare enum RedisErrorMessages {
+    /**
+     * Error message when the Redis client is not connected and throwOnConnectError is set to true.
+     */
+    RedisClientNotConnectedThrown = "Redis client is not connected or has failed to connect. This is thrown because throwOnConnectError is set to true."
+}
+declare const defaultReconnectStrategy: (attempts: number) => number | Error;
 type RedisClientConnectionType = RedisClientType | RedisClusterType<RedisModules, RedisFunctions, RedisScripts>;
-declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
+declare class KeyvRedis<T> extends Hookified implements KeyvStoreAdapter {
     private _client;
     private _namespace;
     private _keyPrefixSeparator;
     private _clearBatchSize;
     private _useUnlink;
     private _noNamespaceAffectsAll;
+    private _throwOnConnectError;
+    private _throwErrors;
+    private _connectionTimeout;
     /**
      * 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.
@@ -129,6 +158,46 @@ declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
      * Set if not namespace affects all keys.
      */
     set noNamespaceAffectsAll(value: boolean);
+    /**
+     * Get if throwOnConnectError is set to true.
+     * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+     * set to true so that it throws an error when trying to connect to the Redis server fails.
+     * @default true
+     */
+    get throwOnConnectError(): boolean;
+    /**
+     * Set if throwOnConnectError is set to true.
+     * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+     * set to true so that it throws an error when trying to connect to the Redis server fails.
+     */
+    set throwOnConnectError(value: boolean);
+    /**
+     * Get if throwErrors is set to true.
+     * This is used to throw an error if at any point there is a failure. Use this if you want to
+     * ensure that all operations are successful and you want to handle errors. By default, this is
+     * set to false so that it does not throw an error on every operation and instead emits an error event
+     * and returns no-op responses.
+     * @default false
+     */
+    get throwErrors(): boolean;
+    /**
+     * Set if throwErrors is set to true.
+     * This is used to throw an error if at any point there is a failure. Use this if you want to
+     * ensure that all operations are successful and you want to handle errors. By default, this is
+     * set to false so that it does not throw an error on every operation and instead emits an error event
+     * and returns no-op responses.
+     */
+    set throwErrors(value: boolean);
+    /**
+     * Get the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+     * @default undefined
+     */
+    get connectionTimeout(): number | undefined;
+    /**
+     * Set the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+     * @default undefined
+     */
+    set connectionTimeout(value: number | undefined);
     /**
      * Get the Redis URL used to connect to the server. This is used to get a connected client.
      */
@@ -251,6 +320,7 @@ declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
     private isClientCluster;
     private setOptions;
     private initClient;
+    private createTimeoutPromise;
 }
 /**
  * Will create a Keyv instance with the Redis adapter. This will also set the namespace and useKeyPrefix to false.
@@ -260,4 +330,4 @@ declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
  */
 declare function createKeyv(connect?: string | RedisClientOptions | RedisClientType, options?: KeyvRedisOptions): Keyv;
 
-export { type KeyvRedisEntry, type KeyvRedisOptions, type KeyvRedisPropertyOptions, type RedisClientConnectionType, createKeyv, KeyvRedis as default };
+export { type KeyvRedisEntry, type KeyvRedisOptions, type KeyvRedisPropertyOptions, type RedisClientConnectionType, RedisErrorMessages, createKeyv, KeyvRedis as default, defaultReconnectStrategy };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import EventEmitter from 'node:events';
 import { RedisClientOptions, RedisClusterOptions, RedisClientType, RedisClusterType, RedisModules, RedisFunctions, RedisScripts } from '@redis/client';
 export { RedisClientOptions, RedisClientType, RedisClusterOptions, RedisClusterType, createClient, createCluster } from '@redis/client';
+import { Hookified } from 'hookified';
 import { KeyvStoreAdapter, KeyvEntry, Keyv } from 'keyv';
 export { Keyv } from 'keyv';
 
@@ -27,6 +27,25 @@ type KeyvRedisOptions = {
      * Defaults to `false`.
      */
     noNamespaceAffectsAll?: boolean;
+    /**
+     * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+     * set to true so that it throws an error when trying to connect to the Redis server fails.
+     */
+    throwOnConnectError?: boolean;
+    /**
+     * This is used to throw an error if at any point there is a failure. Use this if you want to
+     * ensure that all operations are successful and you want to handle errors. By default, this is
+     * set to false so that it does not throw an error on every operation and instead emits an error event
+     * and returns no-op responses.
+     * @default false
+     */
+    throwErrors?: boolean;
+    /**
+     * Timeout in milliseconds for the connection. Default is undefined, which uses the default timeout of the Redis client.
+     * If set, it will throw an error if the connection does not succeed within the specified time.
+     * @default undefined
+     */
+    connectionTimeout?: number;
 };
 type KeyvRedisPropertyOptions = KeyvRedisOptions & {
     /**
@@ -52,14 +71,24 @@ type KeyvRedisEntry<T> = {
      */
     ttl?: number;
 };
+declare enum RedisErrorMessages {
+    /**
+     * Error message when the Redis client is not connected and throwOnConnectError is set to true.
+     */
+    RedisClientNotConnectedThrown = "Redis client is not connected or has failed to connect. This is thrown because throwOnConnectError is set to true."
+}
+declare const defaultReconnectStrategy: (attempts: number) => number | Error;
 type RedisClientConnectionType = RedisClientType | RedisClusterType<RedisModules, RedisFunctions, RedisScripts>;
-declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
+declare class KeyvRedis<T> extends Hookified implements KeyvStoreAdapter {
     private _client;
     private _namespace;
     private _keyPrefixSeparator;
     private _clearBatchSize;
     private _useUnlink;
     private _noNamespaceAffectsAll;
+    private _throwOnConnectError;
+    private _throwErrors;
+    private _connectionTimeout;
     /**
      * 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.
@@ -129,6 +158,46 @@ declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
      * Set if not namespace affects all keys.
      */
     set noNamespaceAffectsAll(value: boolean);
+    /**
+     * Get if throwOnConnectError is set to true.
+     * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+     * set to true so that it throws an error when trying to connect to the Redis server fails.
+     * @default true
+     */
+    get throwOnConnectError(): boolean;
+    /**
+     * Set if throwOnConnectError is set to true.
+     * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+     * set to true so that it throws an error when trying to connect to the Redis server fails.
+     */
+    set throwOnConnectError(value: boolean);
+    /**
+     * Get if throwErrors is set to true.
+     * This is used to throw an error if at any point there is a failure. Use this if you want to
+     * ensure that all operations are successful and you want to handle errors. By default, this is
+     * set to false so that it does not throw an error on every operation and instead emits an error event
+     * and returns no-op responses.
+     * @default false
+     */
+    get throwErrors(): boolean;
+    /**
+     * Set if throwErrors is set to true.
+     * This is used to throw an error if at any point there is a failure. Use this if you want to
+     * ensure that all operations are successful and you want to handle errors. By default, this is
+     * set to false so that it does not throw an error on every operation and instead emits an error event
+     * and returns no-op responses.
+     */
+    set throwErrors(value: boolean);
+    /**
+     * Get the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+     * @default undefined
+     */
+    get connectionTimeout(): number | undefined;
+    /**
+     * Set the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+     * @default undefined
+     */
+    set connectionTimeout(value: number | undefined);
     /**
      * Get the Redis URL used to connect to the server. This is used to get a connected client.
      */
@@ -251,6 +320,7 @@ declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
     private isClientCluster;
     private setOptions;
     private initClient;
+    private createTimeoutPromise;
 }
 /**
  * Will create a Keyv instance with the Redis adapter. This will also set the namespace and useKeyPrefix to false.
@@ -260,4 +330,4 @@ declare class KeyvRedis<T> extends EventEmitter implements KeyvStoreAdapter {
  */
 declare function createKeyv(connect?: string | RedisClientOptions | RedisClientType, options?: KeyvRedisOptions): Keyv;
 
-export { type KeyvRedisEntry, type KeyvRedisOptions, type KeyvRedisPropertyOptions, type RedisClientConnectionType, createKeyv, KeyvRedis as default };
+export { type KeyvRedisEntry, type KeyvRedisOptions, type KeyvRedisPropertyOptions, type RedisClientConnectionType, RedisErrorMessages, createKeyv, KeyvRedis as default, defaultReconnectStrategy };

package/dist/index.js

@@ -1,9 +1,9 @@
 // src/index.ts
-import EventEmitter from "events";
 import {
   createClient,
   createCluster
 } from "@redis/client";
+import { Hookified } from "hookified";
 import { Keyv } from "keyv";
 import calculateSlot from "cluster-key-slot";
 import {
@@ -13,13 +13,25 @@ import {
 import {
   Keyv as Keyv2
 } from "keyv";
-var KeyvRedis = class extends EventEmitter {
+var RedisErrorMessages = /* @__PURE__ */ ((RedisErrorMessages2) => {
+  RedisErrorMessages2["RedisClientNotConnectedThrown"] = "Redis client is not connected or has failed to connect. This is thrown because throwOnConnectError is set to true.";
+  return RedisErrorMessages2;
+})(RedisErrorMessages || {});
+var defaultReconnectStrategy = (attempts) => {
+  const backoff = Math.min(2 ** attempts * 100, 2e3);
+  const jitter = (Math.random() - 0.5) * 100;
+  return backoff + jitter;
+};
+var KeyvRedis = class extends Hookified {
   _client = createClient();
   _namespace;
   _keyPrefixSeparator = "::";
   _clearBatchSize = 1e3;
   _useUnlink = true;
   _noNamespaceAffectsAll = false;
+  _throwOnConnectError = true;
+  _throwErrors = false;
+  _connectionTimeout;
   /**
    * 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.
@@ -27,9 +39,13 @@ var KeyvRedis = class extends EventEmitter {
    */
   constructor(connect, options) {
     super();
+    const socket = {
+      reconnectStrategy: defaultReconnectStrategy
+      // Default timeout for the connection
+    };
     if (connect) {
       if (typeof connect === "string") {
-        this._client = createClient({ url: connect });
+        this._client = createClient({ url: connect, socket });
       } else if (connect.connect !== void 0) {
         this._client = this.isClientCluster(connect) ? connect : connect;
       } else if (connect instanceof Object) {
@@ -68,6 +84,10 @@ var KeyvRedis = class extends EventEmitter {
       keyPrefixSeparator: this._keyPrefixSeparator,
       clearBatchSize: this._clearBatchSize,
       noNamespaceAffectsAll: this._noNamespaceAffectsAll,
+      useUnlink: this._useUnlink,
+      throwOnConnectError: this._throwOnConnectError,
+      throwErrors: this._throwErrors,
+      connectionTimeout: this._connectionTimeout,
       dialect: "redis",
       url
     };
@@ -150,17 +170,82 @@ var KeyvRedis = class extends EventEmitter {
   set noNamespaceAffectsAll(value) {
     this._noNamespaceAffectsAll = value;
   }
+  /**
+   * Get if throwOnConnectError is set to true.
+   * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+   * set to true so that it throws an error when trying to connect to the Redis server fails.
+   * @default true
+   */
+  get throwOnConnectError() {
+    return this._throwOnConnectError;
+  }
+  /**
+   * Set if throwOnConnectError is set to true.
+   * This is used to throw an error if the client is not connected when trying to connect. By default, this is
+   * set to true so that it throws an error when trying to connect to the Redis server fails.
+   */
+  set throwOnConnectError(value) {
+    this._throwOnConnectError = value;
+  }
+  /**
+   * Get if throwErrors is set to true.
+   * This is used to throw an error if at any point there is a failure. Use this if you want to
+   * ensure that all operations are successful and you want to handle errors. By default, this is
+   * set to false so that it does not throw an error on every operation and instead emits an error event
+   * and returns no-op responses.
+   * @default false
+   */
+  get throwErrors() {
+    return this._throwErrors;
+  }
+  /**
+   * Set if throwErrors is set to true.
+   * This is used to throw an error if at any point there is a failure. Use this if you want to
+   * ensure that all operations are successful and you want to handle errors. By default, this is
+   * set to false so that it does not throw an error on every operation and instead emits an error event
+   * and returns no-op responses.
+   */
+  set throwErrors(value) {
+    this._throwErrors = value;
+  }
+  /**
+   * Get the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+   * @default undefined
+   */
+  get connectionTimeout() {
+    return this._connectionTimeout;
+  }
+  /**
+   * Set the connection timeout in milliseconds such as 5000 (5 seconds). Default is undefined. If undefined, it will use the default.
+   * @default undefined
+   */
+  set connectionTimeout(value) {
+    this._connectionTimeout = value;
+  }
   /**
    * Get the Redis URL used to connect to the server. This is used to get a connected client.
    */
   async getClient() {
+    if (this._client.isOpen) {
+      return this._client;
+    }
     try {
-      if (!this._client.isOpen) {
+      if (this._connectionTimeout === void 0) {
         await this._client.connect();
+      } else {
+        await Promise.race([
+          this._client.connect(),
+          this.createTimeoutPromise(this._connectionTimeout)
+        ]);
       }
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnConnectError) {
+        throw new Error("Redis client is not connected or has failed to connect. This is thrown because throwOnConnectError is set to true." /* RedisClientNotConnectedThrown */);
+      }
+      await this.disconnect(true);
     }
+    this.initClient();
     return this._client;
   }
   /**
@@ -171,11 +256,18 @@ var KeyvRedis = class extends EventEmitter {
    */
   async set(key, value, ttl) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    if (ttl) {
-      await client.set(key, value, { PX: ttl });
-    } else {
-      await client.set(key, value);
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      if (ttl) {
+        await client.set(key, value, { PX: ttl });
+      } else {
+        await client.set(key, value);
+      }
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
     }
   }
   /**
@@ -184,16 +276,23 @@ var KeyvRedis = class extends EventEmitter {
    */
   async setMany(entries) {
     const client = await this.getClient();
-    const multi = client.multi();
-    for (const { key, value, ttl } of entries) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      if (ttl) {
-        multi.set(prefixedKey, value, { PX: ttl });
-      } else {
-        multi.set(prefixedKey, value);
+    try {
+      const multi = client.multi();
+      for (const { key, value, ttl } of entries) {
+        const prefixedKey = this.createKeyPrefix(key, this._namespace);
+        if (ttl) {
+          multi.set(prefixedKey, value, { PX: ttl });
+        } else {
+          multi.set(prefixedKey, value);
+        }
+      }
+      await multi.exec();
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
       }
     }
-    await multi.exec();
   }
   /**
    * Check if a key exists in the store.
@@ -202,9 +301,17 @@ var KeyvRedis = class extends EventEmitter {
    */
   async has(key) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    const exists = await client.exists(key);
-    return exists === 1;
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      const exists = await client.exists(key);
+      return exists === 1;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return false;
+    }
   }
   /**
    * Check if many keys exist in the store. This will be done as a single transaction.
@@ -213,13 +320,21 @@ var KeyvRedis = class extends EventEmitter {
    */
   async hasMany(keys) {
     const client = await this.getClient();
-    const multi = client.multi();
-    for (const key of keys) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      multi.exists(prefixedKey);
+    try {
+      const multi = client.multi();
+      for (const key of keys) {
+        const prefixedKey = this.createKeyPrefix(key, this._namespace);
+        multi.exists(prefixedKey);
+      }
+      const results = await multi.exec();
+      return results.map((result) => result === 1);
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return Array.from({ length: keys.length }).fill(false);
     }
-    const results = await multi.exec();
-    return results.map((result) => result === 1);
   }
   /**
    * Get a value from the store. If the key does not exist, it will return undefined.
@@ -228,12 +343,20 @@ var KeyvRedis = class extends EventEmitter {
    */
   async get(key) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    const value = await client.get(key);
-    if (value === null) {
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      const value = await client.get(key);
+      if (value === null) {
+        return void 0;
+      }
+      return value;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
       return void 0;
     }
-    return value;
   }
   /**
    * Get many values from the store. If a key does not exist, it will return undefined.
@@ -245,8 +368,16 @@ var KeyvRedis = class extends EventEmitter {
       return [];
     }
     keys = keys.map((key) => this.createKeyPrefix(key, this._namespace));
-    const values = await this.mget(keys);
-    return values;
+    try {
+      const values = await this.mget(keys);
+      return values;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return Array.from({ length: keys.length }).fill(void 0);
+    }
   }
   /**
    * Delete a key from the store.
@@ -255,10 +386,18 @@ var KeyvRedis = class extends EventEmitter {
    */
   async delete(key) {
     const client = await this.getClient();
-    key = this.createKeyPrefix(key, this._namespace);
-    let deleted = 0;
-    deleted = await (this._useUnlink ? client.unlink(key) : client.del(key));
-    return deleted > 0;
+    try {
+      key = this.createKeyPrefix(key, this._namespace);
+      let deleted = 0;
+      deleted = await (this._useUnlink ? client.unlink(key) : client.del(key));
+      return deleted > 0;
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
+      }
+      return false;
+    }
   }
   /**
    * Delete many keys from the store. This will be done as a single transaction.
@@ -268,19 +407,26 @@ var KeyvRedis = class extends EventEmitter {
   async deleteMany(keys) {
     let result = false;
     const client = await this.getClient();
-    const multi = client.multi();
-    for (const key of keys) {
-      const prefixedKey = this.createKeyPrefix(key, this._namespace);
-      if (this._useUnlink) {
-        multi.unlink(prefixedKey);
-      } else {
-        multi.del(prefixedKey);
+    try {
+      const multi = client.multi();
+      for (const key of keys) {
+        const prefixedKey = this.createKeyPrefix(key, this._namespace);
+        if (this._useUnlink) {
+          multi.unlink(prefixedKey);
+        } else {
+          multi.del(prefixedKey);
+        }
       }
-    }
-    const results = await multi.exec();
-    for (const deleted of results) {
-      if (typeof deleted === "number" && deleted > 0) {
-        result = true;
+      const results = await multi.exec();
+      for (const deleted of results) {
+        if (typeof deleted === "number" && deleted > 0) {
+          result = true;
+        }
+      }
+    } catch (error) {
+      this.emit("error", error);
+      if (this._throwErrors) {
+        throw error;
       }
     }
     return result;
@@ -490,11 +636,37 @@ var KeyvRedis = class extends EventEmitter {
     if (options.noNamespaceAffectsAll !== void 0) {
       this._noNamespaceAffectsAll = options.noNamespaceAffectsAll;
     }
+    if (options.throwOnConnectError !== void 0) {
+      this._throwOnConnectError = options.throwOnConnectError;
+    }
+    if (options.throwErrors !== void 0) {
+      this._throwErrors = options.throwErrors;
+    }
+    if (options.connectionTimeout !== void 0) {
+      this._connectionTimeout = options.connectionTimeout;
+    }
   }
   initClient() {
-    this._client.on("error", (error) => {
-      this.emit("error", error);
+    this._client.on("connect", () => {
+      this.emit("connect", this._client);
+    });
+    this._client.on("disconnect", () => {
+      this.emit("disconnect", this._client);
     });
+    this._client.on("reconnecting", (reconnectInfo) => {
+      this.emit("reconnecting", reconnectInfo);
+    });
+  }
+  async createTimeoutPromise(timeoutMs) {
+    return new Promise((_, reject) => (
+      // eslint-disable-next-line no-promise-executor-return
+      setTimeout(
+        () => {
+          reject(new Error(`Redis timed out after ${timeoutMs}ms`));
+        },
+        timeoutMs
+      )
+    ));
   }
 };
 function createKeyv(connect, options) {
@@ -505,8 +677,10 @@ function createKeyv(connect, options) {
 }
 export {
   Keyv2 as Keyv,
+  RedisErrorMessages,
   createClient2 as createClient,
   createCluster2 as createCluster,
   createKeyv,
-  KeyvRedis as default
+  KeyvRedis as default,
+  defaultReconnectStrategy
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyv/redis",
-  "version": "4.4.1",
+  "version": "4.6.0",
   "description": "Redis storage adapter for Keyv",
   "type": "module",
   "main": "dist/index.cjs",
@@ -35,18 +35,20 @@
   "homepage": "https://github.com/jaredwray/keyv",
   "dependencies": {
     "@redis/client": "^1.6.0",
-    "cluster-key-slot": "^1.1.2"
+    "cluster-key-slot": "^1.1.2",
+    "hookified": "^1.10.0"
   },
   "peerDependencies": {
     "keyv": "^5.3.4"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^3.2.3",
+    "@faker-js/faker": "^9.9.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
     "timekeeper": "^2.3.1",
     "tsd": "^0.32.0",
-    "vitest": "^3.2.3",
-    "xo": "^1.1.0",
+    "vitest": "^3.2.4",
+    "xo": "^1.1.1",
     "@keyv/test-suite": "^2.0.8"
   },
   "tsd": {