@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/array/arscan.mdx

@@ -0,0 +1,42 @@
+---
+title: ARSCAN
+description: Read occupied array slots with their indexes.
+---
+
+## 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="options" type="Object">
+  <ParamField body="limit" type="number">
+    Maximum number of occupied slots to return. If provided, it must be greater than zero.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="[string, TData][]" required>
+  Index-value pairs for occupied slots. Empty slots are skipped; a missing key returns an empty list. TypeScript returns indexes as strings; Python returns integers.
+</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", { 10: "a", 1000: "b" });
+console.log(await redis.arscan("readings", 0, 1000, { limit: 2 }));
+// [["10", "a"], ["1000", "b"]]
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arscan) for protocol details.

package/docs/commands/array/arseek.mdx

@@ -0,0 +1,34 @@
+---
+title: ARSEEK
+description: Choose the index where the next append will write.
+---
+
+Moves only the append cursor; existing values are unchanged. The key must already exist.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The array key.
+</ParamField>
+
+<ParamField body="index" type="number | string" required>
+  The index where the next ARINSERT should write.
+</ParamField>
+
+## Response
+
+<ResponseField type="0 | 1" required>
+  TypeScript returns `1` if the cursor was set and `0` if the key does not exist. Python returns `True` or `False`, respectively.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.arset("readings", 10, "existing");
+const nextIndex = await redis.arlen("readings");
+console.log(await redis.arseek("readings", nextIndex)); // 1
+console.log(await redis.arinsert("readings", "new")); // "11"
+console.log(await redis.arget("readings", 10)); // "existing"
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arseek) for protocol details.

package/docs/commands/array/arset.mdx

@@ -0,0 +1,35 @@
+---
+title: ARSET
+description: Write consecutive values starting at an array index.
+---
+
+Positional writes leave the append cursor unchanged. To append after positional writes, use [ARSEEK](./arseek) with the length returned by [ARLEN](./arlen).
+
+## 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>
+
+<ParamField body="values" type="...TData[]" required>
+  One or more values to write.
+</ParamField>
+
+## Response
+
+<ResponseField type="number" required>
+  The number of previously empty slots that were filled. Overwriting a value contributes zero.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+console.log(await redis.arset("readings", 0, 21.5, 21.7)); // 2
+console.log(await redis.arset("readings", 1, 22.1)); // 0
+```
+</RequestExample>
+
+See the [server command reference](/redis/commands/array/arset) for protocol details.

package/docs/commands/auth/echo.mdx

@@ -0,0 +1,24 @@
+---
+title: ECHO
+---
+
+Returns a message back to you. Useful for debugging the connection.
+
+## Arguments
+
+<ParamField body="message" type="string" required>
+  A message to send to the server.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  The same message you sent.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const response = await redis.echo("hello world");
+console.log(response); // "hello world"
+```
+</RequestExample>

package/docs/commands/auth/ping.mdx

@@ -0,0 +1,21 @@
+---
+title: PING
+description: Send a ping to the server and get a response if the server is alive.
+---
+
+## Arguments
+
+No arguments
+
+## Response
+
+<ResponseField type="string" required>
+  `PONG`
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const response = await redis.ping();
+console.log(response); // "PONG"
+```
+</RequestExample>

package/docs/commands/bitmap/bitcount.mdx

@@ -0,0 +1,39 @@
+---
+title: BITCOUNT
+description: Count the number of set bits.
+---
+
+The `BITCOUNT` command in Redis is used to count the number of set bits (bits with a value of 1) in a range of bytes within a key that is stored as a binary string. It is primarily used for bit-level operations on binary data stored in Redis.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="start" type="integer">
+  Specify the range of bytes within the binary string to count the set bits. If not provided, it counts set bits in the entire string.
+
+    Either specify both `start` and `end` or neither.
+
+</ParamField>
+
+<ParamField body="end" type="integer">
+Specify the range of bytes within the binary string to count the set bits. If not provided, it counts set bits in the entire string.
+
+ Either specify both `start` and `end` or neither.
+</ParamField>
+## Response
+
+<ResponseField type="integer" required>
+  The number of set bits in the specified range.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const bits = await redis.bitcount(key);
+```
+```ts With Range
+const bits = await redis.bitcount(key, 5, 10);
+```
+</RequestExample>

package/docs/commands/bitmap/bitop.mdx

@@ -0,0 +1,142 @@
+---
+title: BITOP
+description: Perform bitwise operations between strings.
+---
+
+The `BITOP` command in Redis is used to perform bitwise operations on multiple keys (or Redis strings) and store the result in a destination key. It supports standard logical operations (AND, OR, XOR, NOT) and advanced operations (DIFF, DIFF1, ANDOR, ONE) for complex bit manipulation.
+
+
+## Arguments
+
+<ParamField body="operation" type="'and' | 'or' | 'xor' | 'not' | 'diff' | 'diff1' | 'andor' | 'one'" required>
+   Specifies the type of bitwise operation to perform:
+   
+   **Standard Operations:**
+   - `and`: Bitwise AND
+   - `or`: Bitwise OR
+   - `xor`: Bitwise XOR
+   - `not`: Bitwise NOT (only accepts one source key)
+   
+   **Advanced Operations (Redis 8.2+):**
+   - `diff`: A bit is set only if it's set in all source bitmaps
+   - `diff1`: A bit is set if it's set in the first key but not in any of the other keys
+   - `andor`: A bit is set if it's set in X and also in one or more of Y1, Y2, ...
+   - `one`: A bit is set if it's set in exactly one source key
+</ParamField>
+
+<ParamField body="destinationKey" type="string" required>
+    The key to store the result of the operation in.
+</ParamField>
+
+<ParamField body="sourceKeys" type="...string[]" required >
+    One or more keys to perform the operation on.
+    </ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The size of the string stored in the destination key.
+</ResponseField>
+
+<RequestExample>
+```ts Standard Operations
+// AND operation
+await redis.bitop("and", "destKey", "sourceKey1", "sourceKey2");
+
+// OR operation
+await redis.bitop("or", "destKey", "sourceKey1", "sourceKey2");
+
+// XOR operation
+await redis.bitop("xor", "destKey", "sourceKey1", "sourceKey2");
+
+// NOT operation (only accepts one source key)
+await redis.bitop("not", "destKey", "sourceKey");
+```
+
+```ts DIFF Operation (Redis 8.2+)
+// Set bits in multiple bitmaps
+await redis.setbit("bitmap1", 0, 1);
+await redis.setbit("bitmap1", 1, 1);
+await redis.setbit("bitmap2", 1, 1);
+await redis.setbit("bitmap2", 2, 1);
+
+// DIFF: bits set in all sources
+await redis.bitop("diff", "result", "bitmap1", "bitmap2");
+// Result: bit 1 is set (only bit present in both)
+```
+
+```ts DIFF1 Operation (Redis 8.2+)
+// Set bits in bitmaps
+await redis.setbit("exclude", 0, 1);
+await redis.setbit("exclude", 1, 1);
+await redis.setbit("include1", 1, 1);
+await redis.setbit("include2", 2, 1);
+
+// DIFF1: bits in first key but not in others
+await redis.bitop("diff1", "result", "exclude", "include1", "include2");
+// Result: bit 0 is set (only in exclude, not in include1 or include2)
+```
+
+```ts ANDOR Operation (Redis 8.2+)
+// Set bits in bitmaps
+await redis.setbit("required", 0, 1);
+await redis.setbit("required", 1, 1);
+await redis.setbit("option1", 1, 1);
+await redis.setbit("option2", 2, 1);
+
+// ANDOR: bits in required AND in at least one option
+await redis.bitop("andor", "result", "required", "option1", "option2");
+// Result: bit 1 is set (in required AND in option1)
+```
+
+```ts ONE Operation (Redis 8.2+)
+// Set bits in multiple sources
+await redis.setbit("source1", 0, 1);
+await redis.setbit("source1", 1, 1);
+await redis.setbit("source2", 1, 1);
+await redis.setbit("source2", 2, 1);
+await redis.setbit("source3", 2, 1);
+
+// ONE: bits set in exactly one source
+await redis.bitop("one", "result", "source1", "source2", "source3");
+// Result: bit 0 is set (only in source1)
+```
+</RequestExample>
+
+## Advanced Operations Details (Redis 8.2+)
+
+### DIFF
+A bit in the destination is set if it is set in **all** source bitmaps. This is equivalent to the intersection of all source bitmaps.
+
+**Use Cases:**
+- Finding common features across multiple datasets
+- Identifying users present in all segments
+- Intersection of multiple filters
+
+### DIFF1
+A bit in the destination is set if it is set in the **first key** but **not in any of the other keys**. This finds bits unique to the first bitmap.
+
+**Use Cases:**
+- Finding exclusive features
+- Identifying users in one segment but not in others
+- Exclusion filtering
+
+### ANDOR
+A bit in the destination is set if it is set in **X and also in one or more of Y1, Y2, ...**. This implements "X AND (Y1 OR Y2 OR ...)" logic.
+
+**Use Cases:**
+- Required condition with optional alternatives
+- Users with a required attribute and at least one optional attribute
+- Complex filtering with mandatory and optional criteria
+
+### ONE
+A bit in the destination is set if it is set in **exactly one** of the source keys. This finds bits that are unique to a single source.
+
+**Use Cases:**
+- Finding unique occurrences
+- Identifying exclusive memberships
+- Detecting singular conditions across multiple sets
+
+<Note>
+The advanced operations (DIFF, DIFF1, ANDOR, ONE) are available in Redis 8.2.0 and later.
+</Note>

package/docs/commands/bitmap/bitpos.mdx

@@ -0,0 +1,39 @@
+---
+title: BITPOS
+description: Find the position of the first set or clear bit (bit with a value of 1 or 0) in a Redis string key. 
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+    The key to search in.
+</ParamField>
+
+<ParamField body="bit" type="0 | 1" required>
+    The key to store the result of the operation in.
+</ParamField>
+
+<ParamField body="start" type="number" >
+   The index to start searching at.
+   </ParamField>
+
+<ParamField body="end" type="number" >
+   The index to stop searching at.
+   </ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The index of the first occurrence of the bit in the string.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+ await redis.bitpos("key", 1);
+```
+
+```ts With Range
+ await redis.bitpos("key", 1, 5, 20);
+```
+
+</RequestExample>

package/docs/commands/bitmap/getbit.mdx

@@ -0,0 +1,28 @@
+---
+title: GETBIT
+description: Retrieve a single bit.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the bitset
+</ParamField>
+
+<ParamField body="offset" type="integer" required>
+  Specify the offset at which to get the bit.
+
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The bit value stored at offset.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const bit = await redis.getbit(key, 4);
+```
+</RequestExample>

package/docs/commands/bitmap/setbit.mdx

@@ -0,0 +1,31 @@
+---
+title: SETBIT
+description: Set a single bit in a string.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the bitset
+</ParamField>
+
+<ParamField body="offset" type="integer" required>
+  Specify the offset at which to set the bit.
+</ParamField>
+
+<ParamField body="value" type="0 | 1" required>
+  The bit to set
+</ParamField>
+
+## Response
+
+<ResponseField type="0 | 1" required>
+  The original bit value stored at offset.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const originalBit = await redis.setbit(key, 4, 1);
+```
+</RequestExample>

package/docs/commands/connection/client_setinfo.mdx

@@ -0,0 +1,91 @@
+---
+title: CLIENT SETINFO
+description: Set client library name and version information.
+---
+
+The `CLIENT SETINFO` command sets client library name and version information that will be shown in CLIENT LIST and CLIENT INFO commands. This helps identify which client library is being used and is useful for debugging and monitoring.
+
+## Arguments
+
+<ParamField body="attribute" type="'LIB-NAME' | 'LIB-VER'" required>
+  The attribute to set:
+  - `LIB-NAME` or `lib-name`: Library name
+  - `LIB-VER` or `lib-ver`: Library version
+</ParamField>
+
+<ParamField body="value" type="string" required>
+  The value to set for the attribute.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  Returns `OK` if the attribute was successfully set.
+</ResponseField>
+
+<RequestExample>
+```ts Set Library Name
+// Set the library name
+await redis.clientSetInfo("LIB-NAME", "redis-js");
+// Returns: "OK"
+```
+
+```ts Set Library Version
+// Set the library version
+await redis.clientSetInfo("LIB-VER", "1.0.0");
+// Returns: "OK"
+```
+
+```ts Lowercase Attributes
+// Attributes are case-insensitive
+await redis.clientSetInfo("lib-name", "redis-js");
+await redis.clientSetInfo("lib-ver", "2.0.0");
+```
+
+```ts With Custom Suffix
+// Common pattern: include wrapper or framework info
+await redis.clientSetInfo("LIB-NAME", "redis-js(upstash_v1.0.0)");
+await redis.clientSetInfo("LIB-VER", "1.0.0");
+```
+
+```ts Complete Setup
+// Set both library name and version
+await redis.clientSetInfo("LIB-NAME", "my-redis-wrapper");
+await redis.clientSetInfo("LIB-VER", "3.2.1");
+
+// Now this information will appear in CLIENT LIST output
+```
+</RequestExample>
+
+## Use Cases
+
+- **Debugging**: Identify which client library version is being used
+- **Monitoring**: Track different client libraries connecting to Redis
+- **Analytics**: Understand client library distribution across connections
+- **Support**: Quickly identify client versions when troubleshooting issues
+
+## Viewing Client Information
+
+After setting client info, you can view it using the CLIENT LIST command:
+
+```ts
+// Set client information
+await redis.clientSetInfo("LIB-NAME", "redis-js");
+await redis.clientSetInfo("LIB-VER", "1.0.0");
+
+// View all clients (if you have access to CLIENT LIST)
+// The output will include lib-name and lib-ver fields
+```
+
+## Best Practices
+
+1. **Set on Connection**: Set client info immediately after establishing a connection
+2. **Include Version**: Always set both library name and version
+3. **Use Descriptive Names**: Make library names easily identifiable
+4. **Version Format**: Use semantic versioning (e.g., "1.2.3")
+5. **Include Context**: Add wrapper or framework info if applicable
+
+<Note>
+This command is available in Redis 7.2.0 and later. The attribute names are case-insensitive and will be normalized to uppercase.
+</Note>
+

package/docs/commands/functions/call.mdx

@@ -0,0 +1,72 @@
+---
+title: FCALL
+description: Invoke a function.
+---
+
+## Arguments
+
+<ParamField body="function" type="string" required>
+  The function name.
+</ParamField>
+
+<ParamField body="keys" type="string[]">
+  The keys that the function accesses. 
+  <Warning>
+    The function can only read/write from the keys that are provided in the `keys` argument.
+  </Warning>
+</ParamField>
+
+<ParamField body="args" type="string[]">
+  The arguments for the function.
+</ParamField>
+
+## Response
+
+<ResponseField type="unknown" required>
+  The return value of the function.
+</ResponseField>
+
+<RequestExample>
+```ts Basic
+const code = `
+#!lua name=mylib
+redis.register_function('helloworld', 
+  function()
+    return 'Hello World!'
+  end
+)
+`;
+
+await redis.functions.load({ code, replace: true });
+
+const res = await redis.functions.call("helloworld");
+console.log(res); // "Hello World!"
+```
+
+```ts Advanced
+const code = `
+#!lua name=mylib
+
+redis.register_function('my_hset',
+  function (keys, args)
+    local hash = keys[1]
+    local time = redis.call('TIME')[1]
+    return redis.call('HSET', hash, '_last_modified_', time, unpack(args))
+  end
+)
+`;
+
+await redis.functions.load({ code, replace: true });
+
+const res = await redis.functions.call(
+  "my_hset",
+  ["myhash"],
+  [
+    "myfield",
+    "some value",
+    "another_field",
+    "another value",
+  ],
+);
+```
+</RequestExample>

package/docs/commands/functions/call_ro.mdx

@@ -0,0 +1,57 @@
+---
+title: FCALL_RO
+description: Invoke a read-only function
+---
+
+<Note>
+  The function must be declared with the `no-writes` flag for it to be used with `callRo`.
+</Note>
+
+## Arguments
+
+<ParamField body="function" type="string" required>
+  The function name.
+</ParamField>
+
+<ParamField body="keys" type="string[]">
+  The keys that the function accesses.
+
+  <Warning>
+    The function can only read from the keys that are provided in the `keys` argument.
+  </Warning>
+</ParamField>
+
+<ParamField body="args" type="string[]">
+  The arguments for the function.
+</ParamField>
+
+## Response
+
+<ResponseField type="unknown" required>
+  The return value of the function.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const code = `
+#!lua name=ro_lib
+  
+local function get_value(keys, args)
+  return redis.call('GET', keys[1])
+end
+
+redis.register_function({
+  function_name='get_value', 
+  callback=get_value, 
+  flags={ 'no-writes' }
+})
+`;
+
+await redis.functions.load({ code, replace: true });
+
+// Call the read-only function
+// Note: We can modify the keys usage here, but since it represents a read-only operation
+// and we marked it with 'no-writes', it is safe to use callRo.
+const value = await redis.functions.callRo("get_value", ["mykey"])
+```
+</RequestExample>

package/docs/commands/functions/delete.mdx

@@ -0,0 +1,22 @@
+---
+title: FUNCTION DELETE
+description: Delete a library and all its functions.
+---
+
+## Arguments
+
+<ParamField body="libraryName" type="string" required>
+  The name of the library to delete.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  "OK"
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.functions.delete("mylib")
+```
+</RequestExample>