@upstash/redis 1.40.0 → 1.41.0

package/cloudflare.mjs

@@ -3,7 +3,7 @@ import {
   Redis,
   VERSION,
   error_exports
-} from "./chunk-RLVWMRRX.mjs";
+} from "./chunk-CGMWROAN.mjs";
 
 // platforms/cloudflare.ts
 var Redis2 = class _Redis extends Redis {

package/docs/advanced.mdx

@@ -0,0 +1,83 @@
+---
+title: Redis TypeScript SDK Advanced Usage
+sidebarTitle: Advanced
+---
+
+## Disable automatic serialization
+
+Your data is (de)serialized as `json` by default. This works for most use cases
+but you can disable it if you want:
+
+```ts
+const redis = new Redis({
+  // ...
+  automaticDeserialization: false,
+});
+
+// or
+const redis = Redis.fromEnv({
+  automaticDeserialization: false,
+});
+```
+
+This probably breaks quite a few types, but it's a first step in that direction.
+Please report bugs and broken types
+[here](https://github.com/upstash/upstash-redis/issues/49).
+
+## Keep-Alive
+
+`@upstash/redis` optimizes performance by reusing connections wherever possible, reducing latency.
+This is achieved by keeping the client in memory instead of reinitializing it with each new function invocation.
+As a result, when a hot lambda function receives a new request, it uses the already initialized client, allowing for the reuse of existing connections to Upstash.
+
+<Tip>This functionality is enabled by default.</Tip>
+
+## Request Timeout
+
+You can configure the SDK so that it will throw an error if the request takes longer than a specified time.
+
+You can achieve this using the signal parameter like this:
+
+```ts
+const redis = new Redis({
+  url: "<UPSTASH_REDIS_REST_URL>",
+  token: "<UPSTASH_REDIS_REST_TOKEN>",
+  // set a timeout of 1 second
+  signal: () => AbortSignal.timeout(1000),
+});
+
+try {
+  await redis.get( ... )
+} catch (error) {
+  if (error.name === "TimeoutError") {
+    console.error("Request timed out");
+  } else {
+    console.error("An error occurred:", error);
+  }
+}
+```
+
+## Telemetry
+
+This library sends anonymous telemetry data to help us improve your experience.
+We collect the following:
+
+- SDK version
+- Platform (Deno, Cloudflare, Vercel)
+- Runtime version (node@18.x)
+
+You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
+to any truthy value.
+
+```sh
+UPSTASH_DISABLE_TELEMETRY=1
+```
+
+Alternatively, you can pass `enableTelemetry: false` when initializing the Redis client:
+
+```ts
+const redis = new Redis({
+  // ...,
+  enableTelemetry: false,
+});
+```

package/docs/commands/array/arcount.mdx

@@ -0,0 +1,28 @@
+---
+title: ARCOUNT
+description: Count the occupied slots in an array.
+---
+
+For sparse arrays, this differs from [ARLEN](./arlen), which returns the highest occupied index plus one.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+## Response
+
+<ResponseField type="number" required>
+  The number of slots containing values, or zero for a missing key.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 1000, "sample");
+console.log(await redis.arcount("readings")); // 1
+console.log(await redis.arlen("readings")); // "1001"
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arcount) for protocol details.

package/docs/commands/array/ardel.mdx

@@ -0,0 +1,30 @@
+---
+title: ARDEL
+description: Delete array values without shifting later indexes.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="indexes" type="...(number | string)[]" required>
+  One or more indexes, passed as separate arguments.
+</ParamField>
+
+## Response
+
+<ResponseField type="number" required>
+  The number of occupied slots removed. Empty slots and repeated indexes do not increase the count.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 0, "a", "b", "c");
+console.log(await redis.ardel("readings", 1, 1, 99)); // 1
+console.log(await redis.argetrange("readings", 0, 2)); // ["a", null, "c"]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/ardel) for protocol details.

package/docs/commands/array/ardelrange.mdx

@@ -0,0 +1,32 @@
+---
+title: ARDELRANGE
+description: Delete occupied slots in one or more inclusive ranges.
+---
+
+Deleting values leaves holes and does not shift later values.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="ranges" type="...[number | string, number | string][]" required>
+  One or more inclusive start-end pairs, passed as separate arguments.
+</ParamField>
+
+## Response
+
+<ResponseField type="number" required>
+  The number of values removed across the ranges. Overlapping ranges do not count a value twice.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 0, "a", "b", "c", "d", "e");
+console.log(await redis.ardelrange("readings", [0, 1], [4, 4])); // 3
+console.log(await redis.arcount("readings")); // 2
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/ardelrange) for protocol details.

package/docs/commands/array/arget.mdx

@@ -0,0 +1,33 @@
+---
+title: ARGET
+description: Read the value at an array index.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="index" type="number | string" required>
+  The zero-based index to access.
+</ParamField>
+
+## Response
+
+<ResponseField type="TData | null" required>
+  The stored value, or `null` (TypeScript) / `None` (Python) for an empty slot or missing key.
+</ResponseField>
+
+Values use the SDK's automatic deserialization. Use `TData` to describe stored JSON values; it defaults to `string`.
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 7, { temperature: 21.5 });
+const reading = await redis.arget<{ temperature: number }>("readings", 7);
+console.log(reading); // { temperature: 21.5 }
+console.log(await redis.arget("readings", 6)); // null
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arget) for protocol details.

package/docs/commands/array/argetrange.mdx

@@ -0,0 +1,38 @@
+---
+title: ARGETRANGE
+description: Read every slot in an inclusive array range.
+---
+
+A start greater than the end returns values in reverse index order. The server rejects ranges containing more than 1,000,000 indexes. Use [ARSCAN](./arscan) for sparse ranges.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="start" type="number | string" required>
+  The first index of the inclusive range.
+</ParamField>
+
+<ParamField body="end" type="number | string" required>
+  The last index of the inclusive range.
+</ParamField>
+
+## Response
+
+<ResponseField type="(TData | null)[]" required>
+  One value per index in the range, including `null` (TypeScript) / `None` (Python) for empty slots.
+</ResponseField>
+
+Values use the SDK's automatic deserialization. Use `TData` to describe stored JSON values; it defaults to `string`.
+
+<RequestExample>
+```ts Example
+await redis.armset("readings", { 0: "a", 2: "c" });
+console.log(await redis.argetrange("readings", 0, 3)); // ["a", null, "c", null]
+console.log(await redis.argetrange("readings", 2, 0)); // ["c", null, "a"]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/argetrange) for protocol details.

package/docs/commands/array/argrep.mdx

@@ -0,0 +1,69 @@
+---
+title: ARGREP
+description: Search array values using one or more predicates.
+---
+
+Provide at least one predicate and at most 250. Regular expressions are limited to 2048 bytes and do not support backreferences.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="start" type="number | string" required>
+  The first index to search. Use `"-"` for the lowest possible index.
+</ParamField>
+
+<ParamField body="end" type="number | string" required>
+  The last index to search. Use `"+"` for the highest possible index.
+</ParamField>
+
+<ParamField body="options" type="Object" required>
+  <ParamField body="predicates" type="ArGrepPredicate[]" required>
+    One to 250 predicates. Each is `{ exact: string }`, `{ match: string }`, `{ glob: string }`, or `{ re: string }` for equality, substring, glob, or regular-expression matching.
+  </ParamField>
+
+  <ParamField body="combine" type="'AND' | 'OR' | 'and' | 'or'">
+    How to combine predicates. Defaults to OR.
+  </ParamField>
+
+  <ParamField body="noCase" type="boolean">
+    Match case-insensitively. Defaults to false.
+  </ParamField>
+
+  <ParamField body="withValues" type="boolean">
+    Return index-value pairs instead of indexes. Defaults to false.
+  </ParamField>
+
+  <ParamField body="limit" type="number">
+    Maximum number of matches. If provided, it must be greater than zero.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="string[] | [string, TData][]" required>
+  Matching indexes, or index-value pairs when values are requested. TypeScript returns indexes as strings; Python returns integers. No matches returns an empty list.
+</ResponseField>
+
+Values use the SDK's automatic deserialization. Use `TData` to describe stored JSON values; it defaults to `string`.
+
+<RequestExample>
+```ts Example
+await redis.arset("logs", 0, "error: disk", "ok", "ERROR: network");
+console.log(await redis.argrep("logs", "-", "+", {
+  predicates: [{ match: "error" }],
+  noCase: true,
+})); // ["0", "2"]
+
+console.log(await redis.argrep("logs", "-", "+", {
+  predicates: [{ glob: "error:*" }, { match: "disk" }],
+  combine: "AND",
+  withValues: true,
+  limit: 10,
+})); // [["0", "error: disk"]]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/argrep) for protocol details.

package/docs/commands/array/arinfo.mdx

@@ -0,0 +1,49 @@
+---
+title: ARINFO
+description: Inspect array size, storage layout, and append position.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="options" type="Object">
+  <ParamField body="full" type="boolean">
+    Include per-slice statistics. Defaults to false. Enabling this walks the whole array.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="ArInfoResult" required>
+  An object with camelCase field names in TypeScript, or a dictionary with snake_case field names in Python. A missing key raises an error.
+</ResponseField>
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `len` | `string` | Highest occupied index plus one. |
+| `count` | `number` | Number of occupied slots. |
+| `sliceSize` | `number` | Indexes covered by one slice. |
+| `slices` | `number` | Allocated slices. |
+| `directorySize` | `number` | Slice directory entries. |
+| `superDirEntries` | `number` | Top-level directory entries. |
+| `nextInsertIndex` | `string` | Next append position. |
+| `denseSlices` | `number` | Dense slices. Only with full statistics. |
+| `sparseSlices` | `number` | Sparse slices. Only with full statistics. |
+| `avgDenseSize` | `number` | Average values per dense slice. Only with full statistics. |
+| `avgDenseFill` | `number` | Average dense-slice fill ratio. Only with full statistics. |
+| `avgSparseSize` | `number` | Average values per sparse slice. Only with full statistics. |
+
+<RequestExample>
+```ts Example
+await redis.arinsert("events", "boot", "ready");
+const info = await redis.arinfo("events");
+console.log(info.len, info.count, info.nextInsertIndex); // "2", 2, "2"
+const fullInfo = await redis.arinfo("events", { full: true });
+console.log(fullInfo.denseSlices, fullInfo.sparseSlices);
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arinfo) for protocol details.

package/docs/commands/array/arinsert.mdx

@@ -0,0 +1,32 @@
+---
+title: ARINSERT
+description: Append values after the array append cursor.
+---
+
+On a new array, appends start at index zero. [ARSET](./arset) and [ARMSET](./armset) leave the cursor unchanged, so appending after positional writes can overwrite values. Use [ARSEEK](./arseek) to choose the next append index.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="values" type="...TData[]" required>
+  One or more values to write.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  The index where the last value was written, as a string in TypeScript or an integer in Python.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+console.log(await redis.arinsert("events", "boot", "ready")); // "1"
+console.log(await redis.arinsert("events", "running")); // "2"
+console.log(await redis.arnext("events")); // "3"
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arinsert) for protocol details.

package/docs/commands/array/arlastitems.mdx

@@ -0,0 +1,40 @@
+---
+title: ARLASTITEMS
+description: Read the most recently appended array values.
+---
+
+Reads walk backward from the append cursor and wrap at index zero. Positional writes do not move that cursor.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="count" type="number" required>
+  The maximum number of values to return. Must be nonnegative and is capped at the number of stored values.
+</ParamField>
+
+<ParamField body="options" type="Object">
+  <ParamField body="rev" type="boolean">
+    Return newest values first. Defaults to false.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="(TData | null)[]" required>
+  Values in oldest-first order, or newest-first when `rev` is enabled. Empty slots are returned as `null` (TypeScript) / `None` (Python). A missing key returns an empty list.
+</ResponseField>
+
+Values use the SDK's automatic deserialization. Use `TData` to describe stored JSON values; it defaults to `string`.
+
+<RequestExample>
+```ts Example
+await redis.arring("recent", 3, "a", "b", "c", "d");
+console.log(await redis.arlastitems("recent", 3)); // ["b", "c", "d"]
+console.log(await redis.arlastitems("recent", 3, { rev: true })); // ["d", "c", "b"]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arlastitems) for protocol details.

package/docs/commands/array/arlen.mdx

@@ -0,0 +1,28 @@
+---
+title: ARLEN
+description: Get the highest occupied array index plus one.
+---
+
+Use [ARCOUNT](./arcount) to count stored values.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  The highest occupied index plus one. A missing key returns `"0"` in TypeScript or `0` in Python. TypeScript returns a string even for small lengths.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 1000, "sample");
+console.log(await redis.arlen("readings")); // "1001"
+console.log(await redis.arcount("readings")); // 1
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arlen) for protocol details.

package/docs/commands/array/armget.mdx

@@ -0,0 +1,31 @@
+---
+title: ARMGET
+description: Read several array slots in request order.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="indexes" type="...(number | string)[]" required>
+  One or more indexes, passed as separate arguments.
+</ParamField>
+
+## Response
+
+<ResponseField type="(TData | null)[]" required>
+  One value per requested index, with `null` (TypeScript) / `None` (Python) for empty slots or missing keys.
+</ResponseField>
+
+Values use the SDK's automatic deserialization. Use `TData` to describe stored JSON values; it defaults to `string`.
+
+<RequestExample>
+```ts Example
+await redis.armset("readings", { 0: "a", 10: "b" });
+console.log(await redis.armget("readings", 10, 5, 0)); // ["b", null, "a"]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/armget) for protocol details.

package/docs/commands/array/armset.mdx

@@ -0,0 +1,31 @@
+---
+title: ARMSET
+description: Write values at several array indexes.
+---
+
+These writes leave the append cursor unchanged.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="values" type="Record<number | string, TData> | [number | string, TData][]" required>
+  A mapping of indexes to values, or an iterable of index-value pairs. Provide at least one pair.
+</ParamField>
+
+## Response
+
+<ResponseField type="number" required>
+  The number of previously empty slots that were filled.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+console.log(await redis.armset("readings", { 0: "a", 10: "b" })); // 2
+console.log(await redis.armset("readings", [[10, "B"], [20, "c"]])); // 1
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/armset) for protocol details.

package/docs/commands/array/arnext.mdx

@@ -0,0 +1,25 @@
+---
+title: ARNEXT
+description: Read the next append index without moving the cursor.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+## Response
+
+<ResponseField type="string | null" required>
+  The next append index. A missing key or an array without appends returns `"0"` in TypeScript or `0` in Python. Returns `null` / `None` when the cursor has reached the highest supported index.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arinsert("events", "boot", "ready");
+console.log(await redis.arnext("events")); // "2"
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arnext) for protocol details.

package/docs/commands/array/arop.mdx

@@ -0,0 +1,44 @@
+---
+title: AROP
+description: Aggregate values in an inclusive array range.
+---
+
+`SUM`, `MIN`, and `MAX` aggregate numeric values. `AND`, `OR`, and `XOR` fold values as 64-bit integers, truncating fractions. These operations skip non-numeric values. `USED` counts occupied slots. `MATCH` counts values equal to the supplied value.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="start" type="number | string" required>
+  The first index of the inclusive range.
+</ParamField>
+
+<ParamField body="end" type="number | string" required>
+  The last index of the inclusive range.
+</ParamField>
+
+<ParamField body="operation" type="ArOpOperation<TData>" required>
+  The reduction to apply. See the operations below.
+</ParamField>
+
+Pass `"SUM"`, `"MIN"`, `"MAX"`, `"AND"`, `"OR"`, `"XOR"`, or `"USED"` (lowercase is also accepted). For equality matching, pass `{ match: value }` as the operation.
+
+## Response
+
+<ResponseField type="number | null" required>
+  The numeric aggregate, or `null` (TypeScript) / `None` (Python) if no values can be used. `USED` and `MATCH` return zero for an empty range.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 0, 1, 2, 3);
+console.log(await redis.arop("readings", 0, 2, "SUM")); // 6
+
+await redis.arset("statuses", 0, "ok", "error", "error");
+console.log(await redis.arop("statuses", 0, 2, { match: "error" })); // 2
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arop) for protocol details.

package/docs/commands/array/arring.mdx

@@ -0,0 +1,36 @@
+---
+title: ARRING
+description: Append values to a fixed-size ring buffer.
+---
+
+Writes wrap to index zero when the ring is full and overwrite the oldest values. Calling this command with a different size reshapes the ring.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="size" type="number" required>
+  The number of slots in the ring. Must be greater than zero.
+</ParamField>
+
+<ParamField body="values" type="...TData[]" required>
+  One or more values to write.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  The index where the last value was written, as a string in TypeScript or an integer in Python.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+console.log(await redis.arring("recent", 3, "a", "b", "c")); // "2"
+console.log(await redis.arring("recent", 3, "d")); // "0"
+console.log(await redis.arlastitems("recent", 3)); // ["b", "c", "d"]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arring) for protocol details.