@keyv/redis 4.5.0 → 5.0.0

package/README.md

@@ -25,11 +25,15 @@ Redis storage adapter for [Keyv](https://github.com/jaredwray/keyv).
 
 # Table of Contents
 * [Usage](#usage)
+* [Migrating from v4 to v5](#migrating-from-v4-to-v5)
+* [Using the createKeyv function](#using-the-createkeyv-function)
+* [Using the createKeyvNonBlocking function](#using-the-createkeyvnonblocking-function)
 * [Namespaces](#namespaces)
+* [Fixing Double Prefixing of Keys](#fixing-double-prefixing-of-keys)
 * [Using Generic Types](#using-generic-types)
 * [Performance Considerations](#performance-considerations)
 * [High Memory Usage on Redis Server](#high-memory-usage-on-redis-server)
-* [Gracefully Handling Connection Errors, Retries, and Timeouts](#gracefully-handling-connection-errors-retries-and-timeouts)
+* [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)
@@ -100,6 +104,10 @@ const keyvRedis = new KeyvRedis(redis);
 const keyv = new Keyv({ store: keyvRedis});
 ```
 
+# Migrating from v4 to v5
+
+The major change from v4 to v5 is that we are now using v5 of the `@redis/client` library which has a new API. This means that some methods have changed but it should be a drop-in replacement for most use cases.
+
 # Keyv Redis Options
 
 You can pass in options to the `KeyvRedis` constructor. Here are the available options:
@@ -131,10 +139,26 @@ export type KeyvRedisOptions = {
 	noNamespaceAffectsAll?: boolean;
 
 	/**
-	 * Timeout for connecting to Redis in milliseconds. This is used to prevent hanging indefinitely when connecting to Redis.
-	 * Defaults to `200`.
+	 * 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.
 	 */
-	connectTimeout?: number;
+	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
+	 */
+	throwOnErrors?: 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:
@@ -164,6 +188,30 @@ const keyv = createKeyv('redis://user:pass@localhost:6379');
 keyv.store.namespace = 'my-namespace';
 ```
 
+# Using the `createKeyv` function
+
+The `createKeyv` function is a convenience function that creates a new `Keyv` instance with the `@keyv/redis` store. It automatically sets the `useKeyPrefix` option to `false`. Here is an example of how to use it:
+
+```js
+import { createKeyv } from '@keyv/redis';
+const keyv = createKeyv('redis://user:pass@localhost:6379');
+```
+
+To use a namespace you can do it here and this will set Keyv up correctly to avoid the double namespace issue:
+
+```js
+import { createKeyv } from '@keyv/redis';
+const keyv = createKeyv('redis://user:pass@localhost:6379', {namespace: 'my-namespace'});
+```
+
+# Using the `createKeyvNonBlocking` function
+
+The `createKeyvNonBlocking` function is a convenience function that creates a new `Keyv` instance with the `@keyv/redis` store does what `createKeyv` does but also disables throwing errors, removes the offline queue redis functionality, and reconnect strategy so that when used as a secondary cache in libraries such as [cacheable](https://npmjs.org/package/cacheable) it does not block the primary cache. This is useful when you want to use Redis as a secondary cache and do not want to block the primary cache on connection errors or timeouts when using `nonBlocking`. Here is an example of how to use it:
+
+```js
+import { createKeyvNonBlocking } from '@keyv/redis';
+const keyv = createKeyvNonBlocking('redis://user:pass@localhost:6379');
+```
 
 # Namespaces
 
@@ -175,10 +223,17 @@ import KeyvRedis, { createClient } from '@keyv/redis';
 
 const redis = createClient('redis://user:pass@localhost:6379');
 const keyvRedis = new KeyvRedis(redis);
-const keyv = new Keyv({ store: keyvRedis, namespace: 'my-namespace' });
+const keyv = new Keyv({ store: keyvRedis, namespace: 'my-namespace', useKeyPrefix: false });
 ```
 
-This will prefix all keys with `my-namespace:`. You can also set the namespace after the fact:
+To make this easier, you can use the `createKeyv` function which will automatically set the `namespace` option to the `KeyvRedis` instance:
+
+```js
+import { createKeyv } from '@keyv/redis';
+const keyv = createKeyv('redis://user:pass@localhost:6379', { namespace: 'my-namespace' });
+```
+
+This will prefix all keys with `my-namespace:` and will also set `useKeyPrefix` to `false`. This is done to avoid double prefixing of keys as we transition out of the legacy behavior in Keyv. You can also set the namespace after the fact:
 
 ```js
 keyv.namespace = 'my-namespace';
@@ -186,6 +241,24 @@ 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.
 
+# Fixing Double Prefixing of Keys
+
+If you are using `Keyv` with `@keyv/redis` as the storage adapter, you may notice that keys are being prefixed twice. This is because `Keyv` has a default prefixing behavior that is applied to all keys. To fix this, you can set the `useKeyPrefix` option to `false` when creating the `Keyv` instance:
+
+```js
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+const keyv = new Keyv(new KeyvRedis('redis://user:pass@localhost:6379'), { useKeyPrefix: false });
+```
+
+To make this easier, you can use the `createKeyv` function which will automatically set the `useKeyPrefix` option to `false`:
+
+```js
+import { createKeyv } from '@keyv/redis';
+const keyv = createKeyv('redis://user:pass@localhost:6379');
+```
+
 ## 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:
@@ -241,7 +314,7 @@ const keyv = new Keyv(new KeyvRedis('redis://user:pass@localhost:6379', { useUnl
 keyv.useUnlink = false;
 ```
 
-# Gracefully Handling Connection Errors, Retries, and Timeouts
+# 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:
 
@@ -254,11 +327,23 @@ keyv.on('error', (error) => {
 });
 ```
 
-We also attempt to connect to Redis and have a `connectTimeout` option that defaults to `200ms`. If the connection is not established within this time, it will emit an error. You can catch this error and handle it accordingly.
+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. If you want this to throw you will need to also set the Keyv instance to `throwOnErrors: true`:
+
+```js
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+const keyv = new Keyv(new KeyvRedis('redis://bad-uri:1111', { throwOnConnectError: false }));
+keyv.throwOnErrors = true; // This will throw an error if the connection fails
+
+await keyv.set('key', 'value'); // this will throw the connection error only.
+```
+
+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.
 
-On `get`, `getMany`, `set`, `setMany`, `delete`, `deleteMany`, and `clear` methods, 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 `throwOnErrors` option. This will throw an error if any operation fails, allowing you to catch it and handle it accordingly:
 
-If you pass in just a `uri` connection string we will automatically create a Redis client for you with the following reconnect strategy:
+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 => {