Allow passing in custom ioredis Redis or Cluster client (#106)

silverbucket · claude · web-flow · commit a840116f44f7 · 2026-01-25T20:09:19.000+01:00
* Allow passing in external clients

* Address PR review feedback

- Remove unnecessary type assertions (as Redis) since both Redis and
  Cluster have status and connect() properties
- Reorder if/else in disconnect() for clarity (check positive case first)

* fix: use event-based ready detection for external clients

* fix: replace test delay with status polling, add comment for close/end check

* tests: improve testing for node envs, cleanup clients

* chore: remove superfluous code

---------

Co-authored-by: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -41,9 +41,85 @@ new SecureStore(config: SecureStoreConfig)
 | ------------------ | ------------------------------- | -------- | ----------------------------------------------------------------- |
 | `uid`              | string                          | Yes      | Unique prefix for Redis keys (e.g., `"myApp"`, `"myApp:sessions"`) |
 | `secret`           | string                          | Yes      | 32-character encryption secret. Use `SecretValidator.generate()`. |
-| `redis`            | RedisOptions \| { url: string } | Yes      | Redis connection config                                           |
+| `redis`            | RedisOptions \| { url: string } \| { client: Redis \| Cluster } | Yes      | Redis connection config or existing client                        |
 | `allowWeakSecrets` | boolean                         | No       | Bypass secret strength validation (default: false)                |
 
+### Using an Existing Redis Client
+
+You can pass your own ioredis `Redis` or `Cluster` client instead of connection options. This enables connection sharing, pre-configured clients, and integration with existing Redis infrastructure.
+
+```typescript
+import { Redis } from "ioredis";
+import SecureStore, { SecretValidator } from "secure-store-redis";
+
+const redis = new Redis({ host: "localhost", port: 6379 });
+
+const store = new SecureStore({
+    uid: "myApp",
+    secret: SecretValidator.generate(),
+    redis: { client: redis },
+});
+
+await store.connect();
+await store.save("key", "value");
+await store.disconnect();
+
+// Your client is still connected - you manage its lifecycle
+console.log(redis.status); // "ready"
+await redis.quit();
+```
+
+#### Redis Cluster
+
+```typescript
+import { Cluster } from "ioredis";
+import SecureStore, { SecretValidator } from "secure-store-redis";
+
+const cluster = new Cluster([
+    { host: "node1", port: 6379 },
+    { host: "node2", port: 6379 },
+]);
+
+const store = new SecureStore({
+    uid: "myApp",
+    secret: SecretValidator.generate(),
+    redis: { client: cluster },
+});
+
+await store.connect();
+```
+
+#### Sharing Connections
+
+Multiple SecureStore instances can share a single Redis connection:
+
+```typescript
+const redis = new Redis();
+
+const sessionsStore = new SecureStore({
+    uid: "sessions",
+    secret: sessionSecret,
+    redis: { client: redis },
+});
+
+const cacheStore = new SecureStore({
+    uid: "cache",
+    secret: cacheSecret,
+    redis: { client: redis },
+});
+
+await sessionsStore.connect();
+await cacheStore.connect();
+
+// Both stores use the same connection
+// Disconnecting either store does NOT close the Redis client
+```
+
+**Important notes:**
+- When using an external client, `disconnect()` will NOT close the Redis connection - you are responsible for calling `redis.quit()` when done
+- The client can be in any connectable state (ready, connecting, or lazyConnect); `connect()` will wait for it to be ready
+- If the client is already closed, `connect()` will throw a `ConnectionError`
+
 ### Methods
 
 #### `connect(): Promise<void>`
@@ -72,7 +148,7 @@ Create a typed namespace for organizing data. See [Namespaces](#namespaces) for
 
 ### Properties
 
-- `client: Redis | undefined` - The underlying ioredis client
+- `client: RedisClient | undefined` - The underlying ioredis client (Redis or Cluster)
 - `isConnected: boolean` - Connection status
 
 ## Namespaces
@@ -223,6 +299,7 @@ Full TypeScript support with exported types:
 import SecureStore, {
     SecureStoreConfig,
     TypedNamespace,
+    RedisClient,
     SecretValidator,
     SecureStoreError,
     ConnectionError,
diff --git a/src/index.test.ts b/src/index.test.ts
@@ -1,4 +1,5 @@
 import { expect, test, describe, afterAll, beforeAll } from "./test-compat.ts";
+import { Redis } from "ioredis";
 
 import SecureStore, { SecretValidator } from "./index.ts";
 
@@ -528,4 +529,135 @@ describe("SecureStore", () => {
             expect(result.valid).toEqual(true);
         });
     });
+
+    describe("External Redis Client", () => {
+        test("accepts pre-connected Redis client", async () => {
+            const redis = new Redis({ host: "127.0.0.1", port: 6379 });
+            try {
+                await redis.ping(); // Ensure connected
+
+                const store = new SecureStore({
+                    uid: "external-client-test",
+                    secret: "823HD8DG26JA0LK1239Hgb651TWfs0j1",
+                    redis: { client: redis },
+                });
+
+                await store.connect();
+                expect(store.isConnected).toEqual(true);
+                expect(store.client).toBe(redis);
+
+                await store.save("extKey", "extValue");
+                expect(await store.get("extKey")).toEqual("extValue");
+
+                await store.disconnect();
+                // External client should still be connected
+                expect(redis.status).toEqual("ready");
+            } finally {
+                await redis.quit();
+            }
+        });
+
+        test("accepts Redis client with lazyConnect", async () => {
+            const redis = new Redis({
+                host: "127.0.0.1",
+                port: 6379,
+                lazyConnect: true,
+            });
+
+            try {
+                const store = new SecureStore({
+                    uid: "lazy-client-test",
+                    secret: "823HD8DG26JA0LK1239Hgb651TWfs0j1",
+                    redis: { client: redis },
+                });
+
+                // Client is in "wait" state, connect() should connect it
+                await store.connect();
+                expect(store.isConnected).toEqual(true);
+
+                await store.save("lazyKey", "lazyValue");
+                expect(await store.get("lazyKey")).toEqual("lazyValue");
+
+                await store.disconnect();
+                expect(redis.status).toEqual("ready");
+            } finally {
+                await redis.quit();
+            }
+        });
+
+        test("multiple stores share one client", async () => {
+            const redis = new Redis({ host: "127.0.0.1", port: 6379 });
+            try {
+                await redis.ping();
+
+                const store1 = new SecureStore({
+                    uid: "shared-client-1",
+                    secret: "823HD8DG26JA0LK1239Hgb651TWfs0j1",
+                    redis: { client: redis },
+                });
+
+                const store2 = new SecureStore({
+                    uid: "shared-client-2",
+                    secret: "923HD8DG26JA0LK1239Hgb651TWfs0j2",
+                    redis: { client: redis },
+                });
+
+                await store1.connect();
+                await store2.connect();
+
+                await store1.save("key", "value1");
+                await store2.save("key", "value2");
+
+                expect(await store1.get("key")).toEqual("value1");
+                expect(await store2.get("key")).toEqual("value2");
+
+                await store1.disconnect();
+                // Redis should still be connected after store1 disconnect
+                expect(redis.status).toEqual("ready");
+                expect(store2.isConnected).toEqual(true);
+
+                await store2.disconnect();
+                expect(redis.status).toEqual("ready");
+            } finally {
+                await redis.quit();
+            }
+        });
+
+        test("throws error if external client is closed", async () => {
+            const redis = new Redis({ host: "127.0.0.1", port: 6379 });
+            await redis.ping();
+            await redis.quit();
+            // Poll until status changes to "end" (avoid arbitrary delay)
+            while (redis.status !== "end") {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+            }
+
+            const store = new SecureStore({
+                uid: "closed-client-test",
+                secret: "823HD8DG26JA0LK1239Hgb651TWfs0j1",
+                redis: { client: redis },
+            });
+
+            await expect(store.connect()).rejects.toThrow(
+                "External Redis client is closed",
+            );
+        });
+
+        test("exposes external client via client property", async () => {
+            const redis = new Redis({ host: "127.0.0.1", port: 6379 });
+            try {
+                await redis.ping();
+
+                const store = new SecureStore({
+                    uid: "client-property-test",
+                    secret: "823HD8DG26JA0LK1239Hgb651TWfs0j1",
+                    redis: { client: redis },
+                });
+
+                expect(store.client).toBe(redis);
+            } finally {
+                await redis.quit();
+            }
+        });
+    });
 });
diff --git a/src/index.ts b/src/index.ts
@@ -6,7 +6,13 @@ import {
     randomBytes,
 } from "node:crypto";
 import debug from "debug";
-import { Redis, type RedisOptions } from "ioredis";
+import { type Cluster, Redis, type RedisOptions } from "ioredis";
+
+/**
+ * A Redis-like client that supports the commands SecureStore needs.
+ * Can be either a standard Redis client or a Redis Cluster client.
+ */
+export type RedisClient = Redis | Cluster;
 
 const ALGORITHM = "aes-256-gcm";
 const IV_LENGTH = 16;
@@ -192,9 +198,17 @@ export interface SecureStoreConfig {
      */
     secret: string;
     /**
-     * Redis connect config object
+     * Redis connection configuration. Accepts one of:
+     * - `RedisOptions`: ioredis connection options (host, port, etc.)
+     * - `{ url: string }`: Redis connection URL
+     * - `{ client: RedisClient }`: An existing Redis or Cluster client instance
+     *
+     * When providing an external client:
+     * - SecureStore will NOT close the client on `disconnect()` - you manage its lifecycle
+     * - The client should be connected or in a connectable state
+     * - Both `Redis` and `Cluster` clients are supported
      */
-    redis: RedisOptions | { url: string };
+    redis: RedisOptions | { url: string } | { client: RedisClient };
     /**
      * Allow weak secrets (bypass entropy validation). Not recommended for production.
      * @default false
@@ -225,9 +239,10 @@ export default class SecureStore {
     /**
      * Redis client
      */
-    client: Redis | undefined;
+    client: RedisClient | undefined;
     private readonly config: Required<SecureStoreConfig>;
     private connected = false;
+    private externalClientProvided = false;
 
     /**
      * Creates an instance of SecureStore.
@@ -238,6 +253,11 @@ export default class SecureStore {
         if (typeof cfg.redis !== "object") {
             cfg.redis = {};
         }
+        // Check for external client before secret validation
+        if ("client" in cfg.redis && cfg.redis.client) {
+            this.client = cfg.redis.client;
+            this.externalClientProvided = true;
+        }
         // Validate secret unless allowWeakSecrets is true
         if (!cfg.allowWeakSecrets) {
             const validation = SecretValidator.validate(cfg.secret);
@@ -252,12 +272,20 @@ export default class SecureStore {
     }
 
     /**
-     * Disconnects the Redis client
+     * Disconnects the Redis client.
+     * If using an external client (passed via `{ client: RedisClient }`),
+     * this method will NOT close the connection - you manage its lifecycle.
      */
-    async disconnect(client: Redis | undefined = this.client): Promise<void> {
+    async disconnect(
+        client: RedisClient | undefined = this.client,
+    ): Promise<void> {
         if (client) {
-            log("Redis client quit called");
-            await client.quit();
+            if (this.externalClientProvided && client === this.client) {
+                log("Skipping quit for external client");
+            } else {
+                log("Redis client quit called");
+                await client.quit();
+            }
             this.connected = false;
         }
     }
@@ -270,9 +298,50 @@ export default class SecureStore {
     }
 
     /**
-     * Connects the Redis client to the Redis server
+     * Connects the Redis client to the Redis server.
+     * If using an external client, ensures the client is ready.
      */
     async connect(): Promise<void> {
+        // Handle external client
+        if (this.externalClientProvided && this.client) {
+            const status = this.client.status;
+            if (status === "ready") {
+                this.connected = true;
+                return;
+            }
+            // "end" is the terminal state after quit(). "close" can occur from
+            // connection errors or manual disconnect. Both indicate unusable client.
+            if (status === "close" || status === "end") {
+                throw new ConnectionError(
+                    "External Redis client is closed. Provide a connected client or reconnect before calling connect().",
+                );
+            }
+            // wait/connecting/reconnecting - wait for ready event
+            return new Promise((resolve, reject) => {
+                const onReady = () => {
+                    this.client?.off("error", onError);
+                    this.connected = true;
+                    resolve();
+                };
+                const onError = (err: Error) => {
+                    this.client?.off("ready", onReady);
+                    reject(
+                        new ConnectionError(
+                            "External client failed to connect",
+                            err,
+                        ),
+                    );
+                };
+                this.client?.once("ready", onReady);
+                this.client?.once("error", onError);
+                // Initiate connection if client is waiting (lazyConnect)
+                if (status === "wait") {
+                    this.client?.connect().catch(onError);
+                }
+            });
+        }
+
+        // Create internal client
         if (!this.client) {
             return new Promise((resolve, reject) => {
                 let redisConfig: RedisOptions = {};
@@ -294,7 +363,10 @@ export default class SecureStore {
                                 ? Number.parseInt(url.pathname.slice(1), 10)
                                 : 0,
                     };
-                } else if (this.config.redis) {
+                } else if (
+                    this.config.redis &&
+                    !("client" in this.config.redis)
+                ) {
                     redisConfig = this.config.redis as RedisOptions;
                 }
 
diff --git a/src/test-compat.ts b/src/test-compat.ts
