Normalize unstable RESP3 replies to RESP2-compatible shapes

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/client/lib/RESP/types.ts

@@ -326,14 +326,6 @@ export interface CommanderConfig<
    * additional data types and features introduced in Redis 6.0.
    */
   RESP?: RESP;
-  /**
-   * When set to true, enables commands that have unstable RESP3 implementations.
-   * When using RESP3 protocol, commands marked as having unstable RESP3 support
-   * will throw an error unless this flag is explicitly set to true.
-   * This primarily affects modules like Redis Search where response formats
-   * in RESP3 mode may change in future versions.
-   */
-  unstableResp3?: boolean;
 }
 
 type Resp2Array<T> = (

packages/client/lib/commander.ts

@@ -15,11 +15,6 @@ interface AttachConfigOptions<
   config?: CommanderConfig<M, F, S, RESP>;
 }
 
-/* FIXME: better error message / link */
-function throwResp3SearchModuleUnstableError() {
-  throw new Error('Some RESP3 results for Redis Query Engine responses may change. Refer to the readme for guidance');
-}
-
 export function attachConfig<
   M extends RedisModules,
   F extends RedisFunctions,
@@ -38,22 +33,14 @@ export function attachConfig<
     Class: any = class extends BaseClass {};
 
   for (const [name, command] of Object.entries(commands)) {
-    if (RESP == 3 && command.unstableResp3 && !config?.unstableResp3) {
-      Class.prototype[name] = throwResp3SearchModuleUnstableError;
-    } else {
-      Class.prototype[name] = createCommand(command, RESP);
-    }
+    Class.prototype[name] = createCommand(command, RESP);
   }
 
   if (config?.modules) {
     for (const [moduleName, module] of Object.entries(config.modules)) {
       const fns: Record<string, (...args: Array<any>) => any> = {};
       for (const [name, command] of Object.entries(module)) {
-        if (RESP == 3 && command.unstableResp3 && !config?.unstableResp3) {
-          fns[name] = throwResp3SearchModuleUnstableError;
-        } else {
-          fns[name] = createModuleCommand(command, RESP);
-        }
+        fns[name] = createModuleCommand(command, RESP);
       }
 
       attachNamespace(Class.prototype, moduleName, fns);

packages/client/lib/commands/HOTKEYS_GET.ts

@@ -1,5 +1,5 @@
 import { CommandParser } from '../client/parser';
-import { Command, 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,12 +213,6 @@ 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 () => HotkeysGetReply
-  },
+  transformReply: transformHotkeysGetReply,
   unstableResp3: true
 } as const satisfies Command;

packages/client/lib/commands/XREAD.spec.ts

@@ -132,24 +132,7 @@ describe('XREAD', () => {
     cluster: GLOBAL.CLUSTERS.OPEN
   });
 
-  testUtils.testWithClient('client.xRead should throw with resp3 and unstableResp3: false', async client => {
-    assert.throws(
-      () => client.xRead({
-        key: 'key',
-        id: '0-0'
-      }),
-      {
-        message: 'Some RESP3 results for Redis Query Engine responses may change. Refer to the readme for guidance'
-      }
-    );
-  }, {
-    ...GLOBAL.SERVERS.OPEN,
-    clientOptions: {
-      RESP: 3
-    }
-  });
-
-  testUtils.testWithClient('client.xRead should not throw with resp3 and unstableResp3: true', async client => {
+  testUtils.testWithClient('client.xRead should not throw with resp3', async client => {
     assert.doesNotThrow(
       () => client.xRead({
         key: 'key',
@@ -159,8 +142,7 @@ describe('XREAD', () => {
   }, {
     ...GLOBAL.SERVERS.OPEN,
     clientOptions: {
-      RESP: 3,
-      unstableResp3: true
+      RESP: 3
     }
   });
 

packages/client/lib/commands/XREAD.ts

@@ -1,6 +1,6 @@
 import { CommandParser } from '../client/parser';
 import { Command, RedisArgument, ReplyUnion } from '../RESP/types';
-import { transformStreamsMessagesReplyResp2 } from './generic-transformers';
+import { transformStreamsMessagesReplyResp2, transformStreamsMessagesReplyResp3 } from './generic-transformers';
 
 /**
  * Structure representing a stream to read from
@@ -48,6 +48,44 @@ export interface XReadOptions {
   BLOCK?: number;
 }
 
+function transformStreamsMessagesReplyResp3Compat(reply: ReplyUnion) {
+  const transformed = transformStreamsMessagesReplyResp3(reply as any);
+  if (transformed === null) return null;
+
+  const compat = [];
+
+  if (transformed instanceof Map) {
+    for (const [name, messages] of transformed.entries()) {
+      compat.push({
+        name,
+        messages
+      });
+    }
+
+    return compat;
+  }
+
+  if (Array.isArray(transformed)) {
+    for (let i = 0; i < transformed.length; i += 2) {
+      compat.push({
+        name: transformed[i],
+        messages: transformed[i + 1]
+      });
+    }
+
+    return compat;
+  }
+
+  for (const [name, messages] of Object.entries(transformed)) {
+    compat.push({
+      name,
+      messages
+    });
+  }
+
+  return compat;
+}
+
 export default {
   IS_READ_ONLY: true,
   /**
@@ -77,7 +115,7 @@ export default {
    */
   transformReply: {
     2: transformStreamsMessagesReplyResp2,
-    3: undefined as unknown as () => ReplyUnion
+    3: transformStreamsMessagesReplyResp3Compat
   },
   unstableResp3: true
 } as const satisfies Command;