@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/geo_search.ts

@@ -0,0 +1,140 @@
+import { parseJSON } from "../util.ts";
+import type { CommandOptions } from "./command.ts";
+import { Command } from "./command.ts";
+
+type RadiusOptions = "M" | "KM" | "FT" | "MI";
+type CenterPoint<TMemberType> =
+  | {
+      type: "FROMMEMBER" | "frommember";
+      member: TMemberType;
+    }
+  | {
+      type: "FROMLONLAT" | "fromlonlat";
+      coordinate: { lon: number; lat: number };
+    };
+
+type Shape =
+  | { type: "BYRADIUS" | "byradius"; radius: number; radiusType: RadiusOptions }
+  | {
+      type: "BYBOX" | "bybox";
+      rect: { width: number; height: number };
+      rectType: RadiusOptions;
+    };
+
+type GeoSearchCommandOptions = {
+  count?: { limit: number; any?: boolean };
+  withCoord?: boolean;
+  withDist?: boolean;
+  withHash?: boolean;
+};
+
+type OptionMappings = {
+  withHash: "hash";
+  withCoord: "coord";
+  withDist: "dist";
+};
+
+type GeoSearchOptions<TOptions> = {
+  [K in keyof TOptions as K extends keyof OptionMappings
+    ? OptionMappings[K]
+    : never]: K extends "withHash"
+    ? string
+    : K extends "withCoord"
+      ? { long: number; lat: number }
+      : K extends "withDist"
+        ? number
+        : never;
+};
+
+type GeoSearchResponse<TOptions, TMemberType> = ({
+  member: TMemberType;
+} & GeoSearchOptions<TOptions>)[];
+
+/**
+ * @see https://redis.io/commands/geosearch
+ */
+export class GeoSearchCommand<
+  TMemberType = string,
+  TOptions extends GeoSearchCommandOptions = GeoSearchCommandOptions,
+> extends Command<any[] | any[][], GeoSearchResponse<TOptions, TMemberType>> {
+  constructor(
+    [key, centerPoint, shape, order, opts]: [
+      key: string,
+      centerPoint: CenterPoint<TMemberType>,
+      shape: Shape,
+      order: "ASC" | "DESC" | "asc" | "desc",
+      opts?: TOptions,
+    ],
+    commandOptions?: CommandOptions<any[] | any[][], GeoSearchResponse<TOptions, TMemberType>>
+  ) {
+    const command: unknown[] = ["GEOSEARCH", key];
+
+    if (centerPoint.type === "FROMMEMBER" || centerPoint.type === "frommember") {
+      command.push(centerPoint.type, centerPoint.member);
+    }
+    if (centerPoint.type === "FROMLONLAT" || centerPoint.type === "fromlonlat") {
+      command.push(centerPoint.type, centerPoint.coordinate.lon, centerPoint.coordinate.lat);
+    }
+
+    if (shape.type === "BYRADIUS" || shape.type === "byradius") {
+      command.push(shape.type, shape.radius, shape.radiusType);
+    }
+    if (shape.type === "BYBOX" || shape.type === "bybox") {
+      command.push(shape.type, shape.rect.width, shape.rect.height, shape.rectType);
+    }
+    command.push(order);
+
+    if (opts?.count) {
+      command.push("COUNT", opts.count.limit, ...(opts.count.any ? ["ANY"] : []));
+    }
+
+    const transform = (result: string[] | string[][]) => {
+      if (!opts?.withCoord && !opts?.withDist && !opts?.withHash) {
+        return result.map((member) => {
+          try {
+            return { member: parseJSON(member as string) };
+          } catch {
+            return { member };
+          }
+        });
+      }
+      return result.map((members) => {
+        let counter = 1;
+        const obj = {} as any;
+
+        try {
+          obj.member = parseJSON(members[0]);
+        } catch {
+          obj.member = members[0];
+        }
+
+        if (opts.withDist) {
+          obj.dist = Number.parseFloat(members[counter++]);
+        }
+        if (opts.withHash) {
+          obj.hash = members[counter++].toString();
+        }
+        if (opts.withCoord) {
+          obj.coord = {
+            long: Number.parseFloat(members[counter][0]),
+            lat: Number.parseFloat(members[counter][1]),
+          };
+        }
+        return obj;
+      });
+    };
+
+    super(
+      [
+        ...command,
+        ...(opts?.withCoord ? ["WITHCOORD"] : []),
+        ...(opts?.withDist ? ["WITHDIST"] : []),
+        ...(opts?.withHash ? ["WITHHASH"] : []),
+      ],
+      {
+        deserialize: transform,
+        ...commandOptions,
+      }
+    );
+  }
+}

package/src/pkg/commands/geo_search_store.ts

@@ -0,0 +1,69 @@
+import type { CommandOptions } from "./command.ts";
+import { Command } from "./command.ts";
+
+type RadiusOptions = "M" | "KM" | "FT" | "MI";
+type CenterPoint<TMemberType> =
+  | {
+      type: "FROMMEMBER" | "frommember";
+      member: TMemberType;
+    }
+  | {
+      type: "FROMLONLAT" | "fromlonlat";
+      coordinate: { lon: number; lat: number };
+    };
+
+type Shape =
+  | { type: "BYRADIUS" | "byradius"; radius: number; radiusType: RadiusOptions }
+  | {
+      type: "BYBOX" | "bybox";
+      rect: { width: number; height: number };
+      rectType: RadiusOptions;
+    };
+
+type GeoSearchCommandOptions = {
+  count?: { limit: number; any?: boolean };
+  storeDist?: boolean;
+};
+
+/**
+ * @see https://redis.io/commands/geosearchstore
+ */
+export class GeoSearchStoreCommand<
+  TMemberType = string,
+  TOptions extends GeoSearchCommandOptions = GeoSearchCommandOptions,
+> extends Command<any[] | any[][], number> {
+  constructor(
+    [destination, key, centerPoint, shape, order, opts]: [
+      destination: string,
+      key: string,
+      centerPoint: CenterPoint<TMemberType>,
+      shape: Shape,
+      order: "ASC" | "DESC" | "asc" | "desc",
+      opts?: TOptions,
+    ],
+    commandOptions?: CommandOptions<any[] | any[][], number>
+  ) {
+    const command: unknown[] = ["GEOSEARCHSTORE", destination, key];
+
+    if (centerPoint.type === "FROMMEMBER" || centerPoint.type === "frommember") {
+      command.push(centerPoint.type, centerPoint.member);
+    }
+    if (centerPoint.type === "FROMLONLAT" || centerPoint.type === "fromlonlat") {
+      command.push(centerPoint.type, centerPoint.coordinate.lon, centerPoint.coordinate.lat);
+    }
+
+    if (shape.type === "BYRADIUS" || shape.type === "byradius") {
+      command.push(shape.type, shape.radius, shape.radiusType);
+    }
+    if (shape.type === "BYBOX" || shape.type === "bybox") {
+      command.push(shape.type, shape.rect.width, shape.rect.height, shape.rectType);
+    }
+    command.push(order);
+
+    if (opts?.count) {
+      command.push("COUNT", opts.count.limit, ...(opts.count.any ? ["ANY"] : []));
+    }
+
+    super([...command, ...(opts?.storeDist ? ["STOREDIST"] : [])], commandOptions);
+  }
+}

package/src/pkg/commands/get.ts

@@ -0,0 +1,15 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/get
+ * @see node_modules/@upstash/redis/docs/commands/string/get.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 GetCommand<TData = string> extends Command<unknown | null, TData | null> {
+  constructor(cmd: [key: string], opts?: CommandOptions<unknown | null, TData | null>) {
+    super(["get", ...cmd], opts);
+  }
+}

package/src/pkg/commands/getbit.ts

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

package/src/pkg/commands/getdel.ts

@@ -0,0 +1,15 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/getdel
+ * @see node_modules/@upstash/redis/docs/commands/string/getdel.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 GetDelCommand<TData = string> extends Command<unknown | null, TData | null> {
+  constructor(cmd: [key: string], opts?: CommandOptions<unknown | null, TData | null>) {
+    super(["getdel", ...cmd], opts);
+  }
+}

package/src/pkg/commands/getex.ts

@@ -0,0 +1,36 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+type GetExCommandOptions =
+  | { ex: number; px?: never; exat?: never; pxat?: never; persist?: never }
+  | { ex?: never; px: number; exat?: never; pxat?: never; persist?: never }
+  | { ex?: never; px?: never; exat: number; pxat?: never; persist?: never }
+  | { ex?: never; px?: never; exat?: never; pxat: number; persist?: never }
+  | { ex?: never; px?: never; exat?: never; pxat?: never; persist: true }
+  | { ex?: never; px?: never; exat?: never; pxat?: never; persist?: never };
+
+/**
+ * @see https://redis.io/commands/getex
+ */
+export class GetExCommand<TData = string> extends Command<unknown | null, TData | null> {
+  constructor(
+    [key, opts]: [key: string, opts?: GetExCommandOptions],
+    cmdOpts?: CommandOptions<unknown | null, TData | null>
+  ) {
+    const command: unknown[] = ["getex", key];
+    if (opts) {
+      if ("ex" in opts && typeof opts.ex === "number") {
+        command.push("ex", opts.ex);
+      } else if ("px" in opts && typeof opts.px === "number") {
+        command.push("px", opts.px);
+      } else if ("exat" in opts && typeof opts.exat === "number") {
+        command.push("exat", opts.exat);
+      } else if ("pxat" in opts && typeof opts.pxat === "number") {
+        command.push("pxat", opts.pxat);
+      } else if ("persist" in opts && opts.persist) {
+        command.push("persist");
+      }
+    }
+    super(command, cmdOpts);
+  }
+}

package/src/pkg/commands/getrange.ts

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

package/src/pkg/commands/getset.ts

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

package/src/pkg/commands/hdel.ts

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

package/src/pkg/commands/hexists.ts

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

package/src/pkg/commands/hexpire.ts

@@ -0,0 +1,30 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import type { ExpireOption } from "./expire";
+
+export class HExpireCommand extends Command<(-2 | 0 | 1 | 2)[], (-2 | 0 | 1 | 2)[]> {
+  constructor(
+    cmd: [
+      key: string,
+      fields: (string | number) | (string | number)[],
+      seconds: number,
+      option?: ExpireOption,
+    ],
+    opts?: CommandOptions<(-2 | 0 | 1 | 2)[], (-2 | 0 | 1 | 2)[]>
+  ) {
+    const [key, fields, seconds, option] = cmd;
+    const fieldArray = Array.isArray(fields) ? fields : [fields];
+    super(
+      [
+        "hexpire",
+        key,
+        seconds,
+        ...(option ? [option] : []),
+        "FIELDS",
+        fieldArray.length,
+        ...fieldArray,
+      ],
+      opts
+    );
+  }
+}

package/src/pkg/commands/hexpireat.ts

@@ -0,0 +1,30 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import type { ExpireOption } from "./expire";
+
+export class HExpireAtCommand extends Command<(-2 | 0 | 1 | 2)[], (-2 | 0 | 1 | 2)[]> {
+  constructor(
+    cmd: [
+      key: string,
+      fields: (string | number) | (string | number)[],
+      timestamp: number,
+      option?: ExpireOption,
+    ],
+    opts?: CommandOptions<(-2 | 0 | 1 | 2)[], (-2 | 0 | 1 | 2)[]>
+  ) {
+    const [key, fields, timestamp, option] = cmd;
+    const fieldArray = Array.isArray(fields) ? fields : [fields];
+    super(
+      [
+        "hexpireat",
+        key,
+        timestamp,
+        ...(option ? [option] : []),
+        "FIELDS",
+        fieldArray.length,
+        ...fieldArray,
+      ],
+      opts
+    );
+  }
+}

package/src/pkg/commands/hexpiretime.ts

@@ -0,0 +1,13 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export class HExpireTimeCommand extends Command<number[], number[]> {
+  constructor(
+    cmd: [key: string, fields: (string | number) | (string | number)[]],
+    opts?: CommandOptions<number[], number[]>
+  ) {
+    const [key, fields] = cmd;
+    const fieldArray = Array.isArray(fields) ? fields : [fields];
+    super(["hexpiretime", key, "FIELDS", fieldArray.length, ...fieldArray], opts);
+  }
+}

package/src/pkg/commands/hget.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/hget
+ * @see node_modules/@upstash/redis/docs/commands/hash/hget.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 HGetCommand<TData> extends Command<unknown | null, TData | null> {
+  constructor(
+    cmd: [key: string, field: string],
+    opts?: CommandOptions<unknown | null, TData | null>
+  ) {
+    super(["hget", ...cmd], opts);
+  }
+}

package/src/pkg/commands/hgetall.ts

@@ -0,0 +1,44 @@
+import { parseJSON } from "../util";
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+function deserialize<TData extends Record<string, unknown>>(result: string[]): TData | null {
+  if (result.length === 0) {
+    return null;
+  }
+  const obj: Record<string, unknown> = {};
+  for (let i = 0; i < result.length; i += 2) {
+    const key = result[i];
+    const value = result[i + 1];
+    try {
+      // handle unsafe integer
+      const valueIsNumberAndNotSafeInteger =
+        !Number.isNaN(Number(value)) && !Number.isSafeInteger(Number(value));
+      obj[key] = valueIsNumberAndNotSafeInteger ? value : parseJSON(value);
+    } catch {
+      obj[key] = value;
+    }
+  }
+  return obj as TData;
+}
+
+/**
+ * @see https://redis.io/commands/hgetall
+ * @see node_modules/@upstash/redis/docs/commands/hash/hgetall.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.
+ * With automaticDeserialization: false, hgetall returns a flat array instead, such as
+ * ["text", "123", "version", "1"], and [] for a missing key.
+ */
+export class HGetAllCommand<TData extends Record<string, unknown>> extends Command<
+  unknown | null,
+  TData | null
+> {
+  constructor(cmd: [key: string], opts?: CommandOptions<unknown | null, TData | null>) {
+    super(["hgetall", ...cmd], {
+      deserialize: (result) => deserialize<TData>(result as string[]),
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/hgetdel.ts

@@ -0,0 +1,30 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import { deserialize } from "./hmget";
+
+/**
+ * HGETDEL returns the values of the specified fields and then atomically deletes them from the hash
+ * The field values are returned as an object like this:
+ * ```ts
+ * {[fieldName: string]: T | null}
+ * ```
+ *
+ * In case all fields are non-existent or the hash doesn't exist, `null` is returned
+ *
+ * @see https://redis.io/commands/hgetdel
+ * @see node_modules/@upstash/redis/docs/commands/hash/hgetdel.mdx
+ */
+export class HGetDelCommand<TData extends Record<string, unknown>> extends Command<
+  (string | null)[],
+  TData | null
+> {
+  constructor(
+    [key, ...fields]: [key: string, ...fields: (string | number)[]],
+    opts?: CommandOptions<(string | null)[], TData | null>
+  ) {
+    super(["hgetdel", key, "FIELDS", fields.length, ...fields], {
+      deserialize: (result) => deserialize<TData>(fields.map(String), result),
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/hgetex.ts

@@ -0,0 +1,56 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import { deserialize } from "./hmget";
+type HGetExCommandOptions =
+  | { ex: number; px?: never; exat?: never; pxat?: never; persist?: never }
+  | { ex?: never; px: number; exat?: never; pxat?: never; persist?: never }
+  | { ex?: never; px?: never; exat: number; pxat?: never; persist?: never }
+  | { ex?: never; px?: never; exat?: never; pxat: number; persist?: never }
+  | { ex?: never; px?: never; exat?: never; pxat?: never; persist: true };
+
+/**
+ * HGETEX returns the values of the specified fields and optionally sets their expiration time or TTL
+ * The field values are returned as an object like this:
+ * ```ts
+ * {[fieldName: string]: T | null}
+ * ```
+ *
+ * In case all fields are non-existent or the hash doesn't exist, `null` is returned
+ *
+ * @see https://redis.io/commands/hgetex
+ * @see node_modules/@upstash/redis/docs/commands/hash/hgetex.mdx
+ */
+export class HGetExCommand<TData extends Record<string, unknown>> extends Command<
+  (string | null)[],
+  TData | null
+> {
+  constructor(
+    [key, opts, ...fields]: [
+      key: string,
+      opts: HGetExCommandOptions,
+      ...fields: (string | number)[],
+    ],
+    cmdOpts?: CommandOptions<(string | null)[], TData | null>
+  ) {
+    const command: (string | number)[] = ["hgetex", key];
+
+    if ("ex" in opts && typeof opts.ex === "number") {
+      command.push("EX", opts.ex);
+    } else if ("px" in opts && typeof opts.px === "number") {
+      command.push("PX", opts.px);
+    } else if ("exat" in opts && typeof opts.exat === "number") {
+      command.push("EXAT", opts.exat);
+    } else if ("pxat" in opts && typeof opts.pxat === "number") {
+      command.push("PXAT", opts.pxat);
+    } else if ("persist" in opts && opts.persist) {
+      command.push("PERSIST");
+    }
+
+    command.push("FIELDS", fields.length, ...fields);
+
+    super(command, {
+      deserialize: (result) => deserialize<TData>(fields.map(String), result),
+      ...cmdOpts,
+    });
+  }
+}

package/src/pkg/commands/hincrby.ts

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

package/src/pkg/commands/hincrbyfloat.ts

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

package/src/pkg/commands/hkeys.ts

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

package/src/pkg/commands/hlen.ts

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