@upstash/redis 1.40.0 → 1.41.0

package/src/pkg/commands/arinsert.ts

@@ -0,0 +1,24 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Appends one or more values after the array's append cursor.
+ *
+ * Returns the index the last value was written to (not the number of values written).
+ *
+ * Indexes are returned as strings; see `arlen`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arinsert
+ * @see node_modules/@upstash/redis/docs/commands/array/arinsert.mdx
+ */
+export class ArInsertCommand<TData = string> extends Command<number | string, string> {
+  constructor(
+    cmd: [key: string, ...values: TData[]],
+    opts?: CommandOptions<number | string, string>
+  ) {
+    super(["ARINSERT", ...cmd], {
+      deserialize: String,
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/arlastitems.ts

@@ -0,0 +1,29 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type ArLastItemsOptions = {
+  /**
+   * Return the newest value first instead of last.
+   */
+  rev?: boolean;
+};
+
+/**
+ * Returns up to `count` of the most recently appended values, walking backwards from the append
+ * cursor. Values come back oldest-first unless `rev` is set.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arlastitems
+ * @see node_modules/@upstash/redis/docs/commands/array/arlastitems.mdx
+ */
+export class ArLastItemsCommand<TData = string> extends Command<unknown[], (TData | null)[]> {
+  constructor(
+    [key, count, opts]: [key: string, count: number, opts?: ArLastItemsOptions],
+    cmdOpts?: CommandOptions<unknown[], (TData | null)[]>
+  ) {
+    const command: unknown[] = ["ARLASTITEMS", key, count];
+    if (opts?.rev) {
+      command.push("REV");
+    }
+    super(command, cmdOpts);
+  }
+}

package/src/pkg/commands/arlen.ts

@@ -0,0 +1,23 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Returns the length of an array: the highest occupied index plus one. A missing key has length `0`.
+ *
+ * Because arrays are sparse this can be larger than the number of stored values, see `arcount`.
+ *
+ * Indexes are returned as strings: they run up to 2^64-2, past what a JavaScript number can hold
+ * exactly. This matches how the SDK keeps the `scan` cursor a string, and the value can be passed
+ * straight back into any command that takes an index.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arlen
+ * @see node_modules/@upstash/redis/docs/commands/array/arlen.mdx
+ */
+export class ArLenCommand extends Command<number | string, string> {
+  constructor(cmd: [key: string], opts?: CommandOptions<number | string, string>) {
+    super(["ARLEN", ...cmd], {
+      deserialize: String,
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/armget.ts

@@ -0,0 +1,18 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Returns the values at several indexes, in the order the indexes were given, with `null` for
+ * empty slots.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/armget
+ * @see node_modules/@upstash/redis/docs/commands/array/armget.mdx
+ */
+export class ArMGetCommand<TData = string> extends Command<unknown[], (TData | null)[]> {
+  constructor(
+    cmd: [key: string, ...indexes: (number | string)[]],
+    opts?: CommandOptions<unknown[], (TData | null)[]>
+  ) {
+    super(["ARMGET", ...cmd], opts);
+  }
+}

package/src/pkg/commands/armset.ts

@@ -0,0 +1,26 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Index-value pairs for `ARMSET`, either as an object (`{ 0: "a", 10: "b" }`) or as a list of
+ * `[index, value]` tuples.
+ */
+export type ArMSetValues<TData> = Record<number | string, TData> | [number | string, TData][];
+
+/**
+ * Writes several index-value pairs into an array in one atomic call.
+ *
+ * Returns the number of slots that were newly occupied. Overwriting an existing value contributes `0`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/armset
+ * @see node_modules/@upstash/redis/docs/commands/array/armset.mdx
+ */
+export class ArMSetCommand<TData = string> extends Command<number, number> {
+  constructor(
+    [key, values]: [key: string, values: ArMSetValues<TData>],
+    opts?: CommandOptions<number, number>
+  ) {
+    const pairs = Array.isArray(values) ? values : Object.entries(values);
+    super(["ARMSET", key, ...pairs.flatMap(([index, value]) => [index, value])], opts);
+  }
+}

package/src/pkg/commands/arnext.ts

@@ -0,0 +1,20 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Returns the index the next `arinsert` would write to, without moving the cursor.
+ *
+ * Returns `"0"` for a missing key or one that was never appended to, and `null` when the cursor is
+ * already at the highest supported index. Indexes are returned as strings; see `arlen`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arnext
+ * @see node_modules/@upstash/redis/docs/commands/array/arnext.mdx
+ */
+export class ArNextCommand extends Command<number | string | null, string | null> {
+  constructor(cmd: [key: string], opts?: CommandOptions<number | string | null, string | null>) {
+    super(["ARNEXT", ...cmd], {
+      deserialize: (result) => (result === null ? null : String(result)),
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/arop.ts

@@ -0,0 +1,48 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+type ArOpKeyword = "SUM" | "MIN" | "MAX" | "AND" | "OR" | "XOR" | "USED";
+
+/**
+ * Reduction applied by `AROP`:
+ * - `SUM`, `MIN`, `MAX`: numeric aggregates
+ * - `AND`, `OR`, `XOR`: bitwise folds over the values as 64-bit integers
+ * - `USED`: number of occupied slots
+ * - `{ match: value }`: number of slots whose value equals `value`
+ */
+export type ArOpOperation<TData = string> = ArOpKeyword | Lowercase<ArOpKeyword> | { match: TData };
+
+/**
+ * Reduces the values in the inclusive range `[start, end]` to a single number on the server.
+ *
+ * `SUM`, `MIN`, `MAX`, `AND`, `OR` and `XOR` skip non-numeric values and return `null` when the
+ * range contains nothing they could use. `USED` and `match` always return a number.
+ *
+ * Results are returned as JavaScript numbers, so bitwise results beyond `Number.MAX_SAFE_INTEGER`
+ * lose precision.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arop
+ * @see node_modules/@upstash/redis/docs/commands/array/arop.mdx
+ */
+export class ArOpCommand<TData = string> extends Command<string | number | null, number | null> {
+  constructor(
+    [key, start, end, operation]: [
+      key: string,
+      start: number | string,
+      end: number | string,
+      operation: ArOpOperation<TData>,
+    ],
+    opts?: CommandOptions<string | number | null, number | null>
+  ) {
+    const command: unknown[] = ["AROP", key, start, end];
+    if (typeof operation === "string") {
+      command.push(operation.toUpperCase());
+    } else {
+      command.push("MATCH", operation.match);
+    }
+    super(command, {
+      deserialize: (result) => (result === null ? null : Number(result)),
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/arring.ts

@@ -0,0 +1,23 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Appends values to a fixed-size ring of `size` slots, wrapping back to index `0` and overwriting
+ * the oldest values once the ring is full. Calling it with a different `size` reshapes the ring.
+ *
+ * Returns the index the last value was written to, as a string; see `arlen`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arring
+ * @see node_modules/@upstash/redis/docs/commands/array/arring.mdx
+ */
+export class ArRingCommand<TData = string> extends Command<number | string, string> {
+  constructor(
+    cmd: [key: string, size: number, ...values: TData[]],
+    opts?: CommandOptions<number | string, string>
+  ) {
+    super(["ARRING", ...cmd], {
+      deserialize: String,
+      ...opts,
+    });
+  }
+}

package/src/pkg/commands/arscan.ts

@@ -0,0 +1,44 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import { parseResponse } from "../util";
+
+export type ArScanOptions = {
+  /**
+   * Maximum number of slots to return.
+   */
+  limit?: number;
+};
+
+/**
+ * Returns the occupied slots in the inclusive range `[start, end]` as `[index, value]` pairs, in
+ * ascending index order. Empty slots are skipped.
+ *
+ * Indexes are returned as strings; see `arlen`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arscan
+ * @see node_modules/@upstash/redis/docs/commands/array/arscan.mdx
+ */
+export class ArScanCommand<TData = string> extends Command<unknown[], [string, TData][]> {
+  constructor(
+    [key, start, end, opts]: [
+      key: string,
+      start: number | string,
+      end: number | string,
+      opts?: ArScanOptions,
+    ],
+    cmdOpts?: CommandOptions<unknown[], [string, TData][]>
+  ) {
+    const command: unknown[] = ["ARSCAN", key, start, end];
+    if (opts?.limit !== undefined) {
+      command.push("LIMIT", opts.limit);
+    }
+    super(command, {
+      deserialize: (result) =>
+        parseResponse<[number | string, TData][]>(result).map(([index, value]) => [
+          String(index),
+          value,
+        ]),
+      ...cmdOpts,
+    });
+  }
+}

package/src/pkg/commands/arseek.ts

@@ -0,0 +1,17 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Moves the append cursor so that the next `arinsert` writes to `index`. Stored values are not
+ * touched.
+ *
+ * Returns `1` if the cursor was moved, `0` if the key does not exist.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arseek
+ * @see node_modules/@upstash/redis/docs/commands/array/arseek.mdx
+ */
+export class ArSeekCommand extends Command<0 | 1, 0 | 1> {
+  constructor(cmd: [key: string, index: number | string], opts?: CommandOptions<0 | 1, 0 | 1>) {
+    super(["ARSEEK", ...cmd], opts);
+  }
+}

package/src/pkg/commands/arset.ts

@@ -0,0 +1,20 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Writes one or more values into an array, starting at `index`: the first value goes to `index`,
+ * the next to `index + 1`, and so on.
+ *
+ * Returns the number of slots that were newly occupied. Overwriting an existing value contributes `0`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arset
+ * @see node_modules/@upstash/redis/docs/commands/array/arset.mdx
+ */
+export class ArSetCommand<TData = string> extends Command<number, number> {
+  constructor(
+    cmd: [key: string, index: number | string, ...values: TData[]],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["ARSET", ...cmd], opts);
+  }
+}

package/src/pkg/commands/bitcount.ts

@@ -0,0 +1,30 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/bitcount
+ * @see node_modules/@upstash/redis/docs/commands/bitmap/bitcount.mdx
+ */
+export class BitCountCommand extends Command<number, number> {
+  constructor(
+    cmd: [key: string, start?: never, end?: never],
+    opts?: CommandOptions<number, number>
+  );
+  constructor(
+    cmd: [key: string, start: number, end: number],
+    opts?: CommandOptions<number, number>
+  );
+  constructor(
+    [key, start, end]: [key: string, start?: number, end?: number],
+    opts?: CommandOptions<number, number>
+  ) {
+    const command: unknown[] = ["bitcount", key];
+    if (typeof start === "number") {
+      command.push(start);
+    }
+    if (typeof end === "number") {
+      command.push(end);
+    }
+    super(command, opts);
+  }
+}

package/src/pkg/commands/bitfield.ts

@@ -0,0 +1,50 @@
+import { type Requester } from "../http";
+import { Command, type CommandOptions } from "./command";
+
+type SubCommandArgs<TRest extends unknown[] = []> = [
+  encoding: string, // u1 - u63 | i1 - i64
+  offset: number | string, // <int> | #<int>
+  ...rest: TRest,
+];
+
+/**
+ * @see https://redis.io/commands/bitfield
+ */
+export class BitFieldCommand<T = Promise<number[]>> {
+  private command: (string | number)[];
+
+  constructor(
+    args: [key: string],
+    private client: Requester,
+    private opts?: CommandOptions<number[], number[]>,
+    private execOperation = (command: Command<number[], number[]>) => command.exec(this.client) as T
+  ) {
+    this.command = ["bitfield", ...args];
+  }
+
+  private chain(...args: typeof this.command) {
+    this.command.push(...args);
+    return this;
+  }
+
+  get(...args: SubCommandArgs) {
+    return this.chain("get", ...args);
+  }
+
+  set(...args: SubCommandArgs<[value: number]>) {
+    return this.chain("set", ...args);
+  }
+
+  incrby(...args: SubCommandArgs<[increment: number]>) {
+    return this.chain("incrby", ...args);
+  }
+
+  overflow(overflow: "WRAP" | "SAT" | "FAIL") {
+    return this.chain("overflow", overflow);
+  }
+
+  exec() {
+    const command = new Command(this.command, this.opts);
+    return this.execOperation(command);
+  }
+}

package/src/pkg/commands/bitop.ts

@@ -0,0 +1,35 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/bitop
+ * @see node_modules/@upstash/redis/docs/commands/bitmap/bitop.mdx
+ */
+export class BitOpCommand extends Command<number, number> {
+  constructor(
+    cmd: [op: "and" | "or" | "xor", destinationKey: string, ...sourceKeys: string[]],
+    opts?: CommandOptions<number, number>
+  );
+  constructor(
+    cmd: [op: "not", destinationKey: string, sourceKey: string],
+    opts?: CommandOptions<number, number>
+  );
+  constructor(
+    cmd: [op: "diff" | "diff1" | "andor", destinationKey: string, x: string, ...y: string[]],
+    opts?: CommandOptions<number, number>
+  );
+  constructor(
+    cmd: [op: "one", destinationKey: string, ...sourceKeys: string[]],
+    opts?: CommandOptions<number, number>
+  );
+  constructor(
+    cmd: [
+      op: "and" | "or" | "xor" | "not" | "diff" | "diff1" | "andor" | "one",
+      destinationKey: string,
+      ...sourceKeys: string[],
+    ],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["bitop", ...cmd], opts);
+  }
+}

package/src/pkg/commands/bitpos.ts

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

package/src/pkg/commands/client_setinfo.ts

@@ -0,0 +1,17 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type ClientSetInfoAttribute = "LIB-NAME" | "lib-name" | "LIB-VER" | "lib-ver";
+
+/**
+ * @see https://redis.io/commands/client-setinfo
+ * @see node_modules/@upstash/redis/docs/commands/connection/client_setinfo.mdx
+ */
+export class ClientSetInfoCommand extends Command<string, string> {
+  constructor(
+    [attribute, value]: [attribute: ClientSetInfoAttribute, value: string],
+    opts?: CommandOptions<string, string>
+  ) {
+    super(["CLIENT", "SETINFO", attribute.toUpperCase(), value], opts);
+  }
+}

package/src/pkg/commands/command.ts

@@ -0,0 +1,142 @@
+import { UpstashError } from "../error";
+import type { Requester } from "../http";
+import { parseResponse } from "../util";
+
+type Serialize = (data: unknown) => string | number | boolean;
+type Deserialize<TResult, TData> = (result: TResult) => TData;
+
+const defaultSerializer: Serialize = (c: unknown) => {
+  switch (typeof c) {
+    case "string":
+    case "number":
+    case "boolean": {
+      return c;
+    }
+
+    default: {
+      return JSON.stringify(c);
+    }
+  }
+};
+
+export type CommandOptions<TResult, TData> = {
+  /**
+   * Custom deserializer
+   */
+  deserialize?: (result: TResult) => TData;
+  /**
+   * Automatically try to deserialize the returned data from upstash using `JSON.deserialize`
+   *
+   * @default true
+   */
+  automaticDeserialization?: boolean;
+  latencyLogging?: boolean;
+  /**
+   * Additional headers to be sent with the request
+   */
+  headers?: Record<string, string>;
+
+  /**
+   * Path to append to the URL
+   */
+  path?: string[];
+
+  /**
+   * Options for streaming requests, mainly used for subscribe, monitor commands
+   **/
+  streamOptions?: {
+    /**
+     * Callback to be called when a message is received
+     */
+    onMessage?: (data: string) => void;
+
+    /**
+     * Whether the request is streaming
+     */
+    isStreaming?: boolean;
+
+    /**
+     * Signal to abort the request
+     */
+    signal?: AbortSignal;
+  };
+};
+/**
+ * Command offers default (de)serialization and the exec method to all commands.
+ *
+ * TData represents what the user will enter or receive,
+ * TResult is the raw data returned from upstash, which may need to be transformed or parsed.
+ */
+export class Command<TResult, TData> {
+  public readonly command: (string | number | boolean)[];
+  public readonly serialize: Serialize;
+  public readonly deserialize: Deserialize<TResult, TData>;
+  protected readonly headers?: Record<string, string>;
+  protected readonly path?: string[];
+  protected readonly onMessage?: (data: string) => void;
+  protected readonly isStreaming: boolean;
+  protected readonly signal?: AbortSignal;
+  /**
+   * Create a new command instance.
+   *
+   * You can define a custom `deserialize` function. By default we try to deserialize as json.
+   */
+  constructor(
+    command: (string | boolean | number | unknown)[],
+    opts?: CommandOptions<TResult, TData>
+  ) {
+    this.serialize = defaultSerializer;
+    this.deserialize =
+      opts?.automaticDeserialization === undefined || opts.automaticDeserialization
+        ? (opts?.deserialize ?? parseResponse)
+        : (x) => x as unknown as TData;
+
+    this.command = command.map((c) => this.serialize(c));
+    this.headers = opts?.headers;
+    this.path = opts?.path;
+    this.onMessage = opts?.streamOptions?.onMessage;
+    this.isStreaming = opts?.streamOptions?.isStreaming ?? false;
+    this.signal = opts?.streamOptions?.signal;
+
+    if (opts?.latencyLogging) {
+      const originalExec = this.exec.bind(this);
+      this.exec = async (client: Requester): Promise<TData> => {
+        const start = performance.now();
+        const result = await originalExec(client);
+        const end = performance.now();
+        const loggerResult = (end - start).toFixed(2);
+        // eslint-disable-next-line no-console
+        console.log(
+          `Latency for \u001B[38;2;19;185;39m${this.command[0]
+            .toString()
+            .toUpperCase()}\u001B[0m: \u001B[38;2;0;255;255m${loggerResult} ms\u001B[0m`
+        );
+        return result;
+      };
+    }
+  }
+
+  /**
+   * Execute the command using a client.
+   */
+  public async exec(client: Requester): Promise<TData> {
+    const { result, error } = await client.request<TResult>({
+      body: this.command,
+      path: this.path,
+      upstashSyncToken: client.upstashSyncToken,
+      headers: this.headers,
+      onMessage: this.onMessage,
+      isStreaming: this.isStreaming,
+      signal: this.signal,
+    });
+
+    if (error) {
+      throw new UpstashError(error);
+    }
+    if (result === undefined) {
+      throw new TypeError("Request did not return a result");
+    }
+
+    return this.deserialize(result);
+  }
+}

package/src/pkg/commands/copy.ts

@@ -0,0 +1,22 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * @see https://redis.io/commands/copy
+ */
+export class CopyCommand extends Command<number, "COPIED" | "NOT_COPIED"> {
+  constructor(
+    [key, destinationKey, opts]: [key: string, destinationKey: string, opts?: { replace: boolean }],
+    commandOptions?: CommandOptions<number, "COPIED" | "NOT_COPIED">
+  ) {
+    super(["COPY", key, destinationKey, ...(opts?.replace ? ["REPLACE"] : [])], {
+      ...commandOptions,
+      deserialize(result) {
+        if (result > 0) {
+          return "COPIED";
+        }
+        return "NOT_COPIED";
+      },
+    });
+  }
+}

package/src/pkg/commands/dbsize.ts

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

package/src/pkg/commands/decr.ts

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

package/src/pkg/commands/decrby.ts

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

package/src/pkg/commands/del.ts

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