@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/set/smove.mdx

@@ -0,0 +1,34 @@
+---
+title: SMOVE
+description: Move a member from one set to another
+---
+
+## Arguments
+
+<ParamField body="source" type="string" required>
+  The key of the set to move the member from.
+</ParamField>
+<ParamField body="destination" type="string" required>
+  The key of the set to move the member to.
+</ParamField>
+
+<ParamField body="member" type="TMember">
+  The members to move
+</ParamField>
+
+## Response
+
+<ResponseField type="0 | 1" required>
+  `1` if the member was moved, `0` if not.
+</ResponseField>
+
+<RequestExample>
+```ts Example 
+await redis.sadd("original", "a", "b", "c"); 
+const moved =  await redis.smove("original", "destination", "a");
+// moved:       1
+// original:    ["b", "c"]
+// destination: ["a"]
+```
+
+</RequestExample>

package/docs/commands/set/spop.mdx

@@ -0,0 +1,36 @@
+---
+title: SPOP
+description: Removes and returns one or more random members from a set.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the set.
+</ParamField>
+
+<ParamField body="count" type="number" default={1}>
+  How many members to remove and return.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="TMember | TMember[]" required>
+  The popped member.
+  If `count` is specified, an array of members is returned.
+</ResponseField>
+
+<RequestExample>
+```ts Example 
+await redis.sadd("set", "a", "b", "c"); 
+const popped = await redis.spop("set");
+console.log(popped); // "a"
+```
+```ts With Count 
+await redis.sadd("set", "a", "b", "c"); 
+const popped = await redis.spop("set", 2);
+console.log(popped); // ["a", "b"]
+```
+
+</RequestExample>

package/docs/commands/set/srandmember.mdx

@@ -0,0 +1,36 @@
+---
+title: SRANDMEMBER
+description: Returns one or more random members from a set.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the set.
+</ParamField>
+
+<ParamField body="count" type="number" default={1}>
+  How many members to return.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="TMember | TMember[]" required>
+  The random member.
+  If `count` is specified, an array of members is returned.
+</ResponseField>
+
+<RequestExample>
+```ts Example 
+await redis.sadd("set", "a", "b", "c"); 
+const member = await redis.srandmember("set");
+console.log(member); // "a"
+```
+```ts With Count 
+await redis.sadd("set", "a", "b", "c"); 
+const members = await redis.srandmember("set", 2);
+console.log(members); // ["a", "b"]
+```
+
+</RequestExample>

package/docs/commands/set/srem.mdx

@@ -0,0 +1,29 @@
+---
+title: SREM
+description: Remove one or more members from a set
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the set to remove the member from.
+</ParamField>
+
+<ParamField body="members" type="...TMember[]">
+  One or more members to remove from the set.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+ How many members were removed
+</ResponseField>
+
+<RequestExample>
+```ts Example 
+await redis.sadd("set", "a", "b", "c"); 
+const removed = await redis.srem("set", "a", "b", "d");
+console.log(removed); // 2
+```
+
+</RequestExample>

package/docs/commands/set/sscan.mdx

@@ -0,0 +1,39 @@
+---
+title: SSCAN
+description: Scan a set
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the set.
+</ParamField>
+
+<ParamField body="cursor" type="number">
+  The cursor, use `0` in the beginning and then use the returned cursor for subsequent calls.
+</ParamField>
+
+<ParamField body="options" type="Object">
+  <ParamField body="match" type="string">
+    Glob-style pattern to filter by members.
+  </ParamField>
+  <ParamField body="count" type="number">
+    Number of members to return per call.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="[number, TMember[]]" required>
+  The new cursor and the members.
+  If the new cursor is `0` the iteration is complete.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.sadd("key", "a", "ab","b", "c");
+const [newCursor, fields] = await redis.sscan("key", 0, { match: "a*"});
+console.log(newCursor); // likely `0` since this is a very small set
+console.log(fields); // ["a", "ab"]
+```
+</RequestExample>

package/docs/commands/set/sunion.mdx

@@ -0,0 +1,27 @@
+---
+title: SUNION
+description: Return the union between sets
+---
+
+## Arguments
+
+<ParamField body="keys" type="...string[]" required>
+  The keys of the sets to perform the union operation on.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="TValue[]" required>
+  The members of the resulting set.
+</ResponseField>
+
+<RequestExample>
+```ts Example 
+await redis.sadd("set1", "a", "b", "c"); 
+await redis.sadd("set2", "c", "d", "e"); 
+const union =  await redis.sunion("set1", "set2");
+console.log(union); // ["a", "b", "c", "d", "e"]
+```
+
+</RequestExample>

package/docs/commands/set/sunionstore.mdx

@@ -0,0 +1,33 @@
+---
+title: SUNIONSTORE
+description: Return the union between sets and store the resulting set in a key
+---
+
+## Arguments
+
+
+
+<ParamField body="destination" type="string" required>
+  The key of the set to store the resulting set in.
+</ParamField>
+
+
+<ParamField body="keys" type="...string[]" required>
+  The keys of the sets to perform the union operation on.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="TValue[]" required>
+  The members of the resulting set.
+</ResponseField>
+
+<RequestExample>
+```ts Example 
+await redis.sadd("set1", "a", "b", "c"); 
+await redis.sadd("set2", "c", "d", "e"); 
+await redis.sunionstore("destination", "set1", "set2");
+```
+
+</RequestExample>

package/docs/commands/stream/xack.mdx

@@ -0,0 +1,37 @@
+---
+title: XACK
+description: Removes one or multiple messages from the pending entries list of 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="id" type="string | string[]" required>
+  The ID(s) of the message(s) to acknowledge. Can be a single ID or an array of IDs.
+</ParamField>
+
+## Response
+
+<ResponseField type="number">
+  The number of messages successfully acknowledged.
+</ResponseField>
+
+<RequestExample>
+```ts Single message
+const result = await redis.xack("mystream", "mygroup", "1638360173533-0");
+```
+
+```ts Multiple messages
+const result = await redis.xack("mystream", "mygroup", [
+  "1638360173533-0",
+  "1638360173533-1"
+]);
+```
+</RequestExample>

package/docs/commands/stream/xackdel.mdx

@@ -0,0 +1,211 @@
+---
+title: XACKDEL
+description: Acknowledge and delete stream entries atomically.
+---
+
+The `XACKDEL` command acknowledges and deletes stream entries atomically in a single operation. This is useful for consumer groups where you want to acknowledge message processing and remove the entries from the stream simultaneously.
+
+## 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="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 acknowledged and deleted by default.
+</ParamField>
+
+<ParamField body="ids" type="...string[]" required>
+  One or more stream entry IDs to acknowledge and delete. When an option is provided, IDs must come after the option.
+</ParamField>
+
+## Response
+
+<ResponseField type="any[]" required>
+  An array indicating the result for each ID in the same order as provided.
+</ResponseField>
+
+<RequestExample>
+```ts Single Entry
+// Acknowledge and delete a single entry
+const result = await redis.xackdel("mystream", "mygroup", "1638360173533-0");
+console.log(result); // Array of results for each ID
+```
+
+```ts Multiple Entries
+// Acknowledge and delete multiple entries
+const result = await redis.xackdel(
+  "mystream", 
+  "mygroup",
+  "1638360173533-0",
+  "1638360173533-1",
+  "1638360173533-2"
+);
+console.log(result); // Array of results for each ID
+```
+
+```ts With KEEPREF Option
+// Keep consumer group references when deleting entries
+// Useful when you want to delete entries but maintain group tracking
+const result = await redis.xackdel(
+  "mystream",
+  "mygroup",
+  "KEEPREF",
+  "1638360173533-0",
+  "1638360173533-1",
+);
+console.log(result); // Array of results for each ID
+```
+
+```ts With DELREF Option
+// Delete consumer group references along with entries
+// Useful for complete cleanup of processed messages
+const result = await redis.xackdel(
+  "mystream",
+  "mygroup",
+  "DELREF",
+  "1638360173533-0",
+  "1638360173533-1",
+);
+console.log(result); // Array of results for each ID
+```
+
+```ts With ACKED Option
+// Only acknowledge messages without deleting them
+// Useful when you want to mark as processed but keep for audit/debugging
+const result = await redis.xackdel(
+  "mystream",
+  "mygroup",
+  "ACKED",
+  "1638360173533-0",
+);
+console.log(result); // Array of results for each ID
+// Entry remains in stream but is acknowledged
+```
+
+```ts Consumer Group Processing
+// Create a consumer group
+await redis.xgroup("CREATE", "orders", "processors", "0", "MKSTREAM");
+
+// Add some orders to the stream
+await redis.xadd("orders", "*", { order_id: "123", status: "pending" });
+await redis.xadd("orders", "*", { order_id: "124", status: "pending" });
+
+// Read messages as a consumer
+const messages = await redis.xreadgroup(
+  "GROUP", "processors", "consumer1",
+  "COUNT", 2,
+  "STREAMS", "orders", ">"
+);
+
+// Process messages and acknowledge + delete them
+for (const [stream, entries] of messages) {
+  for (const [id, fields] of entries) {
+    // Process the order...
+    console.log(`Processing order ${fields.order_id}`);
+    
+    // Acknowledge and delete the entry (default behavior)
+    await redis.xackdel("orders", "processors", id);
+    
+    // Or use DELREF for complete cleanup
+    // await redis.xackdel("orders", "processors", "DELREF", id);
+  }
+}
+```
+
+```ts Batch Processing
+// Read pending messages
+const pending = await redis.xreadgroup(
+  "GROUP", "tasks", "worker1",
+  "COUNT", 10,
+  "STREAMS", "task-queue", ">"
+);
+
+if (pending && pending.length > 0) {
+  const [stream, entries] = pending[0];
+  const processedIds: string[] = [];
+  
+  // Process each task
+  for (const [id, fields] of entries) {
+    try {
+      // Process task...
+      console.log(`Processing task ${id}`);
+      processedIds.push(id);
+    } catch (error) {
+      console.error(`Failed to process ${id}:`, error);
+    }
+  }
+  
+  // Acknowledge and delete all successfully processed tasks
+  // Using DELREF to completely remove references
+  if (processedIds.length > 0) {
+    const result = await redis.xackdel("task-queue", "tasks", "DELREF", ...processedIds);
+    console.log(`Results: ${result}`); // Array of results for each ID
+  }
+}
+```
+
+```ts Audit Mode with ACKED
+// Process messages but keep them for audit/debugging purposes
+const messages = await redis.xreadgroup(
+  "GROUP", "audit", "auditor1",
+  "COUNT", 5,
+  "STREAMS", "events", ">"
+);
+
+for (const [stream, entries] of messages) {
+  const entryIds = entries.map(([id]) => id);
+  
+  // Process and acknowledge but don't delete
+  for (const [id, fields] of entries) {
+    // Audit the event...
+    console.log(`Auditing event ${JSON.stringify(fields)}`);
+  }
+  
+  // Acknowledge without deleting (keep for audit trail)
+  const result = await redis.xackdel("events", "audit", "ACKED", ...entryIds);
+  console.log(`Acknowledged ${result.length} events (kept in stream)`);
+}
+```
+</RequestExample>
+
+## Use Cases
+
+- **Message Queue Cleanup**: Process messages and remove them from the stream in one operation
+- **Event Processing**: Acknowledge event handling and clean up the stream
+- **Task Queue Management**: Complete tasks and remove them atomically
+- **Memory Optimization**: Reduce stream memory usage by removing processed entries
+
+## Comparison with XACK + XDEL
+
+Traditional approach (two operations):
+```ts
+// Acknowledge the message
+await redis.xack("mystream", "mygroup", "123-0");
+// Then delete it
+await redis.xdel("mystream", "123-0");
+```
+
+With XACKDEL (single atomic operation):
+```ts
+// Acknowledge and delete in one operation (default)
+await redis.xackdel("mystream", "mygroup", "123-0");
+
+// With options for fine-grained control
+await redis.xackdel("mystream", "mygroup", "DELREF", "123-0"); // Complete cleanup
+await redis.xackdel("mystream", "mygroup", "ACKED", "123-0");  // Acknowledge only
+```
+
+<Note>
+This command is available in Redis 8.2.0 and later. It combines XACK and XDEL into a single atomic operation, which is more efficient and ensures consistency.
+</Note>
+

package/docs/commands/stream/xadd.mdx

@@ -0,0 +1,137 @@
+---
+title: XADD
+description: Appends one or more new entries to a stream.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to of the stream.
+</ParamField>
+
+<ParamField body="id" type="string | *" required>
+  The stream entry ID. Supports multiple formats:
+  - `*`: Fully automatic ID generation (both timestamp and sequence)
+  - `<ms>-<seq>`: Explicit ID (e.g., "1526919030474-55")
+  - `<ms>-*`: Auto-generate sequence number for the given millisecond timestamp (Redis 8+)
+</ParamField>
+
+<ParamField body="entries" type="Record<string, unknown>" required>
+  Key-value data to be appended to the stream.
+</ParamField>
+
+<ParamField body="options" type="object">
+  <Expandable title="properties">
+    <ParamField body="nomkStream" type="boolean">
+      Prevent creating the stream if it does not exist.
+    </ParamField>
+    
+    <ParamField body="trim" type="object">
+      Trim options for the stream.
+
+      <Expandable title="trim">
+        <ParamField body="type" type="'MAXLEN' | 'MINID'" required>
+          The trim strategy:
+          - `MAXLEN`: Trim based on the maximum number of entries
+          - `MINID`: Trim based on the minimum ID
+        </ParamField>
+
+        <ParamField body="threshold" type="number | string" required>
+          The threshold value for trimming:
+          - For `MAXLEN`: The maximum number of entries to keep (number)
+          - For `MINID`: The minimum ID to keep (string)
+        </ParamField>
+        
+        <ParamField body="comparison" type="'~' | '='" required>
+          The comparison operator:
+          - `~`: Approximate trimming (more efficient)
+          - `=`: Exact trimming
+        </ParamField>
+        
+        <ParamField body="limit" type="number">
+          Limit how many entries will be trimmed at most
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="string">The ID of the newly added entry.</ResponseField>
+
+<RequestExample>
+```ts Basic Example
+const result = await redis.xadd("mystream", "*", { name: "John Doe", age: 30 });
+```
+
+```ts With Custom ID
+const result = await redis.xadd("mystream", "1634567890123-0", { temperature: 25.5, humidity: 60 });
+```
+
+```ts Trimming with MAXLEN
+const result = await redis.xadd("mystream", "*", { event: "user_login", user_id: "12345" }, {
+  trim: {
+    type: "MAXLEN",
+    threshold: 1000,
+    comparison: "="
+  }
+});
+```
+
+```ts Prevent Stream Creation
+const result = await redis.xadd("existing_stream", "*", { data: "value" }, {
+  nomkStream: true
+});
+```
+
+```ts Trimming with MINID
+const result = await redis.xadd("mystream", "*", { action: "purchase", amount: 99.99 }, {
+  trim: {
+    type: "MINID",
+    threshold: "1634567890000-0",
+    comparison: "="
+  }
+});
+```
+
+```ts Auto Sequence Number (Redis 8+)
+// Specify millisecond timestamp, let Redis generate sequence number
+const ms = Date.now();
+const id1 = await redis.xadd("mystream", `${ms}-*`, { event: "login", user: "john" });
+console.log(id1); // e.g., "1769347235123-0"
+
+// Multiple entries with same ms but different sequence numbers
+const id2 = await redis.xadd("mystream", `${ms}-*`, { event: "logout", user: "john" });
+console.log(id2); // e.g., "1769347235123-1"
+```
+
+```ts Precise Timestamp Control
+// Use auto sequence for precise timestamp control
+const timestamp = 1634567890123;
+const result = await redis.xadd("events", `${timestamp}-*`, { 
+  type: "payment",
+  amount: 100.00,
+  currency: "USD"
+});
+// Redis generates the sequence number automatically
+```
+</RequestExample>
+
+## ID Format Details
+
+### Automatic ID (`*`)
+Fully automatic - Redis generates both the millisecond timestamp and sequence number.
+
+### Explicit ID (`<ms>-<seq>`)
+You provide both the millisecond timestamp and sequence number. Example: `"1526919030474-55"`
+
+### Auto Sequence (`<ms>-*`) - Redis 8+
+You provide the millisecond timestamp, Redis automatically generates the sequence number. This is useful when you need precise control over the timestamp but want Redis to handle sequence numbering.
+
+**Benefits of Auto Sequence:**
+- Precise timestamp control for time-sensitive data
+- Automatic sequence management prevents conflicts
+- Multiple entries can share the same millisecond with different sequences
+- Ideal for batch operations with consistent timestamps
+