@upstash/redis 1.40.0 → 1.41.0

package/nodejs.mjs

@@ -5,7 +5,7 @@ import {
   VERSION,
   VectorIndex,
   error_exports
-} from "./chunk-RLVWMRRX.mjs";
+} from "./chunk-CGMWROAN.mjs";
 
 // pkg/commands/search/schema-builder.ts
 var BUILD = /* @__PURE__ */ Symbol("build");
@@ -133,6 +133,27 @@ var DateFieldBuilder = class _DateFieldBuilder {
     return { type: "DATE" };
   }
 };
+var HybridFieldBuilder = class _HybridFieldBuilder {
+  _noStem;
+  _from;
+  constructor(noStem = { noStem: false }, from = { from: null }) {
+    this._noStem = noStem;
+    this._from = from;
+  }
+  noStem() {
+    return new _HybridFieldBuilder({ noStem: true }, this._from);
+  }
+  from(field) {
+    return new _HybridFieldBuilder(this._noStem, { from: field });
+  }
+  [BUILD]() {
+    return {
+      type: "HYBRID",
+      ...this._noStem.noStem ? { noStem: true } : {},
+      ...this._from.from ? { from: this._from.from } : {}
+    };
+  }
+};
 var KeywordFieldBuilder = class {
   [BUILD]() {
     return { type: "KEYWORD" };
@@ -156,6 +177,14 @@ var s = {
   date() {
     return new DateFieldBuilder();
   },
+  /**
+   * A TEXT field that is also embedded for semantic search with `$ann`.
+   *
+   * @see https://upstash.com/docs/redis/search/hybrid-search
+   */
+  hybrid() {
+    return new HybridFieldBuilder();
+  },
   keyword() {
     return new KeywordFieldBuilder();
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upstash/redis",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "main": "./nodejs.js",
   "module": "./nodejs.mjs",
   "types": "./nodejs.d.ts",
@@ -51,12 +51,22 @@
     "upstash"
   ],
   "files": [
-    "./*"
+    "./*",
+    "!src/**/*.test.*",
+    "!src/**/*.test-d.*",
+    "!src/**/*.spec.*",
+    "!src/**/test-utils.*",
+    "!src/**/__tests__/**",
+    "!src/**/__snapshots__/**"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "scripts": {
-    "build": "tsup && cp package.json README.md ../../LICENSE dist/",
-    "test": "bun test pkg --bail --timeout 20000",
-    "check-exports": "bun run build && cd dist && attw -P"
+    "build": "tsup && mkdir -p dist/src && cp -R pkg platforms version.ts dist/src/ && find dist/src \\( -name '*.test.ts' -o -name test-utils.ts \\) -delete && cp package.json README.md ../../LICENSE dist/",
+    "test": "bun test ./pkg --bail --timeout 20000",
+    "check-exports": "bun run build && cd dist && attw -P",
+    "prepack": "giget gh:upstash/docs/redis/sdks/ts docs --force-clean 1>&2"
   },
   "publishConfig": {
     "access": "public"
@@ -69,6 +79,7 @@
   "homepage": "https://github.com/upstash/upstash-redis#readme",
   "devDependencies": {
     "@types/bun": "1.3.6",
+    "giget": "3.3.1",
     "tsup": "^8.2.3",
     "typescript": "latest"
   },

package/src/pkg/auto-pipeline.ts

@@ -0,0 +1,284 @@
+import type { Command } from "./commands/command";
+import { UpstashError } from "./error";
+import type { UpstashResponse } from "./http";
+import type { Pipeline } from "./pipeline";
+import type { Redis } from "./redis";
+import type { CommandArgs } from "./types";
+
+// properties which are only available in redis
+type redisOnly = Exclude<keyof Redis, keyof Pipeline>;
+
+export const MAX_PIPELINE_SIZE = 1000;
+
+const READ_COMMANDS: Set<string> = new Set([
+  // Array
+  "arcount",
+  "arget",
+  "argetrange",
+  "argrep",
+  "arinfo",
+  "arlastitems",
+  "arlen",
+  "armget",
+  "arnext",
+  "arop",
+  "arscan",
+  // String
+  "get",
+  "getrange",
+  "mget",
+  "strlen",
+  // Bit
+  "bitcount",
+  "bitpos",
+  "getbit",
+  // Hash
+  "hexists",
+  "hget",
+  "hgetall",
+  "hkeys",
+  "hlen",
+  "hmget",
+  "hrandfield",
+  "hscan",
+  "hstrlen",
+  "httl",
+  "hvals",
+  "hexpiretime",
+  "hpexpiretime",
+  "hpttl",
+  // List
+  "lindex",
+  "llen",
+  "lpos",
+  "lrange",
+  // Set
+  "scard",
+  "sdiff",
+  "sinter",
+  "sintercard",
+  "sismember",
+  "smembers",
+  "smismember",
+  "srandmember",
+  "sscan",
+  "sunion",
+  // Sorted set
+  "zcard",
+  "zcount",
+  "zlexcount",
+  "zmscore",
+  "zrange",
+  "zrank",
+  "zrevrank",
+  "zscan",
+  "zscore",
+  "zunion",
+  // Key metadata
+  "exists",
+  "type",
+  "ttl",
+  "pttl",
+  "randomkey",
+  "touch",
+  // HyperLogLog
+  "pfcount",
+  // Stream
+  "xinfo",
+  "xlen",
+  "xpending",
+  "xrange",
+  "xread",
+  "xrevrange",
+  // Geo
+  "geodist",
+  "geohash",
+  "geopos",
+  "geosearch",
+  // Script / eval
+  "scriptExists",
+  "evalRo",
+  "evalshaRo",
+  // Utility
+  "dbsize",
+  "echo",
+  "ping",
+  "time",
+  "scan",
+  "keys",
+  // JSON namespace
+  "arrindex",
+  "arrlen",
+  "objkeys",
+  "objlen",
+  "resp",
+  // Functions namespace
+  "list",
+  "stats",
+  "callRo",
+]);
+
+export const EXCLUDE_COMMANDS: Set<keyof Redis> = new Set([
+  "scan",
+  "keys",
+  "flushdb",
+  "flushall",
+  "dbsize",
+  "hscan",
+  "hgetall",
+  "hkeys",
+  "lrange",
+  "sscan",
+  "smembers",
+  "xrange",
+  "xrevrange",
+  "zscan",
+  "zrange",
+  "exec",
+]);
+
+type AutoPipelineNamespace = "root" | "json" | "functions";
+
+export function createAutoPipelineProxy(
+  _redis: Redis,
+  namespace: AutoPipelineNamespace = "root"
+): Redis {
+  const redis = _redis as Redis & {
+    autoPipelineExecutor: AutoPipelineExecutor;
+  };
+
+  if (!redis.autoPipelineExecutor) {
+    redis.autoPipelineExecutor = new AutoPipelineExecutor(redis);
+  }
+
+  return new Proxy(redis, {
+    get: (redis, command: "pipelineCounter" | keyof Pipeline | redisOnly) => {
+      // return pipelineCounter of autoPipelineExecutor
+      if (command === "pipelineCounter") {
+        return redis.autoPipelineExecutor.pipelineCounter;
+      }
+
+      // Namespace switching
+      if (namespace === "root" && command === "json") {
+        return createAutoPipelineProxy(redis, "json");
+      }
+      if (namespace === "root" && command === "functions") {
+        return createAutoPipelineProxy(redis, "functions");
+      }
+
+      // Root-level: some commands should bypass auto pipelining
+      if (namespace === "root") {
+        const commandInRedisButNotPipeline =
+          command in redis && !(command in redis.autoPipelineExecutor.pipeline);
+        const isCommandExcluded = EXCLUDE_COMMANDS.has(command as keyof Redis);
+
+        if (commandInRedisButNotPipeline || isCommandExcluded) {
+          return redis[command as redisOnly];
+        }
+      }
+
+      const pipeline = redis.autoPipelineExecutor.pipeline;
+      const targetFunction =
+        namespace === "json"
+          ? pipeline.json[command as keyof typeof pipeline.json]
+          : namespace === "functions"
+            ? pipeline.functions[command as keyof typeof pipeline.functions]
+            : pipeline[command as keyof Pipeline];
+
+      const isFunction = typeof targetFunction === "function";
+      if (isFunction) {
+        return (...args: CommandArgs<typeof Command>) => {
+          const commandMode = READ_COMMANDS.has(command as string) ? "read" : "write";
+          return redis.autoPipelineExecutor.withAutoPipeline(commandMode, (pipeline) => {
+            const targetFunction =
+              namespace === "json"
+                ? pipeline.json[command as keyof typeof pipeline.json]
+                : namespace === "functions"
+                  ? pipeline.functions[command as keyof typeof pipeline.functions]
+                  : pipeline[command as keyof Pipeline];
+
+            (targetFunction as any)(...args);
+          });
+        };
+      }
+
+      return targetFunction;
+    },
+  }) as Redis;
+}
+
+type CommandMode = "read" | "write";
+
+class AutoPipelineExecutor {
+  private pipelinePromises = new WeakMap<Pipeline, Promise<unknown[]>>();
+  private activeReadPipeline: Pipeline | null = null;
+  private activeWritePipeline: Pipeline | null = null;
+  private readIndex = 0;
+  private writeIndex = 0;
+  private redis: Redis;
+  pipeline: Pipeline; // only to make sure that proxy can work
+  pipelineCounter = 0; // to keep track of how many times a pipeline was executed
+
+  constructor(redis: Redis) {
+    this.redis = redis;
+    this.pipeline = redis.pipeline();
+  }
+
+  async withAutoPipeline<T>(
+    commandMode: CommandMode,
+    executeWithPipeline: (pipeline: Pipeline) => unknown
+  ): Promise<T> {
+    const isRead = commandMode === "read";
+    const activePipeline = isRead ? this.activeReadPipeline : this.activeWritePipeline;
+    const pipeline = activePipeline ?? this.redis.pipeline();
+
+    if (!activePipeline) {
+      if (isRead) {
+        this.activeReadPipeline = pipeline;
+        this.readIndex = 0;
+      } else {
+        this.activeWritePipeline = pipeline;
+        this.writeIndex = 0;
+      }
+    }
+
+    const index = isRead ? this.readIndex++ : this.writeIndex++;
+    executeWithPipeline(pipeline);
+
+    // If pipeline reached max size, close it so next command starts a new pipeline
+    if (isRead && this.readIndex >= MAX_PIPELINE_SIZE) {
+      this.activeReadPipeline = null;
+    } else if (!isRead && this.writeIndex >= MAX_PIPELINE_SIZE) {
+      this.activeWritePipeline = null;
+    }
+
+    const pipelineDone = this.deferExecution().then(() => {
+      if (!this.pipelinePromises.has(pipeline)) {
+        const pipelinePromise = pipeline.exec({ keepErrors: true });
+        this.pipelineCounter += 1;
+
+        this.pipelinePromises.set(pipeline, pipelinePromise);
+        if (this.activeReadPipeline === pipeline) {
+          this.activeReadPipeline = null;
+        }
+        if (this.activeWritePipeline === pipeline) {
+          this.activeWritePipeline = null;
+        }
+      }
+
+      return this.pipelinePromises.get(pipeline)!;
+    });
+
+    const results = (await pipelineDone) as UpstashResponse<T>[];
+    const commandResult = results[index];
+    if (commandResult.error) {
+      throw new UpstashError(`Command failed: ${commandResult.error}`);
+    }
+    return commandResult.result as T;
+  }
+
+  private async deferExecution() {
+    await Promise.resolve();
+    await Promise.resolve();
+  }
+}

package/src/pkg/commands/append.ts

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

package/src/pkg/commands/arcount.ts

@@ -0,0 +1,14 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Returns the number of occupied slots in an array. A missing key counts as `0`.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arcount
+ * @see node_modules/@upstash/redis/docs/commands/array/arcount.mdx
+ */
+export class ArCountCommand extends Command<number, number> {
+  constructor(cmd: [key: string], opts?: CommandOptions<number, number>) {
+    super(["ARCOUNT", ...cmd], opts);
+  }
+}

package/src/pkg/commands/ardel.ts

@@ -0,0 +1,19 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Empties one or more array slots. Later values are not shifted.
+ *
+ * Returns the number of slots that held a value.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/ardel
+ * @see node_modules/@upstash/redis/docs/commands/array/ardel.mdx
+ */
+export class ArDelCommand extends Command<number, number> {
+  constructor(
+    cmd: [key: string, ...indexes: (number | string)[]],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["ARDEL", ...cmd], opts);
+  }
+}

package/src/pkg/commands/ardelrange.ts

@@ -0,0 +1,19 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Empties every occupied slot inside one or more inclusive `[start, end]` ranges.
+ *
+ * Returns the total number of values removed across all ranges.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/ardelrange
+ * @see node_modules/@upstash/redis/docs/commands/array/ardelrange.mdx
+ */
+export class ArDelRangeCommand extends Command<number, number> {
+  constructor(
+    [key, ...ranges]: [key: string, ...ranges: [start: number | string, end: number | string][]],
+    opts?: CommandOptions<number, number>
+  ) {
+    super(["ARDELRANGE", key, ...ranges.flat()], opts);
+  }
+}

package/src/pkg/commands/arget.ts

@@ -0,0 +1,17 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Returns the value stored at `index`, or `null` if the slot is empty or the key does not exist.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arget
+ * @see node_modules/@upstash/redis/docs/commands/array/arget.mdx
+ */
+export class ArGetCommand<TData = string> extends Command<unknown | null, TData | null> {
+  constructor(
+    cmd: [key: string, index: number | string],
+    opts?: CommandOptions<unknown | null, TData | null>
+  ) {
+    super(["ARGET", ...cmd], opts);
+  }
+}

package/src/pkg/commands/argetrange.ts

@@ -0,0 +1,20 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+/**
+ * Returns every slot in the inclusive range `[start, end]`, with `null` for empty slots.
+ *
+ * When `start` is greater than `end`, the values are returned from the higher index down.
+ * Ranges wider than 1,000,000 indexes are rejected by the server.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/argetrange
+ * @see node_modules/@upstash/redis/docs/commands/array/argetrange.mdx
+ */
+export class ArGetRangeCommand<TData = string> extends Command<unknown[], (TData | null)[]> {
+  constructor(
+    cmd: [key: string, start: number | string, end: number | string],
+    opts?: CommandOptions<unknown[], (TData | null)[]>
+  ) {
+    super(["ARGETRANGE", ...cmd], opts);
+  }
+}

package/src/pkg/commands/argrep.ts

@@ -0,0 +1,109 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+import { parseResponse } from "../util";
+
+/**
+ * A single `ARGREP` predicate:
+ * - `exact`: the whole value equals the pattern
+ * - `match`: the value contains the pattern as a substring
+ * - `glob`: the value matches a glob pattern (`*` and `?`)
+ * - `re`: the value matches a regular expression
+ */
+export type ArGrepPredicate =
+  | { exact: string }
+  | { match: string }
+  | { glob: string }
+  | { re: string };
+
+export type ArGrepOptions = {
+  /**
+   * One or more predicates (at most 250).
+   */
+  predicates: ArGrepPredicate[];
+  /**
+   * How to combine several predicates. `OR` (the default) matches a slot when any predicate
+   * matches, `AND` requires all of them.
+   */
+  combine?: "AND" | "OR" | "and" | "or";
+  /**
+   * Compare case-insensitively.
+   */
+  noCase?: boolean;
+  /**
+   * Return `[index, value]` pairs instead of bare indexes.
+   */
+  withValues?: boolean;
+  /**
+   * Maximum number of matches to return.
+   */
+  limit?: number;
+};
+
+/**
+ * Matching indexes, or `[index, value]` pairs when `withValues` is `true`. Indexes are returned as
+ * strings; see `arlen`.
+ */
+export type ArGrepResult<TData, TOpts extends ArGrepOptions> = TOpts extends { withValues: true }
+  ? [string, TData][]
+  : TOpts extends { withValues: false }
+    ? string[]
+    : "withValues" extends keyof TOpts
+      ? string[] | [string, TData][]
+      : string[];
+
+/**
+ * Returns the indexes in `[start, end]` whose value matches the given predicates, or
+ * `[index, value]` pairs with `withValues`. `start` and `end` accept `"-"` and `"+"` for the lowest
+ * and highest possible index.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/argrep
+ * @see node_modules/@upstash/redis/docs/commands/array/argrep.mdx
+ */
+export class ArGrepCommand<
+  TData = string,
+  TOpts extends ArGrepOptions = ArGrepOptions,
+> extends Command<unknown[], ArGrepResult<TData, TOpts>> {
+  constructor(
+    [key, start, end, opts]: [
+      key: string,
+      start: number | string,
+      end: number | string,
+      opts: TOpts,
+    ],
+    cmdOpts?: CommandOptions<unknown[], ArGrepResult<TData, TOpts>>
+  ) {
+    const command: unknown[] = ["ARGREP", key, start, end];
+
+    for (const predicate of opts.predicates) {
+      if ("exact" in predicate) {
+        command.push("EXACT", predicate.exact);
+      } else if ("match" in predicate) {
+        command.push("MATCH", predicate.match);
+      } else if ("glob" in predicate) {
+        command.push("GLOB", predicate.glob);
+      } else {
+        command.push("RE", predicate.re);
+      }
+    }
+    if (opts.combine) {
+      command.push(opts.combine.toUpperCase());
+    }
+    if (opts.noCase) {
+      command.push("NOCASE");
+    }
+    if (opts.withValues) {
+      command.push("WITHVALUES");
+    }
+    if (opts.limit !== undefined) {
+      command.push("LIMIT", opts.limit);
+    }
+
+    super(command, {
+      deserialize: (result) =>
+        parseResponse<unknown[]>(result).map((item) =>
+          Array.isArray(item) ? [String(item[0]), item[1]] : String(item)
+        ) as ArGrepResult<TData, TOpts>,
+      ...cmdOpts,
+    });
+  }
+}

package/src/pkg/commands/arinfo.ts

@@ -0,0 +1,88 @@
+import type { CommandOptions } from "./command";
+import { Command } from "./command";
+
+export type ArInfoOptions = {
+  /**
+   * Also report per-slice statistics. This walks the whole array.
+   */
+  full?: boolean;
+};
+
+export type ArInfoResult = {
+  /** Highest occupied index plus one, as reported by `arlen`. A string, like every index. */
+  len: string;
+  /** Number of occupied slots, as reported by `arcount`. */
+  count: number;
+  /** Number of indexes covered by one slice. */
+  sliceSize: number;
+  /** Number of slices currently allocated. */
+  slices: number;
+  /** Number of entries in the slice directory. */
+  directorySize: number;
+  /** Number of entries in the top-level directory. */
+  superDirEntries: number;
+  /** Index the next `arinsert` would write to. A string, like every index. */
+  nextInsertIndex: string;
+  /** Slices stored in dense form. Only with `full`. */
+  denseSlices?: number;
+  /** Slices stored in sparse form. Only with `full`. */
+  sparseSlices?: number;
+  /** Average number of values in a dense slice. Only with `full`. */
+  avgDenseSize?: number;
+  /** Average fill ratio of a dense slice. Only with `full`. */
+  avgDenseFill?: number;
+  /** Average number of values in a sparse slice. Only with `full`. */
+  avgSparseSize?: number;
+};
+
+type RawArInfo = unknown[] | Record<string, unknown>;
+
+function toCamelCase(field: string): string {
+  return field.replaceAll(/-([a-z])/g, (_, char: string) => char.toUpperCase());
+}
+
+export function deserializeArInfoResponse(result: RawArInfo): ArInfoResult {
+  const entries: [unknown, unknown][] = Array.isArray(result)
+    ? Array.from({ length: Math.floor(result.length / 2) }, (_, i) => [
+        result[i * 2],
+        result[i * 2 + 1],
+      ])
+    : Object.entries(result);
+
+  // `len` and `next-insert-index` are indexes and stay strings; the rest are small counts.
+  const indexFields = new Set(["len", "nextInsertIndex"]);
+
+  const info: Record<string, unknown> = {};
+  for (const [field, value] of entries) {
+    const name = toCamelCase(String(field));
+    if (indexFields.has(name)) {
+      info[name] = String(value);
+      continue;
+    }
+    const numeric = typeof value === "number" ? value : Number(value);
+    info[name] = Number.isNaN(numeric) ? value : numeric;
+  }
+  return info as ArInfoResult;
+}
+
+/**
+ * Describes how an array is laid out in memory. Throws if the key does not exist.
+ *
+ * @see https://upstash.com/docs/redis/commands/array/arinfo
+ * @see node_modules/@upstash/redis/docs/commands/array/arinfo.mdx
+ */
+export class ArInfoCommand extends Command<RawArInfo, ArInfoResult> {
+  constructor(
+    [key, opts]: [key: string, opts?: ArInfoOptions],
+    cmdOpts?: CommandOptions<RawArInfo, ArInfoResult>
+  ) {
+    const command: unknown[] = ["ARINFO", key];
+    if (opts?.full) {
+      command.push("FULL");
+    }
+    super(command, {
+      deserialize: deserializeArInfoResponse,
+      ...cmdOpts,
+    });
+  }
+}