fix(compat): normalize RESP2/RESP3 reply transforms

- Normalize cross-module reply-shape handling for RESP2 and RESP3.
- Apply shared parser and transformer updates for stable compatibility.
- Leave targeted module bugfixes isolated for the next commit.

Author: nkaradzhov

docs/v5.md

@@ -40,41 +40,6 @@ This replaces the previous approach of using `commandOptions({ returnBuffers: tr
 
 RESP3 uses a different mechanism for handling Pub/Sub messages. Instead of modifying the `onReply` handler as in RESP2, RESP3 provides a dedicated `onPush` handler. When using RESP3, the client automatically uses this more efficient push notification system.
 
-## Known Limitations
-
-### Unstable Commands
-
-Some Redis commands have unstable RESP3 transformations. These commands will throw an error when used with RESP3 unless you explicitly opt in to using them by setting `unstableResp3: true` in your client configuration:
-
-```javascript
-const client = createClient({
-  RESP: 3,
-  unstableResp3: true
-});
-```
-
-The following commands have unstable RESP3 implementations:
-
-1. **Stream Commands**:
-   - `XREAD` and `XREADGROUP` - The response format differs between RESP2 and RESP3
-
-2. **Search Commands (RediSearch)**:
-   - `FT.AGGREGATE`
-   - `FT.AGGREGATE_WITHCURSOR`
-   - `FT.CURSOR_READ`
-   - `FT.INFO`
-   - `FT.PROFILE_AGGREGATE`
-   - `FT.PROFILE_SEARCH`
-   - `FT.SEARCH`
-   - `FT.SEARCH_NOCONTENT`
-   - `FT.SPELLCHECK`
-
-3. **Time Series Commands**:
-   - `TS.INFO`
-   - `TS.INFO_DEBUG`
-
-If you need to use these commands with RESP3, be aware that the response format might change in future versions.
-
 # Sentinel Support
 
 [Sentinel](./sentinel.md)

packages/bloom/lib/commands/bloom/helpers.ts

@@ -17,7 +17,7 @@ export function transformInfoV2Reply<T>(reply: Array<any>, typeMapping?: TypeMap
       return ret as unknown as T;
     }
     default: {
-      const ret = Object.create(null);
+      const ret: Record<string, any> = {};
 
       for (let i = 0; i < reply.length; i += 2) {
         ret[reply[i].toString()] = reply[i + 1];
@@ -26,4 +26,4 @@ export function transformInfoV2Reply<T>(reply: Array<any>, typeMapping?: TypeMap
       return ret as unknown as T;
     }
   }
-}
+}

packages/client/lib/RESP/decoder.ts

@@ -924,7 +924,7 @@ export class Decoder {
 
       default:
         return this.#decodeMapAsObject(
-          Object.create(null),
+          {},
           length,
           typeMapping,
           chunk

packages/client/lib/client/commands-queue.ts

@@ -189,7 +189,10 @@ export default class RedisCommandsQueue {
   }
 
   #getTypeMapping() {
-    return this.#waitingForReply.head!.value.typeMapping ?? {};
+    const head = this.#waitingForReply.head;
+    if (!head) return PUSH_TYPE_MAPPING;
+
+    return head.value.typeMapping ?? {};
   }
 
   #initiateDecoder() {

packages/client/lib/commands/FUNCTION_STATS.ts

@@ -60,7 +60,7 @@ function transformEngines(reply: Resp2Reply<Engines>) {
   const engines: Record<string, {
     libraries_count: NumberReply;
     functions_count: NumberReply;
-  }> = Object.create(null);
+  }> = {};
   for (let i = 0; i < unwraped.length; i++) {
     const name = unwraped[i] as BlobStringReply,
       stats = unwraped[++i] as Resp2Reply<Engine>,

packages/client/lib/commands/HOTKEYS_GET.ts

@@ -1,5 +1,5 @@
 import { CommandParser } from '../client/parser';
-import { Command, ReplyUnion, UnwrapReply, ArrayReply, BlobStringReply, NumberReply } from '../RESP/types';
+import { Command } from '../RESP/types';
 
 /**
  * Hotkey entry with key name and metric value
@@ -43,30 +43,77 @@ export interface HotkeysGetReply {
   byNetBytes?: Array<HotkeyEntry>;
 }
 
-type HotkeysGetRawReply = ArrayReply<ArrayReply<BlobStringReply | NumberReply | ArrayReply<BlobStringReply | NumberReply>>>;
+function mapLikeEntries(value: any): Array<[string, any]> {
+  if (value instanceof Map) {
+    return Array.from(value.entries(), ([key, entryValue]) => [key.toString(), entryValue]);
+  }
+
+  if (Array.isArray(value)) {
+    if (
+      value.length === 1 &&
+      (Array.isArray(value[0]) || value[0] instanceof Map || (typeof value[0] === 'object' && value[0] !== null))
+    ) {
+      return mapLikeEntries(value[0]);
+    }
+
+    if (value.every(item => Array.isArray(item) && item.length >= 2)) {
+      return value.map(item => [item[0].toString(), item[1]]);
+    }
+
+    const entries: Array<[string, any]> = [];
+    for (let i = 0; i < value.length - 1; i += 2) {
+      entries.push([value[i].toString(), value[i + 1]]);
+    }
+    return entries;
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.entries(value);
+  }
+
+  return [];
+}
+
+function mapLikeValues(value: any): Array<any> {
+  if (Array.isArray(value)) return value;
+  if (value instanceof Map) return [...value.values()];
+  if (value !== null && typeof value === 'object') return Object.values(value);
+  return [];
+}
 
 /**
  * Parse the hotkeys array into HotkeyEntry objects
  */
-function parseHotkeysList(arr: Array<BlobStringReply | NumberReply>): Array<HotkeyEntry> {
-  const result: Array<HotkeyEntry> = [];
-  for (let i = 0; i < arr.length; i += 2) {
-    result.push({
-      key: arr[i].toString(),
-      value: Number(arr[i + 1])
-    });
-  }
-  return result;
+function parseHotkeysList(arr: unknown): Array<HotkeyEntry> {
+  return mapLikeEntries(arr).map(([key, value]) => ({
+    key,
+    value: Number(value)
+  }));
 }
 
 /**
  * Parse slot ranges from the server response.
  * Single slots are represented as arrays with one element: [slot]
  * Slot ranges are represented as arrays with two elements: [start, end]
  */
-function parseSlotRanges(arr: Array<ArrayReply<NumberReply>>): Array<SlotRange> {
-  return arr.map(range => {
-    const unwrapped = range as unknown as Array<number>;
+function parseSlotRanges(arr: unknown): Array<SlotRange> {
+  return mapLikeValues(arr).map(range => {
+    let unwrapped: Array<number>;
+
+    if (Array.isArray(range)) {
+      unwrapped = range as Array<number>;
+    } else if (range instanceof Map) {
+      unwrapped = [...range.values()].map(value => Number(value));
+    } else if (range !== null && typeof range === 'object') {
+      const objectRange = range as Record<string, unknown>;
+      const start = Number(objectRange.start ?? objectRange[0]);
+      const end = Number(objectRange.end ?? objectRange[1] ?? start);
+      unwrapped = [start, end];
+    } else {
+      const slot = Number(range);
+      unwrapped = [slot, slot];
+    }
+
     if (unwrapped.length === 1) {
       // Single slot - start and end are the same
       return {
@@ -85,15 +132,11 @@ function parseSlotRanges(arr: Array<ArrayReply<NumberReply>>): Array<SlotRange>
 /**
  * Transform the raw reply into a structured object
  */
-function transformHotkeysGetReply(reply: UnwrapReply<HotkeysGetRawReply>): HotkeysGetReply {
-  const result: Partial<HotkeysGetReply> = {};
-
-  // The reply is wrapped in an extra array, so we need to access reply[0]
-  const data = reply[0] as unknown as Array<BlobStringReply | NumberReply | ArrayReply<BlobStringReply | NumberReply>>;
+function transformHotkeysGetReply(reply: unknown | null): HotkeysGetReply | null {
+  if (reply === null) return null;
 
-  for (let i = 0; i < data.length; i += 2) {
-    const key = data[i].toString();
-    const value = data[i + 1];
+  const result: Partial<HotkeysGetReply> = {};
+  for (const [key, value] of mapLikeEntries(reply)) {
 
     switch (key) {
       case 'tracking-active':
@@ -103,7 +146,7 @@ function transformHotkeysGetReply(reply: UnwrapReply<HotkeysGetRawReply>): Hotke
         result.sampleRatio = Number(value);
         break;
       case 'selected-slots':
-        result.selectedSlots = parseSlotRanges(value as unknown as Array<ArrayReply<NumberReply>>);
+        result.selectedSlots = parseSlotRanges(value);
         break;
       case 'sampled-commands-selected-slots-us':
         result.sampledCommandsSelectedSlotsUs = Number(value);
@@ -139,10 +182,10 @@ function transformHotkeysGetReply(reply: UnwrapReply<HotkeysGetRawReply>): Hotke
         result.totalNetBytes = Number(value);
         break;
       case 'by-cpu-time-us':
-        result.byCpuTimeUs = parseHotkeysList(value as unknown as Array<BlobStringReply | NumberReply>);
+        result.byCpuTimeUs = parseHotkeysList(value);
         break;
       case 'by-net-bytes':
-        result.byNetBytes = parseHotkeysList(value as unknown as Array<BlobStringReply | NumberReply>);
+        result.byNetBytes = parseHotkeysList(value);
         break;
     }
   }
@@ -170,11 +213,5 @@ export default {
   parseCommand(parser: CommandParser) {
     parser.push('HOTKEYS', 'GET');
   },
-  transformReply: {
-    2: (reply: UnwrapReply<HotkeysGetRawReply> | null): HotkeysGetReply | null => {
-      if (reply === null) return null;
-      return transformHotkeysGetReply(reply);
-    },
-    3: undefined as unknown as () => ReplyUnion
-  }
+  transformReply: transformHotkeysGetReply
 } as const satisfies Command;

packages/client/lib/commands/MODULE_LIST.ts

@@ -6,6 +6,55 @@ export type ModuleListReply = ArrayReply<TuplesToMapReply<[
   [BlobStringReply<'ver'>, NumberReply],
 ]>>;
 
+function transformModuleReply(moduleReply: any) {
+  if (Array.isArray(moduleReply)) {
+    let name: BlobStringReply | undefined;
+    let ver: NumberReply | undefined;
+
+    for (let i = 0; i < moduleReply.length; i += 2) {
+      const key = moduleReply[i]?.toString();
+      if (key === 'name') {
+        name = moduleReply[i + 1];
+      } else if (key === 'ver') {
+        ver = moduleReply[i + 1];
+      }
+    }
+
+    return {
+      name: name as BlobStringReply,
+      ver: ver as NumberReply
+    };
+  }
+
+  if (moduleReply instanceof Map) {
+    let name: BlobStringReply | undefined;
+    let ver: NumberReply | undefined;
+
+    for (const [key, value] of moduleReply.entries()) {
+      const normalizedKey = key?.toString();
+      if (normalizedKey === 'name') {
+        name = value;
+      } else if (normalizedKey === 'ver') {
+        ver = value;
+      }
+    }
+
+    return {
+      name: name as BlobStringReply,
+      ver: ver as NumberReply
+    };
+  }
+
+  return {
+    name: moduleReply.name,
+    ver: moduleReply.ver
+  };
+}
+
+function transformModuleListReply(reply: Array<any>) {
+  return reply.map(moduleReply => transformModuleReply(moduleReply));
+}
+
 export default {
   NOT_KEYED_COMMAND: true,
   IS_READ_ONLY: true,
@@ -19,15 +68,7 @@ export default {
     parser.push('MODULE', 'LIST');
   },
   transformReply: {
-    2: (reply: UnwrapReply<Resp2Reply<ModuleListReply>>) => {
-      return reply.map(module => {
-        const unwrapped = module as unknown as UnwrapReply<typeof module>;
-        return {
-          name: unwrapped[1],
-          ver: unwrapped[3]
-        };
-      });
-    },
-    3: undefined as unknown as () => ModuleListReply
+    2: transformModuleListReply as unknown as (reply: UnwrapReply<Resp2Reply<ModuleListReply>>) => ModuleListReply,
+    3: transformModuleListReply as unknown as () => ModuleListReply
   }
 } as const satisfies Command;

packages/client/lib/commands/PUBSUB_NUMSUB.ts

@@ -26,7 +26,7 @@ export default {
    * @returns Record mapping channel names to their subscriber counts
    */
   transformReply(rawReply: UnwrapReply<ArrayReply<BlobStringReply | NumberReply>>) {
-    const reply = Object.create(null);
+    const reply: Record<string, any> = {};
     let i = 0;
     while (i < rawReply.length) {
       reply[rawReply[i++].toString()] = Number(rawReply[i++]);

packages/client/lib/commands/PUBSUB_SHARDNUMSUB.ts

@@ -6,7 +6,7 @@ export default {
   IS_READ_ONLY: true,
   /**
    * Constructs the PUBSUB SHARDNUMSUB command
-   * 
+   *
    * @param parser - The command parser
    * @param channels - Optional shard channel names to get subscription count for
    * @see https://redis.io/commands/pubsub-shardnumsub/
@@ -20,18 +20,17 @@ export default {
   },
   /**
    * Transforms the PUBSUB SHARDNUMSUB reply into a record of shard channel name to subscriber count
-   * 
+   *
    * @param reply - The raw reply from Redis
    * @returns Record mapping shard channel names to their subscriber counts
    */
   transformReply(reply: UnwrapReply<ArrayReply<BlobStringReply | NumberReply>>) {
-    const transformedReply: Record<string, NumberReply> = Object.create(null);
+    const transformedReply: Record<string, NumberReply> = {};
 
     for (let i = 0; i < reply.length; i += 2) {
       transformedReply[(reply[i] as BlobStringReply).toString()] = reply[i + 1] as NumberReply;
     }
-  
+
     return transformedReply;
   }
 } as const satisfies Command;
-

packages/client/lib/commands/VINFO.ts

@@ -14,7 +14,7 @@ export default {
   IS_READ_ONLY: true,
   /**
    * Retrieve metadata and internal details about a vector set, including size, dimensions, quantization type, and graph structure
-   * 
+   *
    * @param parser - The command parser
    * @param key - The key of the vector set
    * @see https://redis.io/commands/vinfo/
@@ -25,7 +25,7 @@ export default {
   },
   transformReply: {
     2: (reply: UnwrapReply<Resp2Reply<VInfoReplyMap>>): VInfoReplyMap => {
-      const ret = Object.create(null);
+      const ret: Record<string, any> = {};
 
       for (let i = 0; i < reply.length; i += 2) {
         ret[reply[i].toString()] = reply[i + 1];