bullmq 5.77.0 → 5.77.2

package/dist/cjs/classes/ioredis-client.js

@@ -3,90 +3,101 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createIORedisClient = createIORedisClient;
 exports.isIRedisClient = isIRedisClient;
 /**
- * Augments an ioredis Redis / Cluster instance so that it conforms to
- * {@link IRedisClient}.
+ * Per-raw-client cache so repeated calls to `createIORedisClient` with the
+ * same underlying ioredis instance return the same proxy. This preserves
+ * event-listener identity for the BullMQ-facing client.
+ */
+const proxyCache = new WeakMap();
+/**
+ * Wraps an ioredis `Redis` / `Cluster` instance with a `Proxy` so it conforms
+ * to {@link IRedisClient}.
  *
- * Since ioredis already exposes every Redis command that BullMQ uses
- * (hgetall, zrange, xread, pipeline, multi, nodes, …), the adapter
- * only needs to:
+ * For backwards compatibility BullMQ continues to accept a raw `IORedis`
+ * instance through tehe `connection` option, even though internally it relies
+ * on the `IRedisClient` adapter interface. The returned proxy:
  *
- *   - `runCommand`    – execute a previously defined Lua script by name
- *   - `duplicate`     – ensure the returned instance is also augmented
- *   - `pipeline/multi` – add `runCommand` to the returned ChainableCommander
- *   - translate structured option objects to ioredis varargs where needed
+ *   - exposes `runCommand` (Lua script dispatch by name)
+ *   - exposes structured-options variants of `hset`, `set`, `zrange`,
+ *     `zrevrange`, `xadd`, `xread`, `xtrim`, `scan` (backward-compatible:
+ *     they still accept native ioredis varargs if called that way)
+ *   - returns augmented {@link IRedisTransaction}s from `pipeline()` / `multi()`
+ *   - wraps the result of `duplicate()` in a new proxy
  *
- * **Side-effect warning:** This function mutates the provided instance
- * in-place for zero-overhead augmentation.  When a user passes their own
- * ioredis client to BullMQ, the overrides are written onto that shared
- * object.  All overrides are **backward-compatible**: they detect whether
- * they are called with the ioredis native varargs style or the IRedisClient
- * structured-options style and dispatch accordingly.  External code that
- * calls e.g. `client.hset(key, 'f1', 'v1')` will continue to work after
- * augmentation.
+ * The underlying ioredis instance is **not** mutated. Properties and methods
+ * not in the override table are forwarded to the raw client via the proxy
+ * traps, with `this === target` so EventEmitter / Commander internals work
+ * normally.
  */
 function createIORedisClient(client) {
-    const adapter = client;
-    if (adapter.__bullmq_iredis) {
-        return adapter;
+    // If the caller already passed a proxy produced by this function, return
+    // it as-is. Wrapping a proxy in a second proxy would defeat the WeakMap
+    // cache (the inner raw client is no longer reachable from the outer
+    // argument) and break listener-identity / equality checks for callers
+    // that hold on to the original wrapper.
+    if (client.__bullmq_iredis === true) {
+        return client;
     }
-    adapter.__bullmq_iredis = true;
-    // Ensure isCluster is a boolean.  ioredis Cluster sets it to true;
-    // plain Redis leaves it undefined.
-    if (typeof adapter.isCluster !== 'boolean') {
-        adapter.isCluster = false;
+    const cached = proxyCache.get(client);
+    if (cached) {
+        return cached;
     }
-    // Lua script engine
-    adapter.runCommand = function (name, args) {
-        return adapter[name](args);
+    const isCluster = client.isCluster === true;
+    // Cache bound prototype methods so the returned function identity is
+    // stable across accesses (important for `once`/`removeListener` patterns).
+    const boundCache = new Map();
+    // Override table — properties returned by the proxy without touching the
+    // underlying ioredis instance. The arrow functions close over `client`
+    // directly so ioredis internals always see the raw instance as `this`.
+    const overrides = Object.create(null);
+    overrides.__bullmq_iredis = true;
+    overrides.isCluster = isCluster;
+    // Lua script engine.
+    overrides.runCommand = (name, args) => {
+        return client[name](args);
     };
-    // Pipeline / Multi — add runCommand + structured overrides
-    const origPipeline = client.pipeline.bind(client);
-    adapter.pipeline = function (...args) {
-        return augmentTransaction(origPipeline(...args));
+    // Pipeline / Multi — wrap the ChainableCommander with structured overrides.
+    overrides.pipeline = (...args) => {
+        return augmentTransaction(client.pipeline(...args));
     };
-    const origMulti = client.multi.bind(client);
-    adapter.multi = function (...args) {
-        return augmentTransaction(origMulti(...args));
+    overrides.multi = (...args) => {
+        return augmentTransaction(client.multi(...args));
     };
-    // Duplicate — ensure the result is also augmented.
+    // duplicate — wrap the new raw client with a fresh proxy.
     // ioredis Cluster.duplicate(startupNodes?, options?) expects connection
     // options under `redisOptions`, while Redis.duplicate(options?) takes them
-    // at the top level.  We normalise the call so that callers can always pass
-    // a simple `{ connectionName }` object regardless of the client type.
+    // at the top level. Normalise so callers can always pass `{ connectionName }`.
     if (typeof client.duplicate === 'function') {
-        const origDuplicate = client.duplicate.bind(client);
-        const clientIsCluster = !!client.isCluster;
-        adapter.duplicate = function (opts) {
+        overrides.duplicate = (opts) => {
             var _a;
-            if (clientIsCluster) {
+            if (isCluster) {
                 const existingRedisOpts = ((_a = client.options) === null || _a === void 0 ? void 0 : _a.redisOptions) || {};
                 const mergedRedisOpts = opts
                     ? Object.assign(Object.assign({}, existingRedisOpts), opts) : existingRedisOpts;
-                return createIORedisClient(origDuplicate(undefined, { redisOptions: mergedRedisOpts }));
+                return createIORedisClient(client.duplicate(undefined, {
+                    redisOptions: mergedRedisOpts,
+                }));
             }
-            return createIORedisClient(origDuplicate(opts));
+            return createIORedisClient(client.duplicate(opts));
         };
     }
     // --- Structured → ioredis varargs translations ---
+    // Each override accepts both the IRedisClient structured-options form and
+    // the native ioredis varargs form, dispatching by argument shape.
     // hset: structured { f1: v1 } → ioredis hset(key, f1, v1, …)
-    // Backward-compatible: if second arg is a string, caller is using ioredis varargs.
-    const origHset = client.hset.bind(client);
-    adapter.hset = function (key, dataOrField, ...rest) {
+    overrides.hset = (key, dataOrField, ...rest) => {
         if (typeof dataOrField === 'string') {
-            return origHset(key, dataOrField, ...rest);
+            return client.hset(key, dataOrField, ...rest);
         }
         const args = [key];
         for (const [f, v] of Object.entries(dataOrField)) {
             args.push(f, v);
         }
-        return origHset(...args);
+        return client.hset(...args);
     };
     // set: structured { PX?: n } → ioredis set(key, value, 'PX', n)
-    // Backward-compatible: if third arg is a string, caller is using ioredis varargs.
-    const origSet = client.set.bind(client);
-    adapter.set = function (key, value, optionsOrModifier, ...rest) {
+    overrides.set = (key, value, optionsOrModifier, ...rest) => {
         if (typeof optionsOrModifier === 'string' || optionsOrModifier == null) {
-            return origSet(key, value, ...(optionsOrModifier != null ? [optionsOrModifier, ...rest] : []));
+            return client.set(key, value, ...(optionsOrModifier != null ? [optionsOrModifier, ...rest] : []));
         }
         const args = [key, value];
         if (optionsOrModifier.PX != null) {
@@ -95,39 +106,32 @@ function createIORedisClient(client) {
         else if (optionsOrModifier.EX != null) {
             args.push('EX', optionsOrModifier.EX);
         }
-        return origSet(...args);
+        return client.set(...args);
     };
     // zrange: structured { WITHSCORES? } → ioredis zrange(key, start, end, 'WITHSCORES')
-    // Backward-compatible: if fourth arg is a string, caller is using ioredis varargs.
-    const origZrange = client.zrange.bind(client);
-    adapter.zrange = function (key, start, end, optionsOrStr, ...rest) {
+    overrides.zrange = (key, start, end, optionsOrStr, ...rest) => {
         if (typeof optionsOrStr === 'string') {
-            return origZrange(key, start, end, optionsOrStr, ...rest);
+            return client.zrange(key, start, end, optionsOrStr, ...rest);
         }
         if (optionsOrStr === null || optionsOrStr === void 0 ? void 0 : optionsOrStr.WITHSCORES) {
-            return origZrange(key, start, end, 'WITHSCORES');
+            return client.zrange(key, start, end, 'WITHSCORES');
         }
-        return origZrange(key, start, end);
+        return client.zrange(key, start, end);
     };
     // zrevrange: structured { WITHSCORES? } → ioredis zrevrange(key, start, end, 'WITHSCORES')
-    // Backward-compatible: if fourth arg is a string, caller is using ioredis varargs.
-    const origZrevrange = client.zrevrange.bind(client);
-    adapter.zrevrange = function (key, start, end, optionsOrStr, ...rest) {
+    overrides.zrevrange = (key, start, end, optionsOrStr, ...rest) => {
         if (typeof optionsOrStr === 'string') {
-            return origZrevrange(key, start, end, optionsOrStr, ...rest);
+            return client.zrevrange(key, start, end, optionsOrStr, ...rest);
         }
         if (optionsOrStr === null || optionsOrStr === void 0 ? void 0 : optionsOrStr.WITHSCORES) {
-            return origZrevrange(key, start, end, 'WITHSCORES');
+            return client.zrevrange(key, start, end, 'WITHSCORES');
         }
-        return origZrevrange(key, start, end);
+        return client.zrevrange(key, start, end);
     };
     // xadd: structured (key, id, { field: value }, { MAXLEN? }) → ioredis varargs
-    // Backward-compatible: if third arg is a string, caller is using ioredis varargs
-    // (e.g. xadd(key, id, field1, val1, field2, val2)).
-    const origXadd = client.xadd.bind(client);
-    adapter.xadd = function (key, idOrModifier, fieldsOrArg, ...rest) {
+    overrides.xadd = (key, idOrModifier, fieldsOrArg, ...rest) => {
         if (typeof fieldsOrArg === 'string') {
-            return origXadd(key, idOrModifier, fieldsOrArg, ...rest);
+            return client.xadd(key, idOrModifier, fieldsOrArg, ...rest);
         }
         const options = rest[0];
         const args = [key];
@@ -142,15 +146,12 @@ function createIORedisClient(client) {
         for (const [f, v] of Object.entries(fieldsOrArg)) {
             args.push(f, v);
         }
-        return origXadd(...args);
+        return client.xadd(...args);
     };
     // xread: structured ([{ key, id }], { BLOCK?, COUNT? }) → ioredis varargs
-    // Backward-compatible: if first arg is a string, caller is using ioredis varargs
-    // (e.g. xread('BLOCK', 5000, 'STREAMS', key, id)).
-    const origXread = client.xread.bind(client);
-    adapter.xread = function (streamsOrModifier, ...rest) {
+    overrides.xread = (streamsOrModifier, ...rest) => {
         if (typeof streamsOrModifier === 'string') {
-            return origXread(streamsOrModifier, ...rest);
+            return client.xread(streamsOrModifier, ...rest);
         }
         const options = rest[0];
         const args = [];
@@ -167,15 +168,12 @@ function createIORedisClient(client) {
         for (const s of streamsOrModifier) {
             args.push(s.id);
         }
-        return origXread(...args);
+        return client.xread(...args);
     };
     // xtrim: structured (key, 'MAXLEN', threshold, { approximate? })
-    // ioredis native is the same positional shape, so this is already compatible.
-    const origXtrim = client.xtrim.bind(client);
-    adapter.xtrim = function (key, strategy, thresholdOrApprox, ...rest) {
-        // Varargs passthrough: xtrim(key, 'MAXLEN', '~', 1000) or xtrim(key, 'MAXLEN', 1000)
+    overrides.xtrim = (key, strategy, thresholdOrApprox, ...rest) => {
         if (typeof thresholdOrApprox === 'string' || rest.length === 0) {
-            return origXtrim(key, strategy, thresholdOrApprox, ...rest);
+            return client.xtrim(key, strategy, thresholdOrApprox, ...rest);
         }
         const options = rest[0];
         const args = [key, strategy];
@@ -183,35 +181,21 @@ function createIORedisClient(client) {
             args.push('~');
         }
         args.push(thresholdOrApprox);
-        return origXtrim(...args);
-    };
-    // bzpopmin
-    //
-    // We deliberately do NOT override ioredis' native `bzpopmin` here.
-    // ioredis returns `[key, member, score]` (a tuple) and that is also the
-    // shape required by IRedisClient. Overriding the method on a shared user
-    // instance would change the observable return shape for any non-BullMQ
-    // code that uses `bzpopmin` on the same client.
-    // clientSetName / clientList
-    adapter.clientSetName = function (name) {
-        return client.client('SETNAME', name);
+        return client.xtrim(...args);
     };
-    adapter.clientList = function () {
-        return client.client('LIST');
-    };
-    // scan(cursor, { MATCH?, COUNT? })
-    // Must detect if called with varargs (ioredis internal, e.g. from scanStream)
-    // vs. structured options (IRedisClient interface).
-    const origScan = client.scan.bind(client);
-    adapter.scan = function (cursor, ...rest) {
-        // If called with varargs style (e.g. from scanStream internally),
-        // pass through unchanged.
+    // bzpopmin is not overridden — ioredis already returns
+    // `[key, member, score]`, which matches IRedisClient.
+    // clientSetName / clientList helpers that forward to CLIENT subcommands.
+    overrides.clientSetName = (name) => client.client('SETNAME', name);
+    overrides.clientList = () => client.client('LIST');
+    // scan(cursor, { MATCH?, COUNT? }) — accepts either structured options or
+    // ioredis varargs (used internally by `scanStream`).
+    overrides.scan = (cursor, ...rest) => {
         if (rest.length === 0 ||
             typeof rest[0] === 'string' ||
             typeof rest[0] === 'function') {
-            return origScan(cursor, ...rest);
+            return client.scan(cursor, ...rest);
         }
-        // Structured options: { MATCH?, COUNT? }
         const options = rest[0];
         const args = [cursor];
         if ((options === null || options === void 0 ? void 0 : options.MATCH) != null) {
@@ -220,9 +204,65 @@ function createIORedisClient(client) {
         if ((options === null || options === void 0 ? void 0 : options.COUNT) != null) {
             args.push('COUNT', options.COUNT);
         }
-        return origScan(...args);
+        return client.scan(...args);
     };
-    return adapter;
+    const proxy = new Proxy(client, {
+        get(target, prop) {
+            if (prop in overrides) {
+                return overrides[prop];
+            }
+            // Read against the raw target so getters on the prototype (e.g.
+            // ioredis' EventEmitter internals) see `this === target` rather than
+            // the proxy. This avoids infinite recursion through the proxy traps.
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function') {
+                return value;
+            }
+            // Own properties (including ioredis commands installed via
+            // `defineCommand` and test-time spies set via `obj.method = spy`)
+            // are bound fresh on each access so reassignment is honoured.
+            if (Object.prototype.hasOwnProperty.call(target, prop)) {
+                return value.bind(target);
+            }
+            // Prototype methods (EventEmitter, Commander, ...) are cached so
+            // identity is stable across accesses.
+            const cachedBound = boundCache.get(prop);
+            if (cachedBound !== undefined) {
+                return cachedBound;
+            }
+            const bound = value.bind(target);
+            boundCache.set(prop, bound);
+            return bound;
+        },
+        set(target, prop, value) {
+            // Two assignment paths:
+            //   - Properties present in the override table are reassigned in the
+            //     table itself, so subsequent `get` traps return the new value
+            //     (used by sinon-style spies that stub `runCommand`, `pipeline`,
+            //     etc. on the proxy).
+            //   - All other properties are written through to the raw ioredis
+            //     instance via `Reflect.set`, and any stale bound-method entry is
+            //     invalidated so the next access rebinds the new function.
+            if (prop in overrides) {
+                overrides[prop] = value;
+                return true;
+            }
+            boundCache.delete(prop);
+            return Reflect.set(target, prop, value);
+        },
+        deleteProperty(target, prop) {
+            if (prop in overrides) {
+                return false;
+            }
+            boundCache.delete(prop);
+            return Reflect.deleteProperty(target, prop);
+        },
+        has(target, prop) {
+            return prop in overrides || Reflect.has(target, prop);
+        },
+    });
+    proxyCache.set(client, proxy);
+    return proxy;
 }
 /**
  * Adds `runCommand` and structured overrides to an ioredis ChainableCommander
@@ -275,7 +315,7 @@ function isIRedisClient(obj) {
     if (!obj || typeof obj !== 'object') {
         return false;
     }
-    // Fast path for in-place ioredis augmentation.
+    // Fast path for ioredis instances already wrapped by `createIORedisClient`.
     if (obj.__bullmq_iredis === true) {
         return true;
     }