@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/stream/xread.mdx

@@ -0,0 +1,65 @@
+---
+title: XREAD
+description: Reads data from one or multiple streams, starting from the specified IDs.
+---
+
+## Arguments
+
+<ParamField body="key" type="string | string[]" required>
+  The key(s) of the stream(s). Can be a single stream key or an array of stream keys.
+</ParamField>
+
+<ParamField body="id" type="string | string[]" required>
+  The stream entry ID(s) to start reading from. Must match the number of keys provided.
+  Use `$` to read only new messages added after the command is issued.
+</ParamField>
+
+<ParamField body="options">
+  <Expandable title="properties">
+    <ParamField body="count" type="number">
+      The maximum number of messages to return per stream.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="Array<[string, Array<[string, string[]]>]> | null">
+  Returns an array where each element represents a stream and contains:
+  - The stream key
+  - An array of messages (ID and field-value pairs)
+  
+  Returns null if no data is available.
+</ResponseField>
+
+<RequestExample>
+```ts Single stream
+const result = await redis.xread("mystream", "0-0");
+```
+
+```ts Multiple streams
+const result = await redis.xread(
+  ["stream1", "stream2"], 
+  ["0-0", "0-0"]
+);
+```
+
+```ts With count limit
+const result = await redis.xread("mystream", "0-0", { count: 2 });
+```
+
+```ts Only new messages
+const result = await redis.xread("mystream", `$`);
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+[
+  ["mystream", [
+    ["1638360173533-0", ["field1", "value1", "field2", "value2"]],
+    ["1638360173533-1", ["field1", "value3", "field2", "value4"]]
+  ]]
+]
+```
+</ResponseExample>

package/docs/commands/stream/xreadgroup.mdx

@@ -0,0 +1,87 @@
+---
+title: XREADGROUP
+description: Reads data from a stream as part of a consumer group.
+---
+
+## Arguments
+
+<ParamField body="group" type="string" required>
+  The consumer group name.
+</ParamField>
+
+<ParamField body="consumer" type="string" required>
+  The consumer name within the group.
+</ParamField>
+
+<ParamField body="key" type="string | string[]" required>
+  The stream key(s) to read from. Can be a single stream key or an array of stream keys for multiple streams.
+</ParamField>
+
+<ParamField body="ids" type="string | string[]" required>
+  The starting ID(s) to read from. Use ">" to read messages never delivered to any consumer in the group.
+  For multiple streams, provide an array of IDs corresponding to each stream.
+</ParamField>
+
+<ParamField body="options">
+  <Expandable title="properties">
+    <ParamField body="count" type="number">
+      The maximum number of messages to return per stream.
+    </ParamField>
+    <ParamField body="NOACK" type="boolean">
+      Don't add messages to the pending entries list (messages won't need acknowledgment).
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="Array<[string, Array<[string, string[]]>]> | null">
+  Returns an array where each element represents a stream and contains:
+  - The stream key
+  - An array of messages (ID and field-value pairs)
+  
+  Returns null if no data is available.
+</ResponseField>
+
+<RequestExample>
+```ts Read new messages
+const result = await redis.xreadgroup("mygroup", "consumer1", "mystream", ">");
+```
+
+```ts With count option
+const result = await redis.xreadgroup("mygroup", "consumer1", "mystream", ">", {
+  count: 5
+});
+```
+
+```ts With NOACK option
+const result = await redis.xreadgroup("mygroup", "consumer1", "mystream", ">", {
+  NOACK: true
+});
+```
+
+```ts Multiple streams
+const result = await redis.xreadgroup(
+  "mygroup", 
+  "consumer1", 
+  ["stream1", "stream2"], 
+  [">", ">"],
+  { count: 1 }
+);
+```
+
+```ts Read pending messages
+const result = await redis.xreadgroup("mygroup", "consumer1", "mystream", "0");
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+[
+  ["mystream", [
+    ["1638360173533-0", ["field1", "value1", "field2", "value2"]],
+    ["1638360173533-1", ["field1", "value3", "field2", "value4"]]
+  ]]
+]
+```
+</ResponseExample>

package/docs/commands/stream/xrevrange.mdx

@@ -0,0 +1,65 @@
+---
+title: XREVRANGE
+description: Returns stream entries matching a given range of IDs in reverse order.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="end" type="string" required>
+  The stream entry ID to end at (highest ID).
+</ParamField>
+
+<ParamField body="start" type="string" required>
+  The stream entry ID to start from (lowest ID).
+</ParamField>
+
+<ParamField body="count" type="number">
+  The maximum number of entries to return.
+</ParamField>
+
+## Response
+
+<ResponseField type="Record<string, Record<string, unknown>>">
+  An object of stream entries in reverse chronological order, keyed by their stream ID.
+</ResponseField>
+
+<RequestExample>
+```ts All entries (reverse order)
+const result = await redis.xrevrange("mystream", "+", "-");
+```
+
+```ts Limited count
+const result = await redis.xrevrange("mystream", "+", "-", 2);
+```
+
+```ts Specific range
+const result = await redis.xrevrange(
+  "mystream",
+  "1638360173533-3", 
+  "1638360173533-1"
+);
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+{
+  "1638360173533-4": {
+    "field1": "value5",
+    "field2": "value6"
+  },
+  "1638360173533-3": {
+    "field1": "value3", 
+    "field2": "value4"
+  },
+  "1638360173533-0": {
+    "field1": "value1",
+    "field2": "value2"
+  }
+}
+```
+</ResponseExample>

package/docs/commands/stream/xtrim.mdx

@@ -0,0 +1,75 @@
+---
+title: XTRIM
+description: Trims the stream by removing entries to keep it at a reasonable size.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the stream.
+</ParamField>
+
+<ParamField body="options" type="object" required>
+  <Expandable title="properties">
+    <ParamField body="strategy" type="'MAXLEN' | 'MINID'" required>
+      The trimming 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). Entries with IDs lower than this will be removed
+    </ParamField>
+
+    <ParamField body="exactness" type="'~' | '='">
+      Use `~` for approximate trimming (more efficient, default) or `=` for exact trimming.
+    </ParamField>
+
+    <ParamField body="limit" type="number">
+      Limit how many entries will be trimmed at most (only valid with approximate trimming `~`).
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="number">
+  The number of entries removed from the stream.
+</ResponseField>
+
+<RequestExample>
+```ts Approximate trim by max length
+const result = await redis.xtrim("mystream", {
+  strategy: "MAXLEN",
+  threshold: 100,
+  exactness: "~"
+});
+```
+
+```ts Exact trim by max length
+const result = await redis.xtrim("mystream", {
+  strategy: "MAXLEN", 
+  threshold: 50,
+  exactness: "="
+});
+```
+
+```ts Trim by minimum ID
+const result = await redis.xtrim("mystream", {
+  strategy: "MINID",
+  threshold: "1638360173533-0",
+  exactness: "="
+});
+```
+
+```ts Approximate trim with limit
+const result = await redis.xtrim("mystream", {
+  strategy: "MAXLEN",
+  threshold: 1000,
+  exactness: "~",
+  limit: 100
+});
+```
+</RequestExample>

package/docs/commands/string/append.mdx

@@ -0,0 +1,28 @@
+---
+title: APPEND
+description: Append a value to a string stored at key.
+---
+
+
+## Arguments
+
+<ParamField body="key"type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="value" required>
+  The value to append.
+</ParamField>
+
+## Response
+
+<ResponseField  type="integer" required>
+How many characters were added to the string.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.append(key, "Hello");
+// returns 5
+```
+</RequestExample>

package/docs/commands/string/decr.mdx

@@ -0,0 +1,27 @@
+---
+title: DECR
+description: Decrement the integer value of a key by one
+---
+
+If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+The key to decrement.
+</ParamField>
+
+
+## Response
+
+<ResponseField  type="integer" required>
+The value at the key after the decrementing.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key", 6);
+await redis.decr("key");
+// returns 5
+```
+</RequestExample>

package/docs/commands/string/decrby.mdx

@@ -0,0 +1,30 @@
+---
+title: DECRBY
+description: Decrement the integer value of a key by a given number.
+---
+
+If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
+
+## Arguments
+
+<ParamField body="key" type="string"required>
+The key to decrement.
+</ParamField>
+<ParamField body="decrementBy" type="integer" required>
+The amount to decrement by.
+</ParamField>
+
+
+## Response
+
+<ResponseField  type="integer" required>
+The value at the key after the decrementing.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key", 6);
+await redis.decrby("key", 4);
+// returns 2
+```
+</RequestExample>

package/docs/commands/string/get.mdx

@@ -0,0 +1,34 @@
+---
+title: GET
+description: Return the value of the specified key or `null` if the key doesn't exist.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+## Response
+
+<ResponseField  required>
+The response is the value stored at the key or `null` if the key doesn't exist.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+type MyType = {
+    a: number;
+    b: string;
+}
+const value = await redis.get<MyType>("key");
+if (!value) {
+    // key doesn't exist
+} else {
+    // value is of type MyType
+}
+```
+</RequestExample>

package/docs/commands/string/getdel.mdx

@@ -0,0 +1,29 @@
+---
+title: GETDEL
+description: Return the value of the specified key and delete the key.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+## Response
+
+<ResponseField  required>
+
+The response is the value stored at the key or `null` if the key doesn't exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+type MyType = {
+    a: number;
+    b: string;
+}
+await redis.getdel<MyType>("key");
+// returns {a: 1, b: "2"}
+```
+</RequestExample>

package/docs/commands/string/getrange.mdx

@@ -0,0 +1,34 @@
+---
+title: GETRANGE
+description: Return a substring of value at the specified key.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="start" type="integer" required>
+  The start index of the substring.
+</ParamField>
+
+<ParamField body="end" type="integer" required>
+  The end index of the substring.
+</ParamField>
+
+
+## Response
+
+<ResponseField  type="string" required>
+  The substring.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+const substring = await redis.getrange("key", 2, 4);
+```
+</RequestExample>

package/docs/commands/string/getset.mdx

@@ -0,0 +1,28 @@
+---
+title: GETSET
+description: Return the value of the specified key and replace it with a new value.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="newValue"  required>
+  The new value to store.
+</ParamField>
+
+## Response
+<ResponseField  required>
+
+The response is the value stored at the key or `null` if the key doesn't exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+
+const oldValue = await redis.getset("key", newValue);
+```
+</RequestExample>

package/docs/commands/string/incr.mdx

@@ -0,0 +1,27 @@
+---
+title: INCR
+description: Increment the integer value of a key by one
+---
+
+If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+The key to increment.
+</ParamField>
+
+
+## Response
+
+<ResponseField  type="integer" required>
+The value at the key after the incrementing.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key", 6);
+await redis.incr("key");
+// returns 7
+```
+</RequestExample>

package/docs/commands/string/incrby.mdx

@@ -0,0 +1,30 @@
+---
+title: INCRBY
+description: Increment the integer value of a key by a given number.
+---
+
+If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
+
+## Arguments
+
+<ParamField body="key" type="string"required>
+The key to decrement.
+</ParamField>
+<ParamField body="incrementBy" type="integer" required>
+The amount to increment by.
+</ParamField>
+
+
+## Response
+
+<ResponseField  type="integer" required>
+The value at the key after the incrementing.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key", 6);
+await redis.incrby("key", 4);
+// returns 10
+```
+</RequestExample>

package/docs/commands/string/incrbyfloat.mdx

@@ -0,0 +1,30 @@
+---
+title: INCRBYFLOAT
+description: Increment the float value of a key by a given number.
+---
+
+If a key does not exist, it is initialized as 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
+
+## Arguments
+
+<ParamField body="key" type="string"required>
+The key to decrement.
+</ParamField>
+<ParamField body="incrementBy" type="float" required>
+The amount to increment by.
+</ParamField>
+
+
+## Response
+
+<ResponseField  type="float" required>
+The value at the key after the incrementing.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key", 6);
+await redis.incrbyfloat("key", 4,5);
+// returns 10.5
+```
+</RequestExample>

package/docs/commands/string/mget.mdx

@@ -0,0 +1,31 @@
+---
+title: MGET
+description: Load multiple keys from Redis in one go.
+---
+
+For billing purposes, this counts as a single command.
+
+## Arguments 
+
+<ParamField body="keys" type="...string" required>
+  Multiple keys to load from Redis.
+</ParamField>
+
+## Response
+
+<ResponseField type="T[]" required>
+An array of values corresponding to the keys passed in. If a key doesn't exist, the value will be `null`.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+type MyType = {
+    a: number;
+    b: string;
+}
+const values = await redis.mget<MyType>("key1", "key2", "key3");
+// values.length -> 3
+```
+</RequestExample>

package/docs/commands/string/mset.mdx

@@ -0,0 +1,32 @@
+---
+title: MSET
+description: Set multiple keys in one go.
+---
+
+
+For billing purposes, this counts as a single command.
+
+
+## Arguments 
+
+<ParamField body="params" type="Record<string, TValue>" required>
+  An object where the keys are the keys to set, and the values are the values to set.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+"OK"
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+await redis.mset({
+    key1: 1,
+    key2: "hello",
+    key3: { a: 1, b: "hello" },
+});
+```
+</RequestExample>

package/docs/commands/string/msetnx.mdx

@@ -0,0 +1,29 @@
+---
+title: MSETNX
+description: Set multiple keys in one go unless they exist already.
+---
+
+
+For billing purposes, this counts as a single command.
+
+
+## Arguments 
+
+<ParamField  type="Record<string, TValue>" required>
+  An object where the keys are the keys to set, and the values are the values to set.
+</ParamField>
+
+## Response
+
+<ResponseField  required>
+  `True` if all keys were set, `False` if at least one key was not set.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+redis.msetnx({
+  "key1": "value1",
+  "key2": "value2"
+})
+```
+</RequestExample>