@upstash/redis 0.0.0-ci.babdc47f97e036e2863dfed16300cda2b97bf6ad-20240322001434 → 0.0.0-ci.bb93ac2803c2e927dc8bf1a1b3c5aa2a14034eb6-20240930061920

package/pkg/commands/xread.test.ts

@@ -0,0 +1,117 @@
+/* eslint-disable unicorn/consistent-function-scoping */
+import { addNewItemToStream, keygen, newHttpClient } from "../test-utils";
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { UNBALANCED_XREAD_ERR, XReadCommand } from "./xread";
+
+const client = newHttpClient();
+
+const { newKey, cleanup } = keygen();
+afterAll(cleanup);
+
+describe("COUNT", () => {
+  test("should return successfully", async () => {
+    const streamKey = newKey();
+    const { member1: xmember1, member2: xmember2 } = await addNewItemToStream(streamKey, client);
+
+    const res = (await new XReadCommand([streamKey, "0-0"]).exec(client)) as string[];
+
+    //@ts-expect-error to silence compiler
+    expect(res[0][1][0][1]).toEqual(["field1", xmember1, "field2", xmember2]);
+  });
+  test("should return multiple items", async () => {
+    const wantedLength = 3;
+    const streamKey = newKey();
+    await addNewItemToStream(streamKey, client);
+    await addNewItemToStream(streamKey, client);
+    await addNewItemToStream(streamKey, client);
+
+    const res = (await new XReadCommand([streamKey, "0-0", { count: wantedLength }]).exec(
+      client
+    )) as any[];
+
+    expect(res[0][1].length).toBe(wantedLength);
+  });
+  test("should return desired amount of items", async () => {
+    const wantedLength = 2;
+    const streamKey = newKey();
+    await addNewItemToStream(streamKey, client);
+    await addNewItemToStream(streamKey, client);
+    await addNewItemToStream(streamKey, client);
+
+    const res = (await new XReadCommand([streamKey, "0-0", { count: wantedLength }]).exec(
+      client
+    )) as any[];
+
+    expect(res[0][1].length).toBe(wantedLength);
+  });
+});
+
+describe("IDs", () => {
+  test(
+    "should return items with given id",
+    async () => {
+      const streamKey = newKey();
+      await addNewItemToStream(streamKey, client);
+
+      const res = (await new XReadCommand([streamKey, `${Date.now() - 15_000}-0`]).exec(
+        client
+      )) as string[];
+      expect(res).toBeInstanceOf(Array);
+    },
+    { retry: 3 }
+  );
+});
+
+describe("Multiple stream", () => {
+  test(
+    "should return items with multiple streams and ids",
+    async () => {
+      const wantedLength = 2;
+
+      const streamKey1 = newKey();
+      await addNewItemToStream(streamKey1, client);
+      const streamKey2 = newKey();
+      await addNewItemToStream(streamKey2, client);
+
+      const res = (await new XReadCommand([
+        [streamKey1, streamKey2],
+        ["0-0", "0-0"],
+      ]).exec(client)) as string[];
+      expect(res.length).toBe(wantedLength);
+    },
+    { retry: 3 }
+  );
+
+  test(
+    "should return only 1 stream",
+    async () => {
+      const wantedLength = 1;
+
+      const streamKey1 = newKey();
+      await addNewItemToStream(streamKey1, client);
+
+      const res = (await new XReadCommand([
+        [streamKey1, newKey()],
+        ["0-0", "0-0"],
+      ]).exec(client)) as string[];
+      expect(res.length).toBe(wantedLength);
+    },
+    { retry: 3 }
+  );
+
+  test(
+    "should throw when unbalanced is array passed",
+    () => {
+      const throwable = async () => {
+        const streamKey1 = newKey();
+        await addNewItemToStream(streamKey1, client);
+
+        await new XReadCommand([[streamKey1, newKey()], ["0-0"]]).exec(client);
+      };
+
+      expect(throwable).toThrow(UNBALANCED_XREAD_ERR);
+    },
+    { retry: 3 }
+  );
+});

package/pkg/commands/xread.ts

@@ -0,0 +1,51 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export const UNBALANCED_XREAD_ERR =
+  "ERR Unbalanced XREAD list of streams: for each stream key an ID or '$' must be specified";
+
+type XReadCommandOptions = [
+  key: string | string[],
+  id: string | string[],
+  options?: { count?: number; blockMS?: number },
+];
+
+//This type ensures users have balanced stream keys and stream ids otherwise redis server will throw an error.
+type XReadOptions = XReadCommandOptions extends [infer K, infer I, ...any[]]
+  ? K extends string
+    ? I extends string
+      ? [key: string, id: string, options?: { count?: number; blockMS?: number }]
+      : never
+    : K extends string[]
+      ? I extends string[]
+        ? [key: string[], id: string[], options?: { count?: number; blockMS?: number }]
+        : never
+      : never
+  : never;
+
+/**
+ * @see https://redis.io/commands/xread
+ */
+export class XReadCommand extends Command<number, unknown[]> {
+  constructor([key, id, options]: XReadOptions, opts?: CommandOptions<number, unknown[]>) {
+    if (Array.isArray(key) && Array.isArray(id) && key.length !== id.length) {
+      throw new Error(UNBALANCED_XREAD_ERR);
+    }
+    const commands: unknown[] = [];
+
+    if (typeof options?.count === "number") {
+      commands.push("COUNT", options.count);
+    }
+    if (typeof options?.blockMS === "number") {
+      commands.push("BLOCK", options.blockMS);
+    }
+
+    commands.push(
+      "STREAMS",
+      ...(Array.isArray(key) ? [...key] : [key]),
+      ...(Array.isArray(id) ? [...id] : [id])
+    );
+
+    super(["XREAD", ...commands], opts);
+  }
+}

package/pkg/commands/xreadgroup.test.ts

@@ -0,0 +1,166 @@
+import { addNewItemToStream, keygen, newHttpClient } from "../test-utils";
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { XGroupCommand } from "./xgroup";
+import { XInfoCommand } from "./xinfo";
+import { UNBALANCED_XREADGROUP_ERR, XReadGroupCommand } from "./xreadgroup";
+
+const client = newHttpClient();
+
+const { newKey, cleanup } = keygen();
+afterAll(cleanup);
+
+describe("COUNT", () => {
+  test("should read everything into given xreadgroup and mark them as pending", async () => {
+    const wantedAmount = 3;
+    const streamKey = newKey();
+    const group = newKey();
+    const consumer = newKey();
+
+    for (let i = 0; i < wantedAmount; i++) {
+      await addNewItemToStream(streamKey, client);
+    }
+
+    await new XGroupCommand([streamKey, { type: "CREATE", group, id: "0" }]).exec(client);
+
+    const res = (await new XReadGroupCommand([group, consumer, streamKey, ">"]).exec(
+      client
+    )) as string[];
+    const listOfStreams = res[0][1];
+
+    expect(listOfStreams.length).toEqual(wantedAmount);
+  });
+
+  test("should read given amount of streams into given xreadgroup and mark them as pending", async () => {
+    const wantedAmount = 2;
+    const streamKey = newKey();
+    const group = newKey();
+    const consumer = newKey();
+
+    for (let i = 0; i < wantedAmount; i++) {
+      await addNewItemToStream(streamKey, client);
+    }
+
+    await new XGroupCommand([streamKey, { type: "CREATE", group, id: "0" }]).exec(client);
+
+    const res = (await new XReadGroupCommand([
+      group,
+      consumer,
+      streamKey,
+      ">",
+      { count: wantedAmount },
+    ]).exec(client)) as string[];
+    const listOfStreams = res[0][1];
+
+    expect(listOfStreams.length).toEqual(wantedAmount);
+  });
+});
+
+describe("NOACK", () => {
+  test("should return 0 items in PEL", async () => {
+    const streamKey = newKey();
+    const group = newKey();
+    const consumer = newKey();
+
+    await addNewItemToStream(streamKey, client);
+
+    await new XGroupCommand([streamKey, { type: "CREATE", group, id: "0" }]).exec(client);
+
+    await new XReadGroupCommand([group, consumer, streamKey, ">", { NOACK: true }]).exec(client);
+
+    const xinfoRes = (await new XInfoCommand([streamKey, { type: "CONSUMERS", group }]).exec(
+      client
+    )) as string[];
+    expect(xinfoRes).toEqual([]);
+  });
+
+  test("should return desired amount of items in PEL", async () => {
+    const wantedCount = 5;
+    const streamKey = newKey();
+    const group = newKey();
+    const consumer = newKey();
+
+    for (let i = 0; i < wantedCount; i++) {
+      await addNewItemToStream(streamKey, client);
+    }
+
+    await new XGroupCommand([streamKey, { type: "CREATE", group, id: "0" }]).exec(client);
+
+    await new XReadGroupCommand([group, consumer, streamKey, ">", { NOACK: false }]).exec(client);
+
+    const xinfoRes = (await new XInfoCommand([streamKey, { type: "CONSUMERS", group }]).exec(
+      client
+    )) as string[];
+
+    const pendingCount = Number(xinfoRes[0][3]);
+
+    expect(pendingCount).toBe(wantedCount);
+  });
+});
+
+describe("Multiple Stream", () => {
+  test("should read given amount of streams into given xreadgroup and mark them as pending", async () => {
+    const streamKey1 = newKey();
+    const streamKey2 = newKey();
+    const group = newKey();
+    const consumer = newKey();
+
+    await addNewItemToStream(streamKey1, client);
+    await addNewItemToStream(streamKey1, client);
+    await addNewItemToStream(streamKey2, client);
+    await addNewItemToStream(streamKey2, client);
+
+    await new XGroupCommand([streamKey1, { type: "CREATE", group, id: "0" }]).exec(client);
+    await new XGroupCommand([streamKey2, { type: "CREATE", group, id: "0" }]).exec(client);
+
+    const res = (await new XReadGroupCommand([
+      group,
+      consumer,
+      [streamKey1, streamKey2],
+      [">", ">"],
+      { count: 1 },
+    ]).exec(client)) as string[];
+    expect(res.length).toEqual(2);
+  });
+
+  test("should read everything into given xreadgroup and mark them as pending", async () => {
+    const wantedAmount = 4;
+    const streamKey = newKey();
+    const group = newKey();
+    const consumer = newKey();
+
+    for (let i = 0; i < wantedAmount; i++) {
+      await addNewItemToStream(streamKey, client);
+    }
+
+    await new XGroupCommand([streamKey, { type: "CREATE", group, id: "0" }]).exec(client);
+
+    const res = (await new XReadGroupCommand([
+      group,
+      consumer,
+      streamKey,
+      ">",
+      { count: wantedAmount },
+    ]).exec(client)) as string[];
+    const listOfStreams = res[0][1];
+
+    expect(listOfStreams.length).toEqual(wantedAmount);
+  });
+
+  test("should throw when unbalanced is array passed", () => {
+    // eslint-disable-next-line unicorn/consistent-function-scoping
+    const throwable = async () => {
+      const streamKey = newKey();
+      const group = newKey();
+      const consumer = newKey();
+
+      await addNewItemToStream(streamKey, client);
+
+      await new XGroupCommand([streamKey, { type: "CREATE", group, id: "0" }]).exec(client);
+
+      await new XReadGroupCommand([group, consumer, [streamKey, newKey()], ["0-0"]]).exec(client);
+    };
+
+    expect(throwable).toThrow(UNBALANCED_XREADGROUP_ERR);
+  });
+});

package/pkg/commands/xreadgroup.ts

@@ -0,0 +1,66 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export const UNBALANCED_XREADGROUP_ERR =
+  "ERR Unbalanced XREADGROUP list of streams: for each stream key an ID or '$' must be specified";
+
+type Options = { count?: number; blockMS?: number; NOACK?: boolean };
+type XReadGroupCommandOptions = [
+  group: string,
+  consumer: string,
+  key: string | string[],
+  id: string | string[],
+  options?: Options,
+];
+
+//This type ensures users have balanced stream keys and stream ids otherwise redis server will throw an error.
+type XReadGroupOptions = XReadGroupCommandOptions extends [
+  string,
+  string,
+  infer TKey,
+  infer TId,
+  ...any[],
+]
+  ? TKey extends string
+    ? TId extends string
+      ? [group: string, consumer: string, key: string, id: string, options?: Options]
+      : never
+    : TKey extends string[]
+      ? TId extends string[]
+        ? [group: string, consumer: string, key: string[], id: string[], options?: Options]
+        : never
+      : never
+  : never;
+
+/**
+ * @see https://redis.io/commands/xreadgroup
+ */
+export class XReadGroupCommand extends Command<number, unknown[]> {
+  constructor(
+    [group, consumer, key, id, options]: XReadGroupOptions,
+    opts?: CommandOptions<number, unknown[]>
+  ) {
+    if (Array.isArray(key) && Array.isArray(id) && key.length !== id.length) {
+      throw new Error(UNBALANCED_XREADGROUP_ERR);
+    }
+    const commands: unknown[] = [];
+
+    if (typeof options?.count === "number") {
+      commands.push("COUNT", options.count);
+    }
+    if (typeof options?.blockMS === "number") {
+      commands.push("BLOCK", options.blockMS);
+    }
+    if (typeof options?.NOACK === "boolean" && options.NOACK) {
+      commands.push("NOACK");
+    }
+
+    commands.push(
+      "STREAMS",
+      ...(Array.isArray(key) ? [...key] : [key]),
+      ...(Array.isArray(id) ? [...id] : [id])
+    );
+
+    super(["XREADGROUP", "GROUP", group, consumer, ...commands], opts);
+  }
+}

package/pkg/commands/xrevrange.test.ts

@@ -0,0 +1,48 @@
+import { keygen, newHttpClient } from "../test-utils";
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { XAddCommand } from "./xadd";
+import { XRevRangeCommand } from "./xrevrange";
+
+const client = newHttpClient();
+const { newKey, cleanup } = keygen();
+const key = newKey();
+afterAll(cleanup);
+
+beforeEach(async () => {
+  await new XAddCommand([key, "*", { name: "Virginia", surname: "Woolf" }]).exec(client);
+
+  await new XAddCommand([key, "*", { name: "Jane", surname: "Austen" }]).exec(client);
+
+  await new XAddCommand([key, "*", { name: "Toni", surname: "Morrison" }]).exec(client);
+
+  await new XAddCommand([key, "*", { name: "Agatha", surname: "Christie" }]).exec(client);
+
+  await new XAddCommand([key, "*", { name: "Ngozi", surname: "Adichie" }]).exec(client);
+});
+
+describe("without options", () => {
+  test("should return stream in a reverse order", async () => {
+    const res = await new XRevRangeCommand([key, "+", "-"]).exec(client);
+
+    expect(Object.keys(res).length).toBe(5);
+    expect(Object.values(res)[0]).toEqual({
+      name: "Ngozi",
+      surname: "Adichie",
+    });
+  });
+});
+
+describe("LIMIT", () => {
+  test("should return only last two", async () => {
+    const res = await new XRevRangeCommand([key, "+", "-", 2]).exec(client);
+    expect(Object.keys(res).length).toBe(2);
+    expect(Object.values(res)).toEqual([
+      {
+        name: "Ngozi",
+        surname: "Adichie",
+      },
+      { name: "Agatha", surname: "Christie" },
+    ]);
+  });
+});

package/pkg/commands/xrevrange.ts

@@ -0,0 +1,47 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export class XRevRangeCommand<
+  TData extends Record<string, Record<string, unknown>>,
+> extends Command<string[][], TData> {
+  constructor(
+    [key, end, start, count]: [key: string, end: string, start: string, count?: number],
+    opts?: CommandOptions<unknown[], TData[]>
+  ) {
+    const command: unknown[] = ["XREVRANGE", key, end, start];
+    if (typeof count === "number") {
+      command.push("COUNT", count);
+    }
+    super(command, {
+      deserialize: (result) => deserialize<any>(result as any),
+      ...opts,
+    });
+  }
+}
+
+function deserialize<TData extends Record<string, Record<string, unknown>>>(
+  result: [string, string[]][]
+): TData {
+  const obj: Record<string, Record<string, unknown>> = {};
+  for (const e of result) {
+    while (e.length >= 2) {
+      const streamId = e.shift() as string;
+      const entries = e.shift()!;
+
+      if (!(streamId in obj)) {
+        obj[streamId] = {};
+      }
+      while (entries.length >= 2) {
+        const field = (entries as string[]).shift()!;
+        const value = (entries as string[]).shift()!;
+
+        try {
+          obj[streamId][field] = JSON.parse(value);
+        } catch {
+          obj[streamId][field] = value;
+        }
+      }
+    }
+  }
+  return obj as TData;
+}

package/pkg/commands/xtrim.test.ts

@@ -0,0 +1,65 @@
+import { keygen, newHttpClient, randomID } from "../test-utils";
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { XAddCommand } from "./xadd";
+import { XLenCommand } from "./xlen";
+import { XTrimCommand } from "./xtrim";
+
+const client = newHttpClient();
+
+const { newKey, cleanup } = keygen();
+afterAll(cleanup);
+
+describe("XLEN", () => {
+  test(
+    "should approximately trim stream to 30 items",
+    async () => {
+      const key = newKey();
+      const promises = [];
+      for (let i = 1; i <= 1000; i++) {
+        promises.push(new XAddCommand([key, "*", { [randomID()]: randomID() }]).exec(client));
+      }
+      await Promise.all(promises);
+      await new XTrimCommand([key, { strategy: "MAXLEN", threshold: 30, exactness: "~" }]).exec(
+        client
+      );
+      const len = await new XLenCommand([key]).exec(client);
+      expect(len).toBeGreaterThanOrEqual(29);
+      expect(len).toBeLessThanOrEqual(31);
+    },
+    { timeout: 1000 * 60 }
+  );
+
+  test("should trim with zero threshold and remove everything", async () => {
+    const key = newKey();
+    const promises = [];
+    for (let i = 1; i <= 50; i++) {
+      promises.push(new XAddCommand([key, "*", { [randomID()]: randomID() }]).exec(client));
+    }
+    await Promise.all(promises);
+    await new XTrimCommand([key, { strategy: "MAXLEN", threshold: 0, exactness: "=" }]).exec(
+      client
+    );
+    const len = await new XLenCommand([key]).exec(client);
+    expect(len).toBeLessThanOrEqual(1);
+  });
+
+  test(
+    "should trim with MINID and a limit and only remove 2 items that satisfies MINID",
+    async () => {
+      const key = newKey();
+      const baseTimestamp = Date.now();
+      for (let i = 0; i < 20; i++) {
+        const id = `${baseTimestamp}-${i}`;
+        await new XAddCommand([key, id, { data: `value${i}` }]).exec(client);
+      }
+      const midRangeId = `${baseTimestamp}-10`;
+      await new XTrimCommand([key, { strategy: "MINID", threshold: midRangeId, limit: 2 }]).exec(
+        client
+      );
+      const len = await new XLenCommand([key]).exec(client);
+      expect(len).toBeLessThanOrEqual(20);
+    },
+    { timeout: 20_000 }
+  );
+});

package/pkg/commands/xtrim.ts

@@ -0,0 +1,24 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/xtrim
+ */
+
+type XTrimOptions = {
+  strategy: "MAXLEN" | "MINID";
+  exactness?: "~" | "=";
+  threshold: number | string;
+  limit?: number;
+};
+
+export class XTrimCommand extends Command<number, number> {
+  constructor(
+    [key, options]: [key: string, options: XTrimOptions],
+    opts?: CommandOptions<number, number>
+  ) {
+    const { limit, strategy, threshold, exactness = "~" } = options;
+
+    super(["XTRIM", key, strategy, exactness, threshold, ...(limit ? ["LIMIT", limit] : [])], opts);
+  }
+}