@keyv/redis 4.1.0 → 4.3.0

package/README.md

@@ -26,11 +26,13 @@ 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)
 * [Clustering and TLS Support](#clustering-and-tls-support)
 * [API](#api)
+* [Using Custom Redis Client Events](#using-custom-redis-client-events)
 * [Migrating from v3 to v4](#migrating-from-v3-to-v4)
 * [About Redis Sets and its Support in v4](#about-redis-sets-and-its-support-in-v4)
 * [License](#license)
@@ -110,6 +112,34 @@ 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:
@@ -225,9 +255,34 @@ const keyv = new Keyv({ store: new KeyvRedis(tlsOptions) });
 * **delete** - Delete a key.
 * **deleteMany** - Delete multiple keys.
 * **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.
+* **disconnect** - Disconnect from the Redis server using `Quit` command. If you set `force` to `true` it will force the disconnect.
 * **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`.
 
+# Using Custom Redis Client Events
+
+Keyv by default supports the `error` event across all storage adapters. If you want to listen to other events you can do so by accessing the `client` property of the `KeyvRedis` instance. Here is an example of how to do that:
+
+```js
+import {createKeyv} from '@keyv/redis';
+
+const keyv = createKeyv('redis://user:pass@localhost:6379');
+const redisClient = keyv.store.client;
+
+redisClient.on('connect', () => {
+  console.log('Redis client connected');
+});
+
+redisClient.on('reconnecting', () => {
+  console.log('Redis client reconnecting');
+});
+
+redisClient.on('end', () => {
+  console.log('Redis client disconnected');
+});
+```
+
+Here are some of the events you can listen to: https://www.npmjs.com/package/redis#events
+
 # Migrating from v3 to v4
 
 Overall the API is the same as v3 with additional options and performance improvements. Here are the main changes:

package/dist/index.cjs

@@ -28,15 +28,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   Keyv: () => import_keyv2.Keyv,
   createClient: () => import_redis2.createClient,
   createCluster: () => import_redis2.createCluster,
   createKeyv: () => createKeyv,
   default: () => KeyvRedis
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 var import_node_events = __toESM(require("events"), 1);
 var import_redis = require("redis");
 var import_keyv = require("keyv");
@@ -199,7 +199,7 @@ var KeyvRedis = class extends import_node_events.default {
   }
   /**
    * Will set many key value pairs in the store. TTL is in milliseconds. This will be done as a single transaction.
-   * @param {Array<KeyvRedisEntry<string>>} entries - the key value pairs to set with optional ttl
+   * @param {KeyvEntry[]} entries - the key value pairs to set with optional ttl
    */
   async setMany(entries) {
     const client = await this.getClient();
@@ -213,6 +213,7 @@ var KeyvRedis = class extends import_node_events.default {
       }
     }
     await multi.exec();
+    return entries.map(() => true);
   }
   /**
    * Check if a key exists in the store.
@@ -307,10 +308,12 @@ var KeyvRedis = class extends import_node_events.default {
   /**
    * Disconnect from the Redis server.
    * @returns {Promise<void>}
+   * @param {boolean} [force] - it will send a quit command if false, otherwise it will send a disconnect command to forcefully disconnect.
+   * @see {@link https://github.com/redis/node-redis/tree/master/packages/redis#disconnecting}
    */
-  async disconnect() {
+  async disconnect(force) {
     if (this._client.isOpen) {
-      await this._client.disconnect();
+      await (force ? this._client.disconnect() : this._client.quit());
     }
   }
   /**
@@ -515,6 +518,7 @@ var KeyvRedis = class extends import_node_events.default {
   }
 };
 function createKeyv(connect, options) {
+  connect ??= "redis://localhost:6379";
   const adapter = new KeyvRedis(connect, options);
   const keyv = new import_keyv.Keyv({ store: adapter, namespace: options?.namespace, useKeyPrefix: false });
   return keyv;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import EventEmitter from 'node:events';
 import { RedisClientType, RedisClusterType, RedisModules, RedisFunctions, RedisScripts, RedisClientOptions, RedisClusterOptions } from 'redis';
 export { RedisClientOptions, RedisClientType, RedisClusterOptions, RedisClusterType, createClient, createCluster } from 'redis';
-import { KeyvStoreAdapter, Keyv } from 'keyv';
+import { KeyvStoreAdapter, KeyvEntry, Keyv } from 'keyv';
 export { Keyv } from 'keyv';
 
 type KeyvRedisOptions = {
@@ -53,7 +53,7 @@ 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;
@@ -142,9 +142,9 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
     set(key: string, value: string, ttl?: number): Promise<void>;
     /**
      * Will set many key value pairs in the store. TTL is in milliseconds. This will be done as a single transaction.
-     * @param {Array<KeyvRedisEntry<string>>} entries - the key value pairs to set with optional ttl
+     * @param {KeyvEntry[]} entries - the key value pairs to set with optional ttl
      */
-    setMany(entries: Array<KeyvRedisEntry<string>>): Promise<void>;
+    setMany(entries: KeyvEntry[]): Promise<boolean[]>;
     /**
      * Check if a key exists in the store.
      * @param {string} key - the key to check
@@ -162,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
@@ -184,8 +184,10 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
     /**
      * Disconnect from the Redis server.
      * @returns {Promise<void>}
+     * @param {boolean} [force] - it will send a quit command if false, otherwise it will send a disconnect command to forcefully disconnect.
+     * @see {@link https://github.com/redis/node-redis/tree/master/packages/redis#disconnecting}
      */
-    disconnect(): Promise<void>;
+    disconnect(force?: boolean): Promise<void>;
     /**
      * Helper function to create a key with a namespace.
      * @param {string} key - the key to prefix
@@ -216,7 +218,7 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * @param {string} [namespace] - the namespace to iterate over
      * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
      */
-    iterator<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.
@@ -252,8 +254,8 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 }
 /**
  * Will create a Keyv instance with the Redis adapter. This will also set the namespace and useKeyPrefix to false.
- * @param connect
- * @param options
+ * @param 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. If nothing is passed in, it will default to 'redis://localhost:6379'.
+ * @param {KeyvRedisOptions} options - Options for the adapter such as namespace, keyPrefixSeparator, and clearBatchSize.
  * @returns {Keyv} - Keyv instance with the Redis adapter
  */
 declare function createKeyv(connect?: string | RedisClientOptions | RedisClientType, options?: KeyvRedisOptions): Keyv;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import EventEmitter from 'node:events';
 import { RedisClientType, RedisClusterType, RedisModules, RedisFunctions, RedisScripts, RedisClientOptions, RedisClusterOptions } from 'redis';
 export { RedisClientOptions, RedisClientType, RedisClusterOptions, RedisClusterType, createClient, createCluster } from 'redis';
-import { KeyvStoreAdapter, Keyv } from 'keyv';
+import { KeyvStoreAdapter, KeyvEntry, Keyv } from 'keyv';
 export { Keyv } from 'keyv';
 
 type KeyvRedisOptions = {
@@ -53,7 +53,7 @@ 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;
@@ -142,9 +142,9 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
     set(key: string, value: string, ttl?: number): Promise<void>;
     /**
      * Will set many key value pairs in the store. TTL is in milliseconds. This will be done as a single transaction.
-     * @param {Array<KeyvRedisEntry<string>>} entries - the key value pairs to set with optional ttl
+     * @param {KeyvEntry[]} entries - the key value pairs to set with optional ttl
      */
-    setMany(entries: Array<KeyvRedisEntry<string>>): Promise<void>;
+    setMany(entries: KeyvEntry[]): Promise<boolean[]>;
     /**
      * Check if a key exists in the store.
      * @param {string} key - the key to check
@@ -162,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
@@ -184,8 +184,10 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
     /**
      * Disconnect from the Redis server.
      * @returns {Promise<void>}
+     * @param {boolean} [force] - it will send a quit command if false, otherwise it will send a disconnect command to forcefully disconnect.
+     * @see {@link https://github.com/redis/node-redis/tree/master/packages/redis#disconnecting}
      */
-    disconnect(): Promise<void>;
+    disconnect(force?: boolean): Promise<void>;
     /**
      * Helper function to create a key with a namespace.
      * @param {string} key - the key to prefix
@@ -216,7 +218,7 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
      * @param {string} [namespace] - the namespace to iterate over
      * @returns {AsyncGenerator<[string, T | undefined], void, unknown>} - async iterator with key value pairs
      */
-    iterator<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.
@@ -252,8 +254,8 @@ declare class KeyvRedis extends EventEmitter implements KeyvStoreAdapter {
 }
 /**
  * Will create a Keyv instance with the Redis adapter. This will also set the namespace and useKeyPrefix to false.
- * @param connect
- * @param options
+ * @param 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. If nothing is passed in, it will default to 'redis://localhost:6379'.
+ * @param {KeyvRedisOptions} options - Options for the adapter such as namespace, keyPrefixSeparator, and clearBatchSize.
  * @returns {Keyv} - Keyv instance with the Redis adapter
  */
 declare function createKeyv(connect?: string | RedisClientOptions | RedisClientType, options?: KeyvRedisOptions): Keyv;

package/dist/index.js

@@ -169,7 +169,7 @@ var KeyvRedis = class extends EventEmitter {
   }
   /**
    * Will set many key value pairs in the store. TTL is in milliseconds. This will be done as a single transaction.
-   * @param {Array<KeyvRedisEntry<string>>} entries - the key value pairs to set with optional ttl
+   * @param {KeyvEntry[]} entries - the key value pairs to set with optional ttl
    */
   async setMany(entries) {
     const client = await this.getClient();
@@ -183,6 +183,7 @@ var KeyvRedis = class extends EventEmitter {
       }
     }
     await multi.exec();
+    return entries.map(() => true);
   }
   /**
    * Check if a key exists in the store.
@@ -277,10 +278,12 @@ var KeyvRedis = class extends EventEmitter {
   /**
    * Disconnect from the Redis server.
    * @returns {Promise<void>}
+   * @param {boolean} [force] - it will send a quit command if false, otherwise it will send a disconnect command to forcefully disconnect.
+   * @see {@link https://github.com/redis/node-redis/tree/master/packages/redis#disconnecting}
    */
-  async disconnect() {
+  async disconnect(force) {
     if (this._client.isOpen) {
-      await this._client.disconnect();
+      await (force ? this._client.disconnect() : this._client.quit());
     }
   }
   /**
@@ -485,6 +488,7 @@ var KeyvRedis = class extends EventEmitter {
   }
 };
 function createKeyv(connect, options) {
+  connect ??= "redis://localhost:6379";
   const adapter = new KeyvRedis(connect, options);
   const keyv = new Keyv({ store: adapter, namespace: options?.namespace, useKeyPrefix: false });
   return keyv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyv/redis",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Redis storage adapter for Keyv",
   "type": "module",
   "main": "dist/index.cjs",
@@ -36,16 +36,16 @@
   "dependencies": {
     "cluster-key-slot": "^1.1.2",
     "redis": "^4.7.0",
-    "keyv": "^5.2.1"
+    "keyv": "^5.3.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/coverage-v8": "^3.0.7",
     "rimraf": "^6.0.1",
     "timekeeper": "^2.3.1",
     "tsd": "^0.31.2",
-    "vitest": "^2.1.8",
+    "vitest": "^3.0.7",
     "xo": "^0.60.0",
-    "@keyv/test-suite": "^2.0.3"
+    "@keyv/test-suite": "^2.0.5"
   },
   "tsd": {
     "directory": "test"
@@ -59,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"
   }
 }