@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/stream/xautoclaim.mdx

@@ -0,0 +1,80 @@
+---
+title: XAUTOCLAIM
+description: Changes the ownership of pending messages from one consumer to another in a stream consumer group.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="group" type="string" required>
+  The consumer group name.
+</ParamField>
+
+<ParamField body="consumer" type="string" required>
+  The consumer name that will claim the messages.
+</ParamField>
+
+<ParamField body="minIdleTime" type="number" required>
+  The minimum idle time in milliseconds for messages to be claimed.
+</ParamField>
+
+<ParamField body="start" type="string" required>
+  The stream entry ID to start claiming from.
+</ParamField>
+
+
+<ParamField body="options" type="object">
+  <Expandable title="options">
+    <ParamField body="count" type="number">
+      The maximum number of messages to claim.
+    </ParamField>
+    <ParamField body="justid" type="boolean">
+      Return only the message IDs instead of the full message data.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="[string, Array<[string, string[]]>, string[]]">
+  Returns a tuple containing:
+  - Next start ID for pagination
+  - Array of claimed messages (ID and field-value pairs)
+  - Array of deleted message IDs
+</ResponseField>
+
+<RequestExample>
+```ts Basic autoclaim
+const result = await redis.xautoclaim(
+  "mystream",
+  "mygroup", 
+  "consumer1",
+  60000,
+  "0-0"
+);
+```
+
+```ts With count and justid
+const result = await redis.xautoclaim(
+  "mystream",
+  "mygroup",
+  "consumer1", 
+  60000,
+  "0-0",
+  { count: 5, justid: true }
+);
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+[
+  "1638360173533-1", // next start ID
+  [["1638360173533-0", ["field1", "value1", "field2", "value2"]]], // claimed messages
+  [] // deleted message IDs
+]
+```
+</ResponseExample>

package/docs/commands/stream/xclaim.mdx

@@ -0,0 +1,84 @@
+---
+title: XCLAIM
+description: Changes the ownership of pending messages from one consumer to another in a stream consumer group.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="group" type="string" required>
+  The consumer group name.
+</ParamField>
+
+<ParamField body="consumer" type="string" required>
+  The consumer name that will claim the messages.
+</ParamField>
+
+<ParamField body="minIdleTime" type="number" required>
+  The minimum idle time in milliseconds for messages to be claimed.
+</ParamField>
+
+<ParamField body="ids" type="string | string[]" required>
+  The ID(s) of the message(s) to claim. Can be a single ID or an array of IDs.
+</ParamField>
+
+<ParamField body="options">
+  <Expandable title="options">
+    <ParamField body="idle" type="number">
+      Set the idle time of the message.
+    </ParamField>
+    <ParamField body="time" type="number">
+      Set the idle time to a specific Unix time.
+    </ParamField>
+    <ParamField body="retryCount" type="number">
+      Set the retry counter to the specified value.
+    </ParamField>
+    <ParamField body="force" type="boolean">
+      Create the pending message entry even if certain IDs are not already pending.
+    </ParamField>
+    <ParamField body="justid" type="boolean">
+      Return only the message IDs instead of the full message data.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="Array<[string, string[]]> | string[]">
+  Returns an array of claimed messages. If `justid` option is used, returns only message IDs.
+</ResponseField>
+
+<RequestExample>
+```ts Basic claim
+const result = await redis.xclaim(
+  "mystream",
+  "mygroup",
+  "consumer1",
+  60000,
+  ["1638360173533-0", "1638360173533-1"]
+);
+```
+
+```ts With justid option
+const result = await redis.xclaim(
+  "mystream",
+  "mygroup", 
+  "consumer1",
+  60000,
+  ["1638360173533-0"],
+  { justid: true, force: true }
+);
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+[
+  ["1638360173533-0", ["field1", "value1", "field2", "value2"]],
+  ["1638360173533-1", ["field1", "value3", "field2", "value4"]]
+]
+```
+</ResponseExample>

package/docs/commands/stream/xdel.mdx

@@ -0,0 +1,34 @@
+---
+title: XDEL
+description: Removes the specified entries from a stream, and returns the number of entries deleted.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="ids" type="string | string[]" required>
+  The ID(s) of the message(s) to delete. Can be a single ID or an array of IDs.
+</ParamField>
+
+## Response
+
+<ResponseField type="number">
+  The number of entries actually deleted from the stream.
+</ResponseField>
+
+<RequestExample>
+```ts Single message
+const result = await redis.xdel("mystream", "1638360173533-0");
+```
+
+```ts Multiple messages
+const result = await redis.xdel("mystream", [
+  "1638360173533-0",
+  "1638360173533-1",
+  "1638360173533-2"
+]);
+```
+</RequestExample>

package/docs/commands/stream/xdelex.mdx

@@ -0,0 +1,119 @@
+---
+title: XDELEX
+description: Extended delete for streams with reference control.
+---
+
+The `XDELEX` command provides extended deletion capabilities for stream entries with additional control options. This is an enhanced version of XDEL with more advanced features for managing stream data.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="option" type="'KEEPREF' | 'keepref' | 'DELREF' | 'delref' | 'ACKED' | 'acked'">
+  Optional deletion behavior (case-insensitive). When provided, must come before the IDs:
+  - `KEEPREF`: Keep consumer group references
+  - `DELREF`: Delete consumer group references
+  - `ACKED`: Only acknowledge messages (don't delete)
+  
+  If not provided, entries are deleted by default.
+</ParamField>
+
+<ParamField body="ids" type="...string[]" required>
+  One or more stream entry IDs to delete. When an option is provided, IDs must come after the option.
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  An array of numbers indicating the result for each ID in the same order as provided.
+</ResponseField>
+
+<RequestExample>
+```ts Single Entry
+// Delete a single stream entry
+const result = await redis.xdelex("mystream", "1638360173533-0");
+console.log(result); // Array of results for each ID
+```
+
+```ts Multiple Entries
+// Delete multiple stream entries
+const result = await redis.xdelex(
+  "mystream", 
+  "1638360173533-0",
+  "1638360173533-1",
+  "1638360173533-2"
+);
+console.log(result); // Array of results for each ID
+```
+
+```ts With Option
+// Use KEEPREF option to keep consumer group references
+const result = await redis.xdelex(
+  "mystream",
+  "KEEPREF",
+  "1638360173533-0",
+  "1638360173533-1"
+);
+console.log(result); // Array of results for each ID
+
+// Use DELREF option to delete consumer group references
+const result2 = await redis.xdelex(
+  "mystream",
+  "DELREF",
+  "1638360173533-0"
+);
+console.log(result2); // Array of results for each ID
+
+// Use ACKED option to only acknowledge (don't delete)
+const result3 = await redis.xdelex(
+  "mystream",
+  "ACKED",
+  "1638360173533-0"
+);
+console.log(result3); // Array of results for each ID
+```
+
+```ts With Stream Processing
+// Add entries to stream
+await redis.xadd("events", "*", { type: "login", user: "john" });
+await redis.xadd("events", "*", { type: "logout", user: "john" });
+
+// Read entries
+const entries = await redis.xrange("events", "-", "+");
+console.log(entries);
+
+// Delete specific entries
+const deleted = await redis.xdelex(
+  "events",
+  entries[0][0], // First entry ID
+  entries[1][0]  // Second entry ID
+);
+console.log(`Results: ${deleted}`); // Array of results for each ID
+```
+
+```ts Cleanup Old Entries
+// Get entries older than a certain timestamp
+const oldEntries = await redis.xrange("logs", "-", "1638360000000-0");
+
+// Delete old entries
+if (oldEntries.length > 0) {
+  const ids = oldEntries.map(entry => entry[0]);
+  const deleted = await redis.xdelex("logs", ...ids);
+  console.log(`Results: ${deleted}`); // Array of results for each ID
+}
+```
+</RequestExample>
+
+## Use Cases
+
+- **Stream Cleanup**: Remove processed or expired stream entries
+- **Data Retention**: Implement custom retention policies
+- **Error Handling**: Delete corrupted or invalid stream entries
+- **Memory Management**: Clean up streams to free memory
+
+<Note>
+This command is available in Redis 8.2.0 and later. It provides extended functionality compared to the standard XDEL command.
+</Note>
+

package/docs/commands/stream/xgroup.mdx

@@ -0,0 +1,141 @@
+---
+title: XGROUP
+description: Manage consumer groups for Redis streams.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="subcommand" type="object" required>
+  The XGROUP subcommand and its parameters. Can be one of:
+  
+  <Expandable title="CREATE">
+    <ParamField body="type" type="'CREATE'" required>
+      Create a new consumer group.
+    </ParamField>
+    <ParamField body="group" type="string" required>
+      The consumer group name.
+    </ParamField>
+    <ParamField body="id" type="string | '$'" required>
+      The stream entry ID to start consuming from. Use '$' to start from the end.
+    </ParamField>
+    <ParamField body="options">
+      <Expandable title="options">
+        <ParamField body="MKSTREAM" type="boolean">
+          Create the stream if it doesn't exist.
+        </ParamField>
+        <ParamField body="ENTRIESREAD" type="number">
+          Set the number of entries read by the group.
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+
+  <Expandable title="CREATECONSUMER">
+    <ParamField body="type" type="'CREATECONSUMER'" required>
+      Create a new consumer in the group.
+    </ParamField>
+    <ParamField body="group" type="string" required>
+      The consumer group name.
+    </ParamField>
+    <ParamField body="consumer" type="string" required>
+      The consumer name to create.
+    </ParamField>
+  </Expandable>
+
+  <Expandable title="DELCONSUMER">
+    <ParamField body="type" type="'DELCONSUMER'" required>
+      Delete a consumer from the group.
+    </ParamField>
+    <ParamField body="group" type="string" required>
+      The consumer group name.
+    </ParamField>
+    <ParamField body="consumer" type="string" required>
+      The consumer name to delete.
+    </ParamField>
+  </Expandable>
+
+  <Expandable title="DESTROY">
+    <ParamField body="type" type="'DESTROY'" required>
+      Delete the entire consumer group.
+    </ParamField>
+    <ParamField body="group" type="string" required>
+      The consumer group name to destroy.
+    </ParamField>
+  </Expandable>
+
+  <Expandable title="SETID">
+    <ParamField body="type" type="'SETID'" required>
+      Set the last delivered ID for the group.
+    </ParamField>
+    <ParamField body="group" type="string" required>
+      The consumer group name.
+    </ParamField>
+    <ParamField body="id" type="string | '$'" required>
+      The stream entry ID to set as the last delivered ID.
+    </ParamField>
+    <ParamField body="options">
+      <Expandable title="options">
+        <ParamField body="ENTRIESREAD" type="number">
+          Set the number of entries read by the group.
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField>
+  The return type depends on the subcommand:
+  - CREATE: Returns "OK" string
+  - CREATECONSUMER: Returns 1 if created, 0 if already exists
+  - DELCONSUMER: Returns the number of pending messages the consumer had
+  - DESTROY: Returns 1 if destroyed, 0 if group didn't exist
+  - SETID: Returns "OK" string
+</ResponseField>
+
+<RequestExample>
+```ts Create group
+const result = await redis.xgroup("mystream", {
+  type: "CREATE",
+  group: "mygroup",
+  id: "$",
+  options: { MKSTREAM: true }
+});
+```
+
+```ts Create consumer
+const result = await redis.xgroup("mystream", {
+  type: "CREATECONSUMER",
+  group: "mygroup",
+  consumer: "consumer1"
+});
+```
+
+```ts Delete consumer
+const result = await redis.xgroup("mystream", {
+  type: "DELCONSUMER", 
+  group: "mygroup",
+  consumer: "consumer1"
+});
+```
+
+```ts Set group ID
+const result = await redis.xgroup("mystream", {
+  type: "SETID",
+  group: "mygroup", 
+  id: "0-0"
+});
+```
+
+```ts Destroy group
+const result = await redis.xgroup("mystream", {
+  type: "DESTROY",
+  group: "mygroup"
+});
+```
+</RequestExample>

package/docs/commands/stream/xinfo.mdx

@@ -0,0 +1,77 @@
+---
+title: XINFO
+description: Returns information about streams, consumer groups, and consumers.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="options" type="object" required>
+  The XINFO subcommand options. Can be one of:
+  <Expandable title="GROUPS">
+    <ParamField body="type" type="'GROUPS'" required>
+      List all consumer groups for the stream.
+    </ParamField>
+  </Expandable>
+
+  <Expandable title="CONSUMERS">
+    <ParamField body="type" type="'CONSUMERS'" required>
+      List all consumers in a consumer group.
+    </ParamField>
+    <ParamField body="group" type="string" required>
+      The consumer group name.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField>
+  The return type depends on the subcommand:
+  - GROUPS: Returns an array of consumer group information
+  - CONSUMERS: Returns an array of consumer information
+</ResponseField>
+
+<RequestExample>
+```ts List groups
+const result = await redis.xinfo("mystream", {
+  type: "GROUPS"
+});
+```
+
+```ts List consumers
+const result = await redis.xinfo("mystream", {
+  type: "CONSUMERS",
+  group: "mygroup"
+});
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+// GROUPS response
+[
+  {
+    name: "mygroup",
+    consumers: 2,
+    pending: 1,
+    "last-delivered-id": "1638360173533-2",
+    "entries-read": 3,
+    lag: 2
+  }
+]
+
+// CONSUMERS response
+[
+  {
+    name: "consumer1",
+    pending: 1,
+    idle: 15000,
+    "inactive": 15000
+  }
+]
+```
+</ResponseExample>

package/docs/commands/stream/xlen.mdx

@@ -0,0 +1,22 @@
+---
+title: XLEN
+description: Returns the number of entries inside a stream.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+## Response
+
+<ResponseField type="number">
+  The number of entries in the stream. Returns 0 if the stream does not exist.
+</ResponseField>
+
+<RequestExample>
+```ts Get stream length
+const result = await redis.xlen("mystream");
+```
+</RequestExample>

package/docs/commands/stream/xpending.mdx

@@ -0,0 +1,75 @@
+---
+title: XPENDING
+description: Returns information about pending messages in a stream consumer group.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="group" type="string" required>
+  The consumer group name.
+</ParamField>
+
+<ParamField body="start" type="string" required>
+  The minimum pending ID to return. Use "-" for the first available ID.
+</ParamField>
+
+<ParamField body="end" type="string" required>
+  The maximum pending ID to return. Use "+" for the last available ID.
+</ParamField>
+
+<ParamField body="count" type="number" required>
+  The maximum number of pending messages to return.
+</ParamField>
+
+<ParamField body="options">
+  <Expandable title="properties">
+    <ParamField body="idleTime" type="number">
+      Filter by minimum idle time in milliseconds.
+    </ParamField>
+    <ParamField body="consumer" type="string">
+      Filter results by a specific consumer.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField>
+  Returns an array of pending message details.
+</ResponseField>
+
+<RequestExample>
+```ts Summary
+const result = await redis.xpending("mystream", "mygroup", "-", "+", 10);
+```
+
+```ts With idle time filter
+const result = await redis.xpending("mystream", "mygroup", "-", "+", 5, {
+  idleTime: 10000
+});
+```
+
+```ts Specific consumer filter
+const result = await redis.xpending("mystream", "mygroup", "-", "+", 5, {
+  consumer: "consumer1"
+});
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+[
+  2, // total pending count
+  "1638360173533-0", // smallest pending ID
+  "1638360173533-1", // greatest pending ID
+  [
+    ["consumer1", "1"], // consumer and their pending count
+    ["consumer2", "1"]
+  ]
+]
+```
+</ResponseExample>

package/docs/commands/stream/xrange.mdx

@@ -0,0 +1,59 @@
+---
+title: XRANGE
+description: Returns stream entries matching a given range of IDs.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to of the stream.
+</ParamField>
+
+<ParamField body="start" type="string" required>
+  The stream entry ID to start from.
+</ParamField>
+
+<ParamField body="end" type="string" required>
+  The stream entry ID to end at.
+</ParamField>
+
+<ParamField body="count" type="number">
+  The maximum number of entries to return.
+</ParamField>
+
+## Response
+
+<ResponseField type="Record<streamId, Record<field, value>>">
+  An object of stream entries, keyed by their stream ID
+</ResponseField>
+
+<RequestExample>
+```ts All entries
+const result = await redis.xrange("mystream", "-", "+");
+```
+
+```ts Range with specific IDs
+const result = await redis.xrange("mystream", "1548149259438-0", "1548149259438-5");
+```
+
+```ts Limited count
+const result = await redis.xrange("mystream", "-", "+", 10);
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+{
+  "1548149259438-0": {
+    "field1": "value1",
+    "field2": "value2"
+  },
+  "1548149259438-1": {
+    "field1": "value3",
+    "field2": "value4"
+  }
+}
+```
+</ResponseExample>
+
+