@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/subscribe.ts

@@ -0,0 +1,254 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import type { Requester } from "../http";
+import { PSubscribeCommand } from "./psubscribe";
+import type { RedisOptions } from "../types";
+
+type SubscriptionInfo = {
+  command: SubscribeCommand;
+  controller: AbortController;
+  isPattern: boolean;
+};
+
+type BaseMessageData<TMessage> = {
+  channel: string;
+  message: TMessage;
+};
+
+type PatternMessageData<TMessage> = BaseMessageData<TMessage> & {
+  pattern: string;
+};
+
+type SubscriptionCountEvent = number;
+
+type MessageEventMap<TMessage> = {
+  message: BaseMessageData<TMessage>;
+  subscribe: SubscriptionCountEvent;
+  unsubscribe: SubscriptionCountEvent;
+  pmessage: PatternMessageData<TMessage>;
+  psubscribe: SubscriptionCountEvent;
+  punsubscribe: SubscriptionCountEvent;
+  error: Error;
+  [key: `message:${string}`]: BaseMessageData<TMessage>;
+  [key: `pmessage:${string}`]: PatternMessageData<TMessage>;
+};
+
+type EventType = keyof MessageEventMap<any>;
+
+type Listener<TMessage, T extends EventType> = (event: MessageEventMap<TMessage>[T]) => void;
+
+export class Subscriber<TMessage = any> extends EventTarget {
+  private subscriptions: Map<string, SubscriptionInfo>;
+  private client: Requester;
+  private listeners: Map<string, Set<Listener<TMessage, any>>>;
+  private opts?: Pick<RedisOptions, "automaticDeserialization">;
+
+  constructor(
+    client: Requester,
+    channels: string[],
+    isPattern: boolean = false,
+    opts?: Pick<RedisOptions, "automaticDeserialization">
+  ) {
+    super();
+    this.client = client;
+    this.subscriptions = new Map();
+    this.listeners = new Map();
+    this.opts = opts;
+
+    for (const channel of channels) {
+      if (isPattern) {
+        this.subscribeToPattern(channel);
+      } else {
+        this.subscribeToChannel(channel);
+      }
+    }
+  }
+
+  private subscribeToChannel(channel: string) {
+    const controller = new AbortController();
+
+    const command = new SubscribeCommand([channel], {
+      streamOptions: {
+        signal: controller.signal,
+        onMessage: (data: string) => this.handleMessage(data, false),
+      },
+    });
+
+    command.exec(this.client).catch((error) => {
+      if (error.name !== "AbortError") {
+        this.dispatchToListeners("error", error);
+      }
+    });
+
+    this.subscriptions.set(channel, {
+      command,
+      controller,
+      isPattern: false,
+    });
+  }
+
+  private subscribeToPattern(pattern: string) {
+    const controller = new AbortController();
+
+    const command = new PSubscribeCommand([pattern], {
+      streamOptions: {
+        signal: controller.signal,
+        onMessage: (data: string) => this.handleMessage(data, true),
+      },
+    });
+
+    command.exec(this.client).catch((error) => {
+      if (error.name !== "AbortError") {
+        this.dispatchToListeners("error", error);
+      }
+    });
+
+    this.subscriptions.set(pattern, {
+      command,
+      controller,
+      isPattern: true,
+    });
+  }
+
+  private handleMessage(data: string, isPattern: boolean) {
+    // Remove "data:" prefix and parse the message
+    const messageData = data.replace(/^data:\s*/, "");
+    const firstCommaIndex = messageData.indexOf(",");
+    const secondCommaIndex = messageData.indexOf(",", firstCommaIndex + 1);
+    const thirdCommaIndex = isPattern ? messageData.indexOf(",", secondCommaIndex + 1) : -1;
+
+    if (firstCommaIndex !== -1 && secondCommaIndex !== -1) {
+      const type = messageData.slice(0, firstCommaIndex);
+
+      if (isPattern && type === "pmessage" && thirdCommaIndex !== -1) {
+        // Handle pmessage format: pmessage,pattern,channel,message
+        const pattern = messageData.slice(firstCommaIndex + 1, secondCommaIndex);
+        const channel = messageData.slice(secondCommaIndex + 1, thirdCommaIndex);
+        const messageStr = messageData.slice(thirdCommaIndex + 1);
+
+        try {
+          const message =
+            this.opts?.automaticDeserialization === false ? messageStr : JSON.parse(messageStr);
+
+          this.dispatchToListeners("pmessage", { pattern, channel, message });
+          this.dispatchToListeners(`pmessage:${pattern}`, { pattern, channel, message });
+        } catch (error) {
+          this.dispatchToListeners("error", new Error(`Failed to parse message: ${error}`));
+        }
+      } else {
+        // Handle regular message format: message,channel,message
+        const channel = messageData.slice(firstCommaIndex + 1, secondCommaIndex);
+        const messageStr = messageData.slice(secondCommaIndex + 1);
+
+        try {
+          if (
+            type === "subscribe" ||
+            type === "psubscribe" ||
+            type === "unsubscribe" ||
+            type === "punsubscribe"
+          ) {
+            // For subscription events, just emit the count
+            const count = Number.parseInt(messageStr);
+            this.dispatchToListeners(type, count);
+          } else {
+            const message =
+              this.opts?.automaticDeserialization === false
+                ? messageStr
+                : parseWithTryCatch(messageStr);
+
+            this.dispatchToListeners(type, { channel, message });
+            this.dispatchToListeners(`${type}:${channel}`, { channel, message });
+          }
+        } catch (error) {
+          this.dispatchToListeners("error", new Error(`Failed to parse message: ${error}`));
+        }
+      }
+    }
+  }
+
+  private dispatchToListeners(type: string, data: any) {
+    const listeners = this.listeners.get(type);
+    if (listeners) {
+      for (const listener of listeners) {
+        listener(data);
+      }
+    }
+  }
+
+  on<T extends keyof MessageEventMap<TMessage>>(type: T, listener: Listener<TMessage, T>): void {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, new Set());
+    }
+    this.listeners.get(type)?.add(listener);
+  }
+
+  removeAllListeners(): void {
+    this.listeners.clear();
+  }
+
+  async unsubscribe(channels?: string[]) {
+    if (channels) {
+      for (const channel of channels) {
+        const subscription = this.subscriptions.get(channel);
+        if (subscription) {
+          try {
+            subscription.controller.abort();
+          } catch {
+            // ignore
+          }
+          this.subscriptions.delete(channel);
+        }
+      }
+    } else {
+      for (const subscription of this.subscriptions.values()) {
+        try {
+          subscription.controller.abort();
+        } catch {
+          // ignore
+        }
+      }
+      this.subscriptions.clear();
+      this.removeAllListeners();
+    }
+  }
+
+  getSubscribedChannels(): string[] {
+    return [...this.subscriptions.keys()];
+  }
+}
+
+/**
+ * @see https://redis.io/commands/subscribe
+ * @see node_modules/@upstash/redis/docs/commands/pubsub/subscribe.mdx
+ */
+export class SubscribeCommand extends Command<number, number> {
+  constructor(
+    cmd: [...channels: string[]],
+    opts?: CommandOptions<number, number> & { signal?: AbortSignal }
+  ) {
+    const sseHeaders = {
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    };
+
+    super([], {
+      ...opts,
+      headers: sseHeaders,
+      path: ["subscribe", ...cmd],
+      streamOptions: {
+        isStreaming: true,
+        onMessage: opts?.streamOptions?.onMessage,
+        signal: opts?.streamOptions?.signal,
+      },
+    });
+  }
+}
+
+const parseWithTryCatch = (str: string) => {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return str;
+  }
+};

package/src/pkg/commands/sunion.ts

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

package/src/pkg/commands/sunionstore.ts

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

package/src/pkg/commands/time.ts

@@ -0,0 +1,10 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/time
+ */
+export class TimeCommand extends Command<[number, number], [number, number]> {
+  constructor(opts?: CommandOptions<[number, number], [number, number]>) {
+    super(["time"], opts);
+  }
+}

package/src/pkg/commands/touch.ts

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

package/src/pkg/commands/ttl.ts

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

package/src/pkg/commands/type.ts

@@ -0,0 +1,13 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type Type = "string" | "list" | "set" | "zset" | "hash" | "none";
+/**
+ * @see https://redis.io/commands/type
+ * @see node_modules/@upstash/redis/docs/commands/generic/type.mdx
+ */
+export class TypeCommand extends Command<Type, Type> {
+  constructor(cmd: [key: string], opts?: CommandOptions<Type, Type>) {
+    super(["type", ...cmd], opts);
+  }
+}

package/src/pkg/commands/types.ts

@@ -0,0 +1,201 @@
+export { type AppendCommand } from "./append";
+export { type ArCountCommand } from "./arcount";
+export { type ArDelCommand } from "./ardel";
+export { type ArDelRangeCommand } from "./ardelrange";
+export { type ArGetCommand } from "./arget";
+export { type ArGetRangeCommand } from "./argetrange";
+export {
+  type ArGrepCommand,
+  type ArGrepOptions,
+  type ArGrepPredicate,
+  type ArGrepResult,
+} from "./argrep";
+export { type ArInfoCommand, type ArInfoOptions, type ArInfoResult } from "./arinfo";
+export { type ArInsertCommand } from "./arinsert";
+export { type ArLastItemsCommand, type ArLastItemsOptions } from "./arlastitems";
+export { type ArLenCommand } from "./arlen";
+export { type ArMGetCommand } from "./armget";
+export { type ArMSetCommand, type ArMSetValues } from "./armset";
+export { type ArNextCommand } from "./arnext";
+export { type ArOpCommand, type ArOpOperation } from "./arop";
+export { type ArRingCommand } from "./arring";
+export { type ArScanCommand, type ArScanOptions } from "./arscan";
+export { type ArSeekCommand } from "./arseek";
+export { type ArSetCommand } from "./arset";
+export { type BitCountCommand } from "./bitcount";
+export { type BitOpCommand } from "./bitop";
+export { type BitPosCommand } from "./bitpos";
+export { type ClientSetInfoCommand, type ClientSetInfoAttribute } from "./client_setinfo";
+export { type CopyCommand } from "./copy";
+export { type DBSizeCommand } from "./dbsize";
+export { type DecrCommand } from "./decr";
+export { type DecrByCommand } from "./decrby";
+export { type DelCommand } from "./del";
+export { type EchoCommand } from "./echo";
+export { type EvalROCommand } from "./evalRo";
+export { type EvalCommand } from "./eval";
+export { type EvalshaROCommand } from "./evalshaRo";
+export { type EvalshaCommand } from "./evalsha";
+export { type ExistsCommand } from "./exists";
+export { type ExpireCommand, type ExpireOption } from "./expire";
+export { type ExpireAtCommand } from "./expireat";
+export { type FlushAllCommand } from "./flushall";
+export { type FlushDBCommand } from "./flushdb";
+export { type GeoAddCommand, GeoAddCommandOptions, GeoMember } from "./geo_add";
+export { type GeoDistCommand } from "./geo_dist";
+export { type GeoHashCommand } from "./geo_hash";
+export { type GeoPosCommand } from "./geo_pos";
+export { type GeoSearchCommand } from "./geo_search";
+export { type GeoSearchStoreCommand } from "./geo_search_store";
+export { type GetCommand } from "./get";
+export { type GetBitCommand } from "./getbit";
+export { type GetDelCommand } from "./getdel";
+export { type GetExCommand } from "./getex";
+export { type GetRangeCommand } from "./getrange";
+export { type GetSetCommand } from "./getset";
+export { type HDelCommand } from "./hdel";
+export { type HExistsCommand } from "./hexists";
+export { type HExpireCommand } from "./hexpire";
+export { type HExpireAtCommand } from "./hexpireat";
+export { type HExpireTimeCommand } from "./hexpiretime";
+export { type HTtlCommand } from "./httl";
+export { type HPExpireCommand } from "./hpexpire";
+export { type HPExpireAtCommand } from "./hpexpireat";
+export { type HPExpireTimeCommand } from "./hpexpiretime";
+export { type HPTtlCommand } from "./hpttl";
+export { type HPersistCommand } from "./hpersist";
+export { type HGetCommand } from "./hget";
+export { type HGetAllCommand } from "./hgetall";
+export { type HGetDelCommand } from "./hgetdel";
+export { type HGetExCommand } from "./hgetex";
+export { type HIncrByCommand } from "./hincrby";
+export { type HIncrByFloatCommand } from "./hincrbyfloat";
+export { type HKeysCommand } from "./hkeys";
+export { type HLenCommand } from "./hlen";
+export { type HMGetCommand } from "./hmget";
+export { type HMSetCommand } from "./hmset";
+export { type HRandFieldCommand } from "./hrandfield";
+export { type HScanCommand } from "./hscan";
+export { type HSetCommand } from "./hset";
+export { type HSetExCommand } from "./hsetex";
+export { type HSetNXCommand } from "./hsetnx";
+export { type HStrLenCommand } from "./hstrlen";
+export { type HValsCommand } from "./hvals";
+export { type IncrCommand } from "./incr";
+export { type IncrByCommand } from "./incrby";
+export { type IncrByFloatCommand } from "./incrbyfloat";
+export { type JsonArrAppendCommand } from "./json_arrappend";
+export { type JsonArrIndexCommand } from "./json_arrindex";
+export { type JsonArrInsertCommand } from "./json_arrinsert";
+export { type JsonArrLenCommand } from "./json_arrlen";
+export { type JsonArrPopCommand } from "./json_arrpop";
+export { type JsonArrTrimCommand } from "./json_arrtrim";
+export { type JsonClearCommand } from "./json_clear";
+export { type JsonDelCommand } from "./json_del";
+export { type JsonForgetCommand } from "./json_forget";
+export { type JsonGetCommand } from "./json_get";
+export { type JsonMergeCommand } from "./json_merge";
+export { type JsonMGetCommand } from "./json_mget";
+export { type JsonNumIncrByCommand } from "./json_numincrby";
+export { type JsonNumMultByCommand } from "./json_nummultby";
+export { type JsonObjKeysCommand } from "./json_objkeys";
+export { type JsonObjLenCommand } from "./json_objlen";
+export { type JsonRespCommand } from "./json_resp";
+export { type JsonSetCommand } from "./json_set";
+export { type JsonStrAppendCommand } from "./json_strappend";
+export { type JsonStrLenCommand } from "./json_strlen";
+export { type JsonToggleCommand } from "./json_toggle";
+export { type JsonTypeCommand } from "./json_type";
+export { type KeysCommand } from "./keys";
+export { type LIndexCommand } from "./lindex";
+export { type LInsertCommand } from "./linsert";
+export { type LLenCommand } from "./llen";
+export { type LMoveCommand } from "./lmove";
+export { type LPopCommand } from "./lpop";
+export { type LPushCommand } from "./lpush";
+export { type LPushXCommand } from "./lpushx";
+export { type LRangeCommand } from "./lrange";
+export { type LRemCommand } from "./lrem";
+export { type LSetCommand } from "./lset";
+export { type LTrimCommand } from "./ltrim";
+export { type MGetCommand } from "./mget";
+export { type MSetCommand } from "./mset";
+export { type MSetNXCommand } from "./msetnx";
+export { type PersistCommand } from "./persist";
+export { type PExpireCommand } from "./pexpire";
+export { type PExpireAtCommand } from "./pexpireat";
+export { type PingCommand } from "./ping";
+export { type PSetEXCommand } from "./psetex";
+export { type PTtlCommand } from "./pttl";
+export { type PublishCommand } from "./publish";
+export { type RandomKeyCommand } from "./randomkey";
+export { type RenameCommand } from "./rename";
+export { type RenameNXCommand } from "./renamenx";
+export { type RPopCommand } from "./rpop";
+export { type RPushCommand } from "./rpush";
+export { type RPushXCommand } from "./rpushx";
+export { type SAddCommand } from "./sadd";
+export { type ScanCommand, ScanCommandOptions } from "./scan";
+export { type SCardCommand } from "./scard";
+export { type ScriptExistsCommand } from "./script_exists";
+export { type ScriptFlushCommand } from "./script_flush";
+export { type ScriptLoadCommand } from "./script_load";
+export { type SDiffCommand } from "./sdiff";
+export { type SDiffStoreCommand } from "./sdiffstore";
+export { type SetCommand, SetCommandOptions } from "./set";
+export { type SetBitCommand } from "./setbit";
+export { type SetExCommand } from "./setex";
+export { type SetNxCommand } from "./setnx";
+export { type SetRangeCommand } from "./setrange";
+export { type SInterCommand } from "./sinter";
+export { type SInterCardCommand } from "./sintercard";
+export { type SInterStoreCommand } from "./sinterstore";
+export { type SIsMemberCommand } from "./sismember";
+export { type SMembersCommand } from "./smembers";
+export { type SMIsMemberCommand } from "./smismember";
+export { type SMoveCommand } from "./smove";
+export { type SPopCommand } from "./spop";
+export { type SRandMemberCommand } from "./srandmember";
+export { type SRemCommand } from "./srem";
+export { type SScanCommand } from "./sscan";
+export { type StrLenCommand } from "./strlen";
+export { type SUnionCommand } from "./sunion";
+export { type SUnionStoreCommand } from "./sunionstore";
+export { type TimeCommand } from "./time";
+export { type TouchCommand } from "./touch";
+export { type TtlCommand } from "./ttl";
+export { Type, type TypeCommand } from "./type";
+export { type UnlinkCommand } from "./unlink";
+export { type VectorAddCommand } from "./vector_add";
+export { type VectorCountCommand } from "./vector_count";
+export { type VectorCreateCommand } from "./vector_create";
+export { type VectorDelCommand } from "./vector_del";
+export { type VectorDropCommand } from "./vector_drop";
+export { type VectorGetCommand } from "./vector_get";
+export { type VectorInfoCommand } from "./vector_info";
+export { type VectorQueryCommand } from "./vector_query";
+export { type XAddCommand } from "./xadd";
+export { type XAckDelCommand } from "./xackdel";
+export { type XDelExCommand } from "./xdelex";
+export { type XRangeCommand } from "./xrange";
+export { ScoreMember, ZAddCommandOptions, type ZAddCommand } from "./zadd";
+export { type ZCardCommand } from "./zcard";
+export { type ZCountCommand } from "./zcount";
+export { type ZDiffStoreCommand } from "./zdiffstore";
+export { type ZIncrByCommand } from "./zincrby";
+export { type ZInterStoreCommand, ZInterStoreCommandOptions } from "./zinterstore";
+export { type ZLexCountCommand } from "./zlexcount";
+export { type ZMScoreCommand } from "./zmscore";
+export { type ZPopMaxCommand } from "./zpopmax";
+export { type ZPopMinCommand } from "./zpopmin";
+export { type ZRangeCommand, ZRangeCommandOptions } from "./zrange";
+export { type ZRankCommand } from "./zrank";
+export { type ZRemCommand } from "./zrem";
+export { type ZRemRangeByLexCommand } from "./zremrangebylex";
+export { type ZRemRangeByRankCommand } from "./zremrangebyrank";
+export { type ZRemRangeByScoreCommand } from "./zremrangebyscore";
+export { type ZRevRankCommand } from "./zrevrank";
+export { type ZScanCommand } from "./zscan";
+export { type ZScoreCommand } from "./zscore";
+export { type ZUnionCommand, ZUnionCommandOptions } from "./zunion";
+export { type ZUnionStoreCommand, ZUnionStoreCommandOptions } from "./zunionstore";

package/src/pkg/commands/unlink.ts

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

package/src/pkg/commands/vector/index.ts

@@ -0,0 +1,11 @@
+export { VectorIndex } from "./vector";
+export type { CreateVectorIndexParameters, VectorIndexParameters } from "./vector";
+export type {
+  VectorCreateOptions,
+  VectorIndexInfo,
+  VectorInput,
+  VectorMetric,
+  VectorQueryOptions,
+  VectorQueryProfile,
+  VectorQueryResult,
+} from "./types";

package/src/pkg/commands/vector/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Distance metric used by a vector index.
+ */
+export type VectorMetric = "COSINE" | "EUCLIDEAN" | "DOT";
+
+/**
+ * Speed / recall trade-off for `VECTOR.QUERY`.
+ *
+ * @default "BALANCED"
+ */
+export type VectorQueryProfile = "FAST" | "BALANCED" | "PRECISE";
+
+/**
+ * A vector to add or query with. Accepts:
+ * - `number[]`: sent as `VALUES <n> <f1> ... <fn>`
+ * - `Float32Array`: encoded as little-endian FP32 and sent as `BASE64-FP32 <b64>`
+ * - `{ base64: string }`: a base64-encoded little-endian FP32 blob, sent as-is with `BASE64-FP32`
+ *   (e.g. the `encoding_format: "base64"` output of embedding providers)
+ */
+export type VectorInput = number[] | Float32Array | { base64: string };
+
+export type VectorCreateOptions = {
+  /**
+   * Number of dimensions of the vectors stored in the index. Must be between 1 and 32768.
+   */
+  dimension: number;
+  /**
+   * Distance metric used to compare vectors.
+   */
+  metric: VectorMetric;
+  /**
+   * When `true`, creating an index that already exists with the same dimension and metric
+   * succeeds (returns `0`) instead of throwing.
+   */
+  existsOk?: boolean;
+};
+
+export type VectorQueryOptions = {
+  /**
+   * The query vector.
+   */
+  vector: VectorInput;
+  /**
+   * Number of nearest neighbours to return. Must be between 1 and 1000.
+   */
+  topK: number;
+  /**
+   * Speed / recall trade-off.
+   *
+   * @default "BALANCED"
+   */
+  profile?: VectorQueryProfile;
+};
+
+export type VectorQueryResult = {
+  id: string;
+  score: number;
+};
+
+export type VectorIndexInfo = {
+  dimension: number;
+  metric: VectorMetric;
+};