feat: add withtypes option to the scan command (#1376)

* feat: add withtypes option to the scan command

* fix: use describe instead of test and fix tests

---------

Co-authored-by: CahidArda <cahidardaooz@hotmail.com>

Author: ytkimirti

pkg/commands/scan.test.ts

@@ -1,7 +1,8 @@
 import { keygen, newHttpClient, randomID } from "../test-utils";
 
-import { afterAll, expect, test } from "bun:test";
+import { afterAll, describe, expect, test } from "bun:test";
 import { FlushDBCommand } from "./flushdb";
+import type { ScanResultWithType } from "./scan";
 import { ScanCommand } from "./scan";
 import { SetCommand } from "./set";
 import { TypeCommand } from "./type";
@@ -10,7 +11,7 @@ const client = newHttpClient();
 
 const { newKey, cleanup } = keygen();
 afterAll(cleanup);
-test("without options", () => {
+describe("without options", () => {
   test("returns cursor and keys", async () => {
     const key = newKey();
     const value = randomID();
@@ -26,7 +27,7 @@ test("without options", () => {
   });
 });
 
-test("with match", () => {
+describe("with match", () => {
   test("returns cursor and keys", async () => {
     const key = newKey();
     const value = randomID();
@@ -36,7 +37,7 @@ test("with match", () => {
     const found: string[] = [];
     do {
       const res = await new ScanCommand([cursor, { match: key }]).exec(client);
-      expect(typeof res[0]).toEqual("number");
+      expect(typeof res[0]).toEqual("string");
       cursor = res[0];
       found.push(...res[1]);
     } while (cursor !== "0");
@@ -45,7 +46,7 @@ test("with match", () => {
   });
 });
 
-test("with count", () => {
+describe("with count", () => {
   test("returns cursor and keys", async () => {
     const key = newKey();
     const value = randomID();
@@ -63,7 +64,7 @@ test("with count", () => {
   });
 });
 
-test("with type", () => {
+describe("with type", () => {
   test("returns cursor and keys", async () => {
     await new FlushDBCommand([]).exec(client);
     const key1 = newKey();
@@ -89,3 +90,46 @@ test("with type", () => {
     }
   });
 });
+
+describe("with withType", () => {
+  test("returns cursor and keys with types", async () => {
+    await new FlushDBCommand([]).exec(client);
+    const stringKey = newKey();
+    const zsetKey = newKey();
+    const value = randomID();
+
+    // Add different types of keys
+    await new SetCommand([stringKey, value]).exec(client);
+    await new ZAddCommand([zsetKey, { score: 1, member: "abc" }]).exec(client);
+
+    // Scan with WITHTYPE option
+    let cursor = "0";
+    let foundStringKey;
+    let foundZsetKey;
+
+    do {
+      // Use the generic type parameter to specify the return type
+      const res = await new ScanCommand<ScanResultWithType>([cursor, { withType: true }]).exec(
+        client
+      );
+
+      cursor = res[0];
+      const items = res[1];
+
+      // Find our test keys in the results
+      if (!foundStringKey) {
+        foundStringKey = items.find((item) => item.key === stringKey && item.type === "string");
+      }
+
+      if (!foundZsetKey) {
+        foundZsetKey = items.find((item) => item.key === zsetKey && item.type === "zset");
+      }
+    } while (cursor !== "0");
+
+    // Verify types are correct
+    expect(foundStringKey).toBeDefined();
+    expect(foundZsetKey).toBeDefined();
+    expect(foundStringKey?.type).toEqual("string");
+    expect(foundZsetKey?.type).toEqual("zset");
+  });
+});

pkg/commands/scan.ts

@@ -1,19 +1,42 @@
-import { deserializeScanResponse } from "../util";
+import { deserializeScanResponse, deserializeScanWithTypesResponse } from "../util";
 import type { CommandOptions } from "./command";
 import { Command } from "./command";
 
-export type ScanCommandOptions = {
+export type ScanCommandOptionsStandard = {
   match?: string;
   count?: number;
   type?: string;
+  withType?: false;
 };
+
+export type ScanCommandOptionsWithType = {
+  match?: string;
+  count?: number;
+  /**
+   * Includes types of each key in the result
+   *
+   * @example
+   * ```typescript
+   * await redis.scan("0", { withType: true })
+   * // ["0", [{ key: "key1", type: "string" }, { key: "key2", type: "list" }]]
+   * ```
+   */
+  withType: true;
+};
+
+export type ScanCommandOptions = ScanCommandOptionsStandard | ScanCommandOptionsWithType;
+
+export type ScanResultStandard = [string, string[]];
+
+export type ScanResultWithType = [string, { key: string; type: string }[]];
+
 /**
  * @see https://redis.io/commands/scan
  */
-export class ScanCommand extends Command<[string, string[]], [string, string[]]> {
+export class ScanCommand<TData = ScanResultStandard> extends Command<[string, string[]], TData> {
   constructor(
     [cursor, opts]: [cursor: string | number, opts?: ScanCommandOptions],
-    cmdOpts?: CommandOptions<[string, string[]], [string, string[]]>
+    cmdOpts?: CommandOptions<[string, string[]], TData>
   ) {
     const command: (number | string)[] = ["scan", cursor];
     if (opts?.match) {
@@ -22,11 +45,17 @@ export class ScanCommand extends Command<[string, string[]], [string, string[]]>
     if (typeof opts?.count === "number") {
       command.push("count", opts.count);
     }
-    if (opts?.type && opts.type.length > 0) {
+
+    // Handle type and withType options
+    if (opts && "withType" in opts && opts.withType === true) {
+      command.push("withtype");
+    } else if (opts && "type" in opts && opts.type && opts.type.length > 0) {
       command.push("type", opts.type);
     }
+
     super(command, {
-      deserialize: deserializeScanResponse,
+      // @ts-expect-error ignore types here
+      deserialize: opts?.withType ? deserializeScanWithTypesResponse : deserializeScanResponse,
       ...cmdOpts,
     });
   }

pkg/redis.test.ts

@@ -3,6 +3,7 @@ import { keygen, newHttpClient, randomID } from "./test-utils";
 
 import { afterEach, describe, expect, test } from "bun:test";
 import { HttpClient } from "./http";
+import type { ScanResultStandard, ScanResultWithType } from "./commands/scan";
 const client = newHttpClient();
 
 const { newKey, cleanup } = keygen();
@@ -75,7 +76,7 @@ describe("when destructuring the redis class", () => {
   });
 });
 
-test("zadd", () => {
+describe("zadd", () => {
   test("adds the set", async () => {
     const key = newKey();
     const score = 1;
@@ -86,7 +87,7 @@ test("zadd", () => {
   });
 });
 
-test("zrange", () => {
+describe("zrange", () => {
   test("returns the range", async () => {
     const key = newKey();
     const score = 1;
@@ -98,7 +99,7 @@ test("zrange", () => {
   });
 });
 
-test("middleware", () => {
+describe("middleware", () => {
   let state = false;
   test("before", async () => {
     const r = new Redis(client);
@@ -128,7 +129,7 @@ test("middleware", () => {
   });
 });
 
-test("special data", () => {
+describe("special data", () => {
   test("with %", async () => {
     const key = newKey();
     const value = "%%12";
@@ -184,7 +185,7 @@ test("special data", () => {
   });
 });
 
-test("disable base64 encoding", () => {
+describe("disable base64 encoding", () => {
   test("emojis", async () => {
     const key = newKey();
     const value = "😀";
@@ -248,3 +249,19 @@ describe("tests with latency logging", () => {
     expect(res).toEqual(value);
   });
 });
+
+const assertIsType = <T>(_arg: () => T) => {};
+
+describe("return type of scan withType", () => {
+  test("should return cursor and keys with types", async () => {
+    const redis = new Redis(client);
+
+    assertIsType<Promise<ScanResultStandard>>(() => redis.scan("0"));
+
+    assertIsType<Promise<ScanResultStandard>>(() => redis.scan("0", {}));
+
+    assertIsType<Promise<ScanResultStandard>>(() => redis.scan("0", { withType: false }));
+
+    assertIsType<Promise<ScanResultWithType>>(() => redis.scan("0", { withType: true }));
+  });
+});

pkg/redis.ts

@@ -5,6 +5,9 @@ import type {
   SetCommandOptions,
   ZAddCommandOptions,
   ZRangeCommandOptions,
+  ScanCommandOptions,
+  ScanResultStandard,
+  ScanResultWithType,
 } from "./commands/mod";
 import {
   AppendCommand,
@@ -1100,8 +1103,17 @@ export class Redis {
   /**
    * @see https://redis.io/commands/scan
    */
-  scan = (...args: CommandArgs<typeof ScanCommand>) =>
-    new ScanCommand(args, this.opts).exec(this.client);
+  scan(cursor: string | number): Promise<ScanResultStandard>;
+  scan<TOptions extends ScanCommandOptions>(
+    cursor: string | number,
+    opts: TOptions
+  ): Promise<TOptions extends { withType: true } ? ScanResultWithType : ScanResultStandard>;
+  scan<TOptions extends ScanCommandOptions>(
+    cursor: string | number,
+    opts?: TOptions
+  ): Promise<TOptions extends { withType: true } ? ScanResultWithType : ScanResultStandard> {
+    return new ScanCommand([cursor, opts], this.opts).exec(this.client);
+  }
 
   /**
    * @see https://redis.io/commands/scard

pkg/util.ts

@@ -1,3 +1,5 @@
+import type { ScanResultWithType } from "./commands/scan";
+
 function parseRecursive(obj: unknown): unknown {
   const parsed = Array.isArray(obj)
     ? obj.map((o) => {
@@ -41,6 +43,18 @@ export function deserializeScanResponse<TResult>(result: [string, ...any]): TRes
   return [result[0], ...parseResponse<any[]>(result.slice(1))] as TResult;
 }
 
+export function deserializeScanWithTypesResponse(result: [string, string[]]): ScanResultWithType {
+  const [cursor, keys] = result;
+
+  const parsedKeys: ScanResultWithType[1] = [];
+
+  for (let i = 0; i < keys.length; i += 2) {
+    parsedKeys.push({ key: keys[i], type: keys[i + 1] });
+  }
+
+  return [cursor, parsedKeys];
+}
+
 /**
  * Merges multiple Records of headers into a single Record
  * Later headers take precedence over earlier ones.