@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/echo.ts

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

package/src/pkg/commands/eval.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/eval
+ * @see node_modules/@upstash/redis/docs/commands/scripts/eval.mdx
+ * Responses are JSON-parsed automatically: a stored "123" comes back as the number 123, "true" as
+ * true, and '{"a":1}' as an object. Pass automaticDeserialization: false to the Redis constructor
+ * to receive raw strings.
+ */
+export class EvalCommand<TArgs extends unknown[], TData> extends Command<unknown, TData> {
+  constructor(
+    [script, keys, args]: [script: string, keys: string[], args: TArgs],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["eval", script, keys.length, ...keys, ...(args ?? [])], opts);
+  }
+}

package/src/pkg/commands/evalRo.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/eval_ro
+ * @see node_modules/@upstash/redis/docs/commands/scripts/eval_ro.mdx
+ * Responses are JSON-parsed automatically: a stored "123" comes back as the number 123, "true" as
+ * true, and '{"a":1}' as an object. Pass automaticDeserialization: false to the Redis constructor
+ * to receive raw strings.
+ */
+export class EvalROCommand<TArgs extends unknown[], TData> extends Command<unknown, TData> {
+  constructor(
+    [script, keys, args]: [script: string, keys: string[], args: TArgs],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["eval_ro", script, keys.length, ...keys, ...(args ?? [])], opts);
+  }
+}

package/src/pkg/commands/evalsha.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/evalsha
+ * @see node_modules/@upstash/redis/docs/commands/scripts/evalsha.mdx
+ * Responses are JSON-parsed automatically: a stored "123" comes back as the number 123, "true" as
+ * true, and '{"a":1}' as an object. Pass automaticDeserialization: false to the Redis constructor
+ * to receive raw strings.
+ */
+export class EvalshaCommand<TArgs extends unknown[], TData> extends Command<unknown, TData> {
+  constructor(
+    [sha, keys, args]: [sha: string, keys: string[], args?: TArgs],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["evalsha", sha, keys.length, ...keys, ...(args ?? [])], opts);
+  }
+}

package/src/pkg/commands/evalshaRo.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/evalsha_ro
+ * @see node_modules/@upstash/redis/docs/commands/scripts/evalsha_ro.mdx
+ * Responses are JSON-parsed automatically: a stored "123" comes back as the number 123, "true" as
+ * true, and '{"a":1}' as an object. Pass automaticDeserialization: false to the Redis constructor
+ * to receive raw strings.
+ */
+export class EvalshaROCommand<TArgs extends unknown[], TData> extends Command<unknown, TData> {
+  constructor(
+    [sha, keys, args]: [sha: string, keys: string[], args?: TArgs],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["evalsha_ro", sha, keys.length, ...keys, ...(args ?? [])], opts);
+  }
+}

package/src/pkg/commands/exec.ts

@@ -0,0 +1,23 @@
+import { type CommandOptions, Command } from "./command";
+
+/**
+ * Generic exec command for executing arbitrary Redis commands
+ * Allows executing Redis commands that might not be directly supported by the SDK
+ *
+ * @example
+ * // Execute MEMORY USAGE command
+ * await redis.exec<number>("MEMORY", "USAGE", "myKey")
+ *
+ * // Execute GET command
+ * await redis.exec<string>("GET", "foo")
+ */
+
+export class ExecCommand<TResult> extends Command<TResult, TResult> {
+  constructor(
+    cmd: [command: string, ...args: (string | number | boolean)[]],
+    opts?: CommandOptions<TResult, TResult>
+  ) {
+    const normalizedCmd = cmd.map((arg) => (typeof arg === "string" ? arg : String(arg)));
+    super(normalizedCmd, opts);
+  }
+}

package/src/pkg/commands/exists.ts

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

package/src/pkg/commands/expire.ts

@@ -0,0 +1,13 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type ExpireOption = "NX" | "nx" | "XX" | "xx" | "GT" | "gt" | "LT" | "lt";
+
+export class ExpireCommand extends Command<"0" | "1", 0 | 1> {
+  constructor(
+    cmd: [key: string, seconds: number, option?: ExpireOption],
+    opts?: CommandOptions<"0" | "1", 0 | 1>
+  ) {
+    super(["expire", ...cmd.filter(Boolean)], opts);
+  }
+}

package/src/pkg/commands/expireat.ts

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

package/src/pkg/commands/fcall.ts

@@ -0,0 +1,15 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/docs/latest/commands/fcall/
+ * @see node_modules/@upstash/redis/docs/commands/functions/call.mdx
+ */
+export class FCallCommand<TData> extends Command<unknown, TData> {
+  constructor(
+    [functionName, keys, args]: [functionName: string, keys?: string[], args?: string[]],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(["fcall", functionName, ...(keys ? [keys.length, ...keys] : [0]), ...(args ?? [])], opts);
+  }
+}

package/src/pkg/commands/fcall_ro.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/docs/latest/commands/fcall_ro/
+ * @see node_modules/@upstash/redis/docs/commands/functions/call_ro.mdx
+ */
+export class FCallRoCommand<TData> extends Command<unknown, TData> {
+  constructor(
+    [functionName, keys, args]: [functionName: string, keys?: string[], args?: string[]],
+    opts?: CommandOptions<unknown, TData>
+  ) {
+    super(
+      ["fcall_ro", functionName, ...(keys ? [keys.length, ...keys] : [0]), ...(args ?? [])],
+      opts
+    );
+  }
+}

package/src/pkg/commands/flushall.ts

@@ -0,0 +1,15 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/flushall
+ * @see node_modules/@upstash/redis/docs/commands/server/flushall.mdx
+ */
+export class FlushAllCommand extends Command<"OK", "OK"> {
+  constructor(args?: [{ async?: boolean }], opts?: CommandOptions<"OK", "OK">) {
+    const command = ["flushall"];
+    if (args && args.length > 0 && args[0].async) {
+      command.push("async");
+    }
+    super(command, opts);
+  }
+}

package/src/pkg/commands/flushdb.ts

@@ -0,0 +1,15 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+/**
+ * @see https://redis.io/commands/flushdb
+ * @see node_modules/@upstash/redis/docs/commands/server/flushdb.mdx
+ */
+export class FlushDBCommand extends Command<"OK", "OK"> {
+  constructor([opts]: [opts?: { async?: boolean }], cmdOpts?: CommandOptions<"OK", "OK">) {
+    const command = ["flushdb"];
+    if (opts?.async) {
+      command.push("async");
+    }
+    super(command, cmdOpts);
+  }
+}

package/src/pkg/commands/function_delete.ts

@@ -0,0 +1,12 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/docs/latest/commands/function-delete/
+ * @see node_modules/@upstash/redis/docs/commands/functions/delete.mdx
+ */
+export class FunctionDeleteCommand extends Command<"OK", "OK"> {
+  constructor([libraryName]: [libraryName: string], opts?: CommandOptions<"OK", "OK">) {
+    super(["function", "delete", libraryName], opts);
+  }
+}

package/src/pkg/commands/function_flush.ts

@@ -0,0 +1,12 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/docs/latest/commands/function-flush/
+ * @see node_modules/@upstash/redis/docs/commands/functions/flush.mdx
+ */
+export class FunctionFlushCommand extends Command<"OK", "OK"> {
+  constructor(opts?: CommandOptions<"OK", "OK">) {
+    super(["function", "flush"], opts);
+  }
+}

package/src/pkg/commands/function_list.ts

@@ -0,0 +1,77 @@
+import { kvArrayToObject } from "../util";
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type FunctionListArgs = {
+  /**
+   * Pattern for matching library names. Supports glob patterns.
+   *
+   * Example: "my_library_*"
+   */
+  libraryName?: string;
+  /**
+   * Includes the library source code in the response.
+   *
+   * @default false
+   */
+  withCode?: boolean;
+};
+
+type RedisFunctionLibrary = {
+  libraryName: string;
+  engine: string;
+  functions: {
+    name: string;
+    description?: string;
+    flags: string[];
+  }[];
+  libraryCode?: string;
+};
+
+/**
+ * @see https://redis.io/docs/latest/commands/function-list/
+ * @see node_modules/@upstash/redis/docs/commands/functions/list.mdx
+ */
+export class FunctionListCommand extends Command<unknown, RedisFunctionLibrary[]> {
+  constructor(
+    [args]: [args?: FunctionListArgs],
+    opts?: CommandOptions<unknown, RedisFunctionLibrary[]>
+  ) {
+    const command: (string | number | boolean)[] = ["function", "list"];
+    if (args?.libraryName) {
+      command.push("libraryname", args.libraryName);
+    }
+    if (args?.withCode) {
+      command.push("withcode");
+    }
+    super(command, { deserialize, ...opts });
+  }
+}
+
+function deserialize(result: unknown): RedisFunctionLibrary[] {
+  if (!Array.isArray(result)) return [];
+
+  return result.map((libRaw) => {
+    const lib = kvArrayToObject<{
+      library_name: string;
+      engine: string;
+      functions: unknown[];
+      library_code: string;
+    }>(libRaw);
+
+    const functionsParsed = lib.functions.map((fnRaw) =>
+      kvArrayToObject<{ name: string; description: string | null; flags: string[] }>(fnRaw)
+    );
+
+    return {
+      libraryName: lib.library_name,
+      engine: lib.engine,
+      functions: functionsParsed.map((fn) => ({
+        name: fn.name,
+        description: fn.description ?? undefined,
+        flags: fn.flags,
+      })),
+      libraryCode: lib.library_code,
+    };
+  });
+}

package/src/pkg/commands/function_load.ts

@@ -0,0 +1,31 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type FunctionLoadArgs = {
+  /**
+   * The Lua code to load.
+   *
+   * Example:
+   * ```lua
+   * #!lua name=mylib
+   * redis.register_function('myfunc', function() return 'ok' end)
+   * ```
+   */
+  code: string;
+  /**
+   * If true, the library will replace the existing library with the same name.
+   *
+   * @default false
+   */
+  replace?: boolean;
+};
+
+/**
+ * @see https://redis.io/docs/latest/commands/function-load/
+ * @see node_modules/@upstash/redis/docs/commands/functions/load.mdx
+ */
+export class FunctionLoadCommand extends Command<string, string> {
+  constructor([args]: [args: FunctionLoadArgs], opts?: CommandOptions<string, string>) {
+    super(["function", "load", ...(args.replace ? ["replace"] : []), args.code], opts);
+  }
+}

package/src/pkg/commands/function_stats.ts

@@ -0,0 +1,42 @@
+import { kvArrayToObject } from "../util";
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+type RedisFunctionStats = ReturnType<typeof deserialize>;
+
+/**
+ * @see https://redis.io/docs/latest/commands/function-stats/
+ * @see node_modules/@upstash/redis/docs/commands/functions/stats.mdx
+ *
+ * Note: `running_script` is always null in Upstash and therefore not included in the type.
+ */
+export class FunctionStatsCommand extends Command<unknown, RedisFunctionStats> {
+  constructor(opts?: CommandOptions<unknown, RedisFunctionStats>) {
+    super(["function", "stats"], { deserialize, ...opts });
+  }
+}
+
+function deserialize(result: unknown) {
+  // Object of { engines: { LUA: [k1, v1, k2, v2, ...] }}
+  const rawEngines = kvArrayToObject(kvArrayToObject(result).engines);
+
+  // Parses inside LUA: [k1, v1 ...] into LUA: { libraries_count: v1, functions_count: v2 }
+  const parsedEngines = Object.fromEntries(
+    Object.entries(rawEngines).map(([key, value]) => [key, kvArrayToObject(value)])
+  );
+
+  // Converts to camelCased keys
+  const final = {
+    engines: Object.fromEntries(
+      Object.entries(parsedEngines).map(([key, value]) => [
+        key,
+        {
+          librariesCount: value.libraries_count,
+          functionsCount: value.functions_count,
+        },
+      ])
+    ),
+  };
+
+  return final;
+}

package/src/pkg/commands/geo_add.ts

@@ -0,0 +1,54 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type GeoAddCommandOptions =
+  | {
+      nx?: boolean;
+      xx?: never;
+    }
+  | ({
+      nx?: never;
+      xx?: boolean;
+    } & { ch?: boolean });
+
+export type GeoMember<TMemberType> = {
+  latitude: number;
+  longitude: number;
+  member: TMemberType;
+};
+
+/**
+ * @see https://redis.io/commands/geoadd
+ */
+export class GeoAddCommand<TMemberType = string> extends Command<number | null, number | null> {
+  constructor(
+    [key, arg1, ...arg2]: [
+      string,
+      GeoMember<TMemberType> | GeoAddCommandOptions,
+      ...GeoMember<TMemberType>[],
+    ],
+    opts?: CommandOptions<number | null, number | null>
+  ) {
+    const command: unknown[] = ["geoadd", 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 ("latitude" in arg1 && arg1.latitude) {
+      command.push(arg1.longitude, arg1.latitude, arg1.member);
+    }
+
+    command.push(
+      ...arg2.flatMap(({ latitude, longitude, member }) => [longitude, latitude, member])
+    );
+
+    super(command, opts);
+  }
+}

package/src/pkg/commands/geo_dist.ts

@@ -0,0 +1,19 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/geodist
+ */
+export class GeoDistCommand<TMemberType = string> extends Command<number | null, number | null> {
+  constructor(
+    [key, member1, member2, unit = "M"]: [
+      key: string,
+      member1: TMemberType,
+      member2: TMemberType,
+      unit?: "M" | "KM" | "FT" | "MI",
+    ],
+    opts?: CommandOptions<number | null, number | null>
+  ) {
+    super(["GEODIST", key, member1, member2, unit], opts);
+  }
+}

package/src/pkg/commands/geo_hash.ts

@@ -0,0 +1,23 @@
+import type { CommandOptions } from "./command.ts";
+import { Command } from "./command.ts";
+
+/**
+ * @see https://redis.io/commands/geohash
+ */
+export class GeoHashCommand<TMember = string> extends Command<
+  (string | null)[],
+  (string | null)[]
+> {
+  constructor(
+    cmd: [string, ...TMember[]],
+    opts?: CommandOptions<(string | null)[], (string | null)[]>
+  ) {
+    const [key] = cmd;
+    // Check if the second argument is an array of strings (members).
+    // If it is, use it directly; if not, it means the members were passed individually,
+    // so we slice the cmd from the second element onwards to get the members.
+    const members = Array.isArray(cmd[1]) ? cmd[1] : cmd.slice(1);
+
+    super(["GEOHASH", key, ...members], opts);
+  }
+}

package/src/pkg/commands/geo_pos.ts

@@ -0,0 +1,39 @@
+import type { CommandOptions } from "./command.ts";
+import { Command } from "./command.ts";
+
+type Coordinates = {
+  lng: number;
+  lat: number;
+};
+
+/**
+ * @see https://redis.io/commands/geopos
+ */
+export class GeoPosCommand<TMember = string> extends Command<(string | null)[][], Coordinates[]> {
+  constructor(
+    cmd: [string, ...(TMember[] | TMember[])],
+    opts?: CommandOptions<(string | null)[][], Coordinates[]>
+  ) {
+    const [key] = cmd;
+    // Check if the second argument is an array of strings (members).
+    // If it is, use it directly; if not, it means the members were passed individually,
+    // so we slice the cmd from the second element onwards to get the members.
+    const members = Array.isArray(cmd[1]) ? cmd[1] : cmd.slice(1);
+
+    super(["GEOPOS", key, ...members], {
+      deserialize: (result) => transform(result),
+      ...opts,
+    });
+  }
+}
+
+function transform(result: (string | null)[][]): Coordinates[] {
+  const final: Coordinates[] = [];
+  for (const pos of result) {
+    if (!pos?.[0] || !pos?.[1]) {
+      continue;
+    }
+    final.push({ lng: Number.parseFloat(pos[0]), lat: Number.parseFloat(pos[1]) });
+  }
+  return final;
+}