@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/xgroup.ts

@@ -0,0 +1,101 @@
+import type { CommandOptions } from "./command.ts";
+import { Command } from "./command.ts";
+
+type XGroupCommandType =
+  | {
+      type: "CREATE";
+      group: string;
+      id: `$` | string;
+      options?: { MKSTREAM?: boolean; ENTRIESREAD?: number };
+    }
+  | {
+      type: "CREATECONSUMER";
+      group: string;
+      consumer: string;
+    }
+  | {
+      type: "DELCONSUMER";
+      group: string;
+      consumer: string;
+    }
+  | {
+      type: "DESTROY";
+      group: string;
+    }
+  | {
+      type: "SETID";
+      group: string;
+      id: `$` | string;
+      options?: { ENTRIESREAD?: number };
+    };
+
+type XGroupReturnType<T extends XGroupCommandType> = T["type"] extends "CREATE"
+  ? string
+  : T["type"] extends "CREATECONSUMER"
+    ? 0 | 1
+    : T["type"] extends "DELCONSUMER"
+      ? number
+      : T["type"] extends "DESTROY"
+        ? 0 | 1
+        : T["type"] extends "SETID"
+          ? string
+          : never;
+
+/**
+ * @see https://redis.io/commands/xgroup
+ * @see node_modules/@upstash/redis/docs/commands/stream/xgroup.mdx
+ */
+export class XGroupCommand<TOptions extends XGroupCommandType = XGroupCommandType> extends Command<
+  any,
+  XGroupReturnType<TOptions>
+> {
+  constructor(
+    [key, opts]: [key: string, opts: TOptions],
+    commandOptions?: CommandOptions<any, any>
+  ) {
+    const command: unknown[] = ["XGROUP"];
+
+    switch (opts.type) {
+      case "CREATE": {
+        command.push("CREATE", key, opts.group, opts.id);
+        if (opts.options) {
+          if (opts.options.MKSTREAM) {
+            command.push("MKSTREAM");
+          }
+          if (opts.options.ENTRIESREAD !== undefined) {
+            command.push("ENTRIESREAD", opts.options.ENTRIESREAD.toString());
+          }
+        }
+        break;
+      }
+
+      case "CREATECONSUMER": {
+        command.push("CREATECONSUMER", key, opts.group, opts.consumer);
+        break;
+      }
+
+      case "DELCONSUMER": {
+        command.push("DELCONSUMER", key, opts.group, opts.consumer);
+        break;
+      }
+
+      case "DESTROY": {
+        command.push("DESTROY", key, opts.group);
+        break;
+      }
+
+      case "SETID": {
+        command.push("SETID", key, opts.group, opts.id);
+        if (opts.options?.ENTRIESREAD !== undefined) {
+          command.push("ENTRIESREAD", opts.options.ENTRIESREAD.toString());
+        }
+        break;
+      }
+
+      default: {
+        throw new Error("Invalid XGROUP");
+      }
+    }
+    super(command, commandOptions);
+  }
+}

package/src/pkg/commands/xinfo.ts

@@ -0,0 +1,28 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+type XInfoCommands =
+  | {
+      type: "CONSUMERS";
+      group: string;
+    }
+  | { type: "GROUPS" };
+
+/**
+ * @see https://redis.io/commands/xinfo
+ * @see node_modules/@upstash/redis/docs/commands/stream/xinfo.mdx
+ */
+export class XInfoCommand extends Command<number, unknown[]> {
+  constructor(
+    [key, options]: [key: string, options: XInfoCommands],
+    opts?: CommandOptions<number, unknown[]>
+  ) {
+    const cmds: unknown[] = [];
+    if (options.type === "CONSUMERS") {
+      cmds.push("CONSUMERS", key, options.group);
+    } else {
+      cmds.push("GROUPS", key);
+    }
+    super(["XINFO", ...cmds], opts);
+  }
+}

package/src/pkg/commands/xlen.ts

@@ -0,0 +1,12 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/xlen
+ * @see node_modules/@upstash/redis/docs/commands/stream/xlen.mdx
+ */
+export class XLenCommand extends Command<number, number> {
+  constructor(cmd: [key: string], opts?: CommandOptions<number, number>) {
+    super(["XLEN", ...cmd], opts);
+  }
+}

package/src/pkg/commands/xpending.ts

@@ -0,0 +1,44 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/xpending
+ * @see node_modules/@upstash/redis/docs/commands/stream/xpending.mdx
+ */
+export class XPendingCommand extends Command<unknown[], unknown[]> {
+  constructor(
+    [key, group, start, end, count, options]: [
+      key: string,
+      group: string,
+      start: string,
+      end: string,
+      count: number,
+      options?: {
+        idleTime?: number;
+        consumer?: string | string[];
+      },
+    ],
+    opts?: CommandOptions<unknown[], unknown[]>
+  ) {
+    const consumers =
+      options?.consumer === undefined
+        ? []
+        : Array.isArray(options.consumer)
+          ? [...options.consumer]
+          : [options.consumer];
+
+    super(
+      [
+        "XPENDING",
+        key,
+        group,
+        ...(options?.idleTime ? ["IDLE", options.idleTime] : []),
+        start,
+        end,
+        count,
+        ...consumers,
+      ],
+      opts
+    );
+  }
+}

package/src/pkg/commands/xrange.ts

@@ -0,0 +1,49 @@
+import { parseJSON } from "../util";
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+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) {
+    for (let i = 0; i < e.length; i += 2) {
+      const streamId = e[i] as string;
+      const entries = e[i + 1];
+
+      if (!(streamId in obj)) {
+        obj[streamId] = {};
+      }
+      for (let j = 0; j < entries.length; j += 2) {
+        const field = (entries as string[])[j];
+        const value = (entries as string[])[j + 1];
+
+        try {
+          obj[streamId][field] = parseJSON(value);
+        } catch {
+          obj[streamId][field] = value;
+        }
+      }
+    }
+  }
+  return obj as TData;
+}
+
+export class XRangeCommand<TData extends Record<string, Record<string, unknown>>> extends Command<
+  string[][],
+  TData
+> {
+  constructor(
+    [key, start, end, count]: [key: string, start: string, end: string, count?: number],
+    opts?: CommandOptions<unknown[], TData[]>
+  ) {
+    const command: unknown[] = ["XRANGE", key, start, end];
+    if (typeof count === "number") {
+      command.push("COUNT", count);
+    }
+    super(command, {
+      deserialize: (result) => deserialize<any>(result as any),
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/xread.ts

@@ -0,0 +1,78 @@
+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;
+    /**
+     * @deprecated block is not yet supported in Upstash Redis
+     */
+    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;
+            /**
+             * @deprecated block is not yet supported in Upstash Redis
+             */
+            blockMS?: number;
+          },
+        ]
+      : never
+    : K extends string[]
+      ? I extends string[]
+        ? [
+            key: string[],
+            id: string[],
+            options?: {
+              count?: number;
+              /**
+               * @deprecated block is not yet supported in Upstash Redis
+               */
+              blockMS?: number;
+            },
+          ]
+        : never
+      : never
+  : never;
+
+/**
+ * @see https://redis.io/commands/xread
+ * @see node_modules/@upstash/redis/docs/commands/stream/xread.mdx
+ */
+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/src/pkg/commands/xreadgroup.ts

@@ -0,0 +1,74 @@
+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;
+  /**
+   * @deprecated block is not yet supported in Upstash Redis
+   */
+  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
+ * @see node_modules/@upstash/redis/docs/commands/stream/xreadgroup.mdx
+ */
+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/src/pkg/commands/xrevrange.ts

@@ -0,0 +1,48 @@
+import { parseJSON } from "../util";
+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) {
+    for (let i = 0; i < e.length; i += 2) {
+      const streamId = e[i] as string;
+      const entries = e[i + 1];
+
+      if (!(streamId in obj)) {
+        obj[streamId] = {};
+      }
+      for (let j = 0; j < entries.length; j += 2) {
+        const field = (entries as string[])[j];
+        const value = (entries as string[])[j + 1];
+
+        try {
+          obj[streamId][field] = parseJSON(value);
+        } catch {
+          obj[streamId][field] = value;
+        }
+      }
+    }
+  }
+  return obj as TData;
+}

package/src/pkg/commands/xtrim.ts

@@ -0,0 +1,25 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/xtrim
+ * @see node_modules/@upstash/redis/docs/commands/stream/xtrim.mdx
+ */
+
+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);
+  }
+}

package/src/pkg/commands/zadd.ts

@@ -0,0 +1,54 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+type NXAndXXOptions =
+  | { nx: true; xx?: never }
+  | { nx?: never; xx: true }
+  | { nx?: never; xx?: never };
+
+type LTAndGTOptions =
+  | { lt: true; gt?: never }
+  | { lt?: never; gt: true }
+  | { lt?: never; gt?: never };
+
+export type ZAddCommandOptions = NXAndXXOptions & LTAndGTOptions & { ch?: true } & { incr?: true };
+
+type Arg2<TData> = ScoreMember<TData> | ZAddCommandOptions;
+export type ScoreMember<TData> = { score: number; member: TData };
+/**
+ * @see https://redis.io/commands/zadd
+ * @see node_modules/@upstash/redis/docs/commands/zset/zadd.mdx
+ */
+export class ZAddCommand<TData = string> extends Command<number | null, number | null> {
+  constructor(
+    [key, arg1, ...arg2]: [string, Arg2<TData>, ...ScoreMember<TData>[]],
+    opts?: CommandOptions<number | null, number | null>
+  ) {
+    const command: unknown[] = ["zadd", key];
+    if ("nx" in arg1 && arg1.nx) {
+      command.push("nx");
+    } else if ("xx" in arg1 && arg1.xx) {
+      command.push("xx");
+    }
+    if ("ch" in arg1 && arg1.ch) {
+      command.push("ch");
+    }
+    if ("incr" in arg1 && arg1.incr) {
+      command.push("incr");
+    }
+
+    if ("lt" in arg1 && arg1.lt) {
+      command.push("lt");
+    } else if ("gt" in arg1 && arg1.gt) {
+      command.push("gt");
+    }
+
+    if ("score" in arg1 && "member" in arg1) {
+      command.push(arg1.score, arg1.member);
+    }
+
+    command.push(...arg2.flatMap(({ score, member }) => [score, member]));
+
+    super(command, opts);
+  }
+}

package/src/pkg/commands/zcard.ts

@@ -0,0 +1,12 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/zcard
+ * @see node_modules/@upstash/redis/docs/commands/zset/zcard.mdx
+ */
+export class ZCardCommand extends Command<number, number> {
+  constructor(cmd: [key: string], opts?: CommandOptions<number, number>) {
+    super(["zcard", ...cmd], opts);
+  }
+}

package/src/pkg/commands/zcount.ts

@@ -0,0 +1,14 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/zcount
+ * @see node_modules/@upstash/redis/docs/commands/zset/zcount.mdx
+ */
+export class ZCountCommand extends Command<number, number> {
+  constructor(
+    cmd: [key: string, min: number | string, max: number | string],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["zcount", ...cmd], opts);
+  }
+}

package/src/pkg/commands/zdiffstore.ts

@@ -0,0 +1,15 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/zdiffstore
+ * @see node_modules/@upstash/redis/docs/commands/zset/zdiffstore.mdx
+ */
+export class ZDiffStoreCommand extends Command<number, number> {
+  constructor(
+    cmd: [destination: string, numkeys: number, ...keys: string[]],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["zdiffstore", ...cmd], opts);
+  }
+}

package/src/pkg/commands/zincrby.ts

@@ -0,0 +1,14 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/zincrby
+ * @see node_modules/@upstash/redis/docs/commands/zset/zincrby.mdx
+ */
+export class ZIncrByCommand<TData> extends Command<number, number> {
+  constructor(
+    cmd: [key: string, increment: number, member: TData],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["zincrby", ...cmd], opts);
+  }
+}

package/src/pkg/commands/zinterstore.ts

@@ -0,0 +1,51 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type ZInterStoreCommandOptions = {
+  aggregate?: "sum" | "min" | "max";
+} & (
+  | { weight: number; weights?: never }
+  | { weight?: never; weights: number[] }
+  | { weight?: never; weights?: never }
+);
+
+/**
+ * @see https://redis.io/commands/zInterstore
+ */
+export class ZInterStoreCommand extends Command<number, number> {
+  constructor(
+    cmd: [destination: string, numKeys: 1, key: string, opts?: ZInterStoreCommandOptions],
+    cmdOpts?: CommandOptions<number, number>
+  );
+  constructor(
+    cmd: [destination: string, numKeys: number, keys: string[], opts?: ZInterStoreCommandOptions],
+    cmdOpts?: CommandOptions<number, number>
+  );
+  constructor(
+    [destination, numKeys, keyOrKeys, opts]: [
+      destination: string,
+      numKeys: number,
+      keyOrKeys: string | string[],
+      opts?: ZInterStoreCommandOptions,
+    ],
+    cmdOpts?: CommandOptions<number, number>
+  ) {
+    const command: unknown[] = ["zinterstore", destination, numKeys];
+    if (Array.isArray(keyOrKeys)) {
+      command.push(...keyOrKeys);
+    } else {
+      command.push(keyOrKeys);
+    }
+    if (opts) {
+      if ("weights" in opts && opts.weights) {
+        command.push("weights", ...opts.weights);
+      } else if ("weight" in opts && typeof opts.weight === "number") {
+        command.push("weights", opts.weight);
+      }
+      if ("aggregate" in opts) {
+        command.push("aggregate", opts.aggregate);
+      }
+    }
+    super(command, cmdOpts);
+  }
+}

package/src/pkg/commands/zlexcount.ts

@@ -0,0 +1,11 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/zlexcount
+ * @see node_modules/@upstash/redis/docs/commands/zset/zlexcount.mdx
+ */
+export class ZLexCountCommand extends Command<number, number> {
+  constructor(cmd: [key: string, min: string, max: string], opts?: CommandOptions<number, number>) {
+    super(["zlexcount", ...cmd], opts);
+  }
+}

package/src/pkg/commands/zmscore.ts

@@ -0,0 +1,16 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/zmscore
+ * @see node_modules/@upstash/redis/docs/commands/zset/zmscore.mdx
+ */
+export class ZMScoreCommand<TData> extends Command<string[] | null, number[] | null> {
+  constructor(
+    cmd: [key: string, members: TData[]],
+    opts?: CommandOptions<string[] | null, number[] | null>
+  ) {
+    const [key, members] = cmd;
+    super(["zmscore", key, ...members], opts);
+  }
+}

package/src/pkg/commands/zpopmax.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/zpopmax
+ * @see node_modules/@upstash/redis/docs/commands/zset/zpopmax.mdx
+ */
+export class ZPopMaxCommand<TData> extends Command<string[], TData[]> {
+  constructor(
+    [key, count]: [key: string, count?: number],
+    opts?: CommandOptions<string[], TData[]>
+  ) {
+    const command: unknown[] = ["zpopmax", key];
+    if (typeof count === "number") {
+      command.push(count);
+    }
+    super(command, opts);
+  }
+}