@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/functions/flush.mdx

@@ -0,0 +1,16 @@
+---
+title: FUNCTION FLUSH
+description: Delete all the libraries and functions.
+---
+
+## Response
+
+<ResponseField type="string" required>
+  "OK"
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.functions.flush()
+```
+</RequestExample>

package/docs/commands/functions/list.mdx

@@ -0,0 +1,72 @@
+---
+title: FUNCTION LIST
+description: List details about the registered libraries and functions.
+---
+
+## Arguments
+
+<ParamField body="options" type="Object">
+  The list options.
+  <Expandable>
+    <ParamField body="libraryName" type="string">
+      Pattern for matching library names.
+    </ParamField>
+    <ParamField body="withCode" type="boolean" default="false">
+      Whether to include the library source code in the response.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="Object[]" required>
+  List of libraries.
+  <Expandable>
+    <ResponseField name="libraryName" type="string" required>
+      The name of the library.
+    </ResponseField>
+    <ResponseField name="engine" type="string" required>
+      The engine used by the library (e.g., "LUA").
+    </ResponseField>
+    <ResponseField name="functions" type="Object[]" required>
+      List of functions in the library.
+      <Expandable>
+        <ResponseField name="name" type="string" required>
+          The name of the function.
+        </ResponseField>
+        <ResponseField name="description" type="string | undefined" required>
+          The description of the function, or undefined if not provided.
+        </ResponseField>
+        <ResponseField name="flags" type="string[]" required>
+          List of flags for the function (e.g., "no-writes").
+        </ResponseField>
+      </Expandable>
+    </ResponseField>
+    <ResponseField name="libraryCode" type="string">
+      The source code of the library (only included if `withCode` is true).
+    </ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const libs = await redis.functions.list({
+    libraryName: "mylib",
+    withCode: true
+})
+
+console.log(libs)
+// [
+//   {
+//     libraryName: "mylib",
+//     engine: "LUA",
+//     functions: [{
+//       name: "my_func",
+//       description: null,
+//       flags: [ "no-writes" ]
+//     }],
+//     libraryCode: "#!lua name=mylib ..."
+//   }
+// ]
+```
+</RequestExample>

package/docs/commands/functions/load.mdx

@@ -0,0 +1,64 @@
+---
+title: FUNCTION LOAD
+description: Load a library to Redis.
+---
+
+Redis functions act as a superset of Lua scripts. Instead of sending the script
+content with every request (like `EVAL`), you load the script once as a
+"library" and call the functions it registers.
+
+<Note>
+  Currently, `LUA` is the only supported engine.
+</Note>
+
+The library source code must start with the `#!lua name=<library_name>` shebang.
+Inside the script, use `redis.register_function` to expose your functions.
+
+The registered functions can be called with the [FCALL](./call) command.
+
+## Arguments
+
+<ParamField body="options" type="Object" required>
+  The load options.
+  <Expandable>
+    <ParamField body="code" type="string" required>
+      The source code of the library.
+    </ParamField>
+    <ParamField body="replace" type="boolean" default="false">
+      Whether to overwrite the library if it already exists. If `false` and the
+      library already exists, Redis will return an error.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  The name of the loaded library.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const code = `#!lua name=mylib
+  
+  -- Simple function that returns a string
+  redis.register_function(
+    'helloworld',
+    function() return 'Hello World!' end
+  )
+
+  -- Complex function that modifies data with logic
+  local function my_hset(keys, args)
+    local hash = keys[1]
+    local time = redis.call('TIME')[1]
+    return redis.call('HSET', hash, '_last_modified_', time, unpack(args))
+  end
+
+  redis.register_function('my_hset', my_hset)
+`;
+
+const libraryName = await redis.functions.load({ code, replace: true });
+
+console.log(libraryName); // "mylib"
+```
+</RequestExample>

package/docs/commands/functions/stats.mdx

@@ -0,0 +1,46 @@
+---
+title: FUNCTION STATS
+description: Return information about the function running engine.
+---
+
+## Response
+
+<ResponseField type="Object" required>
+  Stats about the engines and functions.
+  
+  <Note> 
+  Currently, `LUA` is the only supported engine.
+  </Note>
+  <Expandable>
+    <ParamField body="engines" type="Object">
+      <Expandable>
+        <ParamField body="LUA" type="Object">
+          <Expandable>
+            <ParamField body="librariesCount" type="number">
+              The number of libraries.
+            </ParamField>
+            <ParamField body="functionsCount" type="number">
+              The number of functions.
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const stats = await redis.functions.stats()
+
+console.log(stats)
+// {
+//   engines: {
+//     LUA: {
+//       librariesCount: 3,
+//       functionsCount: 15
+//     }
+//   }
+// }
+```
+</RequestExample>

package/docs/commands/generic/del.mdx

@@ -0,0 +1,29 @@
+---
+title: DEL
+description: Removes the specified keys. A key is ignored if it does not exist.
+---
+
+
+## Arguments
+
+<ParamField body="keys" type="...string[]" required>
+  One or more keys to remove.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of keys that were removed.
+</ResponseField>
+
+<RequestExample>
+```ts Basic
+await redis.del("key1", "key2");
+```
+```ts Array
+// in case you have an array of keys
+const keys = ["key1", "key2"];
+await redis.del(...keys)
+
+```
+</RequestExample>

package/docs/commands/generic/exists.mdx

@@ -0,0 +1,26 @@
+---
+title: EXISTS
+description: Check if a key exists.
+---
+
+
+## Arguments
+
+<ParamField body="keys" type="...string[]" required>
+  One or more keys to check.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of keys that exist
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key1", "value1")
+await redis.set("key2", "value2")
+const keys = await redis.exists("key1", "key2", "key3");
+console.log(keys) // 2
+```
+</RequestExample>

package/docs/commands/generic/expire.mdx

@@ -0,0 +1,29 @@
+---
+title: EXPIRE
+description: Sets a timeout on key. The key will automatically be deleted.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to set the timeout on.
+</ParamField>
+
+<ParamField body="seconds" type="integer">
+ How many seconds until the key should be deleted.
+
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  `1` if the timeout was set, `0` otherwise
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("mykey", "Hello");
+await redis.expire("mykey", 10);
+```
+</RequestExample>

package/docs/commands/generic/expireat.mdx

@@ -0,0 +1,29 @@
+---
+title: EXPIREAT
+description: Sets a timeout on key. The key will automatically be deleted.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to set the timeout on.
+</ParamField>
+
+<ParamField body="unix" type="integer">
+A unix timestamp in seconds at which point the key will expire.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  `1` if the timeout was set, `0` otherwise
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("mykey", "Hello");
+const tenSecondsFromNow = Math.floor(Date.now() / 1000) + 10;
+await redis.expireat("mykey", tenSecondsFromNow);
+```
+</RequestExample>

package/docs/commands/generic/keys.mdx

@@ -0,0 +1,32 @@
+---
+title: KEYS
+description: Returns all keys matching pattern.
+---
+
+<Warning>
+This command can block the database for an extended period, especially with large datasets. We recommend using [SCAN](/redis/sdks/ts/commands/generic/scan) instead for production environments.
+
+This command will return an error for databases containing more than 100,000 entries.
+</Warning>
+
+
+## Arguments
+
+<ParamField body="match" type="string" required>
+  A glob-style pattern. Use `*` to match all keys.
+</ParamField>
+
+## Response
+
+<ResponseField type="string[]" required>
+  Array of keys matching the pattern.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const keys = await redis.keys("prefix*");
+```
+```ts Match All
+const keys = await redis.keys("*");
+```
+</RequestExample>

package/docs/commands/generic/persist.mdx

@@ -0,0 +1,23 @@
+---
+title: PERSIST
+description: Remove any timeout set on the key.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to persist
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  `1` if the timeout was removed, `0` if `key` does not exist or does not have an associated timeout.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.persist(key);
+```
+</RequestExample>

package/docs/commands/generic/pexpire.mdx

@@ -0,0 +1,28 @@
+---
+title: PEXPIRE
+description: Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to expire.
+</ParamField>
+
+<ParamField body="milliseconds" type="integer">
+  The number of milliseconds until the key expires.
+
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+ `1` if the timeout was applied, `0` if `key` does not exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+ await redis.pexpire(key, 60_000); // 1 minute
+```
+</RequestExample>

package/docs/commands/generic/pexpireat.mdx

@@ -0,0 +1,29 @@
+---
+title: PEXPIREAT
+description: Sets a timeout on key. After the timeout has expired, the key will automatically be deleted.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to expire.
+</ParamField>
+
+<ParamField body="unixmilli" type="integer">
+  The unix timestamp in milliseconds at which the key will expire.
+
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+ `1` if the timeout was applied, `0` if `key` does not exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const 10MinutesFromNow = Date.now() + 10 * 60 * 1000;
+ await redis.pexpireat(key, 10MinutesFromNow);
+```
+</RequestExample>

package/docs/commands/generic/pttl.mdx

@@ -0,0 +1,23 @@
+---
+title: PTTL
+description: Return the expiration in milliseconds of a key.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key 
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of milliseconds until this expires, negative if the key does not exist or does not have an expiration set.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const millis = await redis.pttl(key);
+```
+</RequestExample>

package/docs/commands/generic/randomkey.mdx

@@ -0,0 +1,21 @@
+---
+title: RANDOMKEY
+description: Returns a random key from database
+---
+
+
+## Arguments
+
+No arguments
+
+## Response
+
+<ResponseField type="string" required>
+A random key from database, or `null` when database is empty.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const key = await redis.randomkey();
+```
+</RequestExample>

package/docs/commands/generic/rename.mdx

@@ -0,0 +1,28 @@
+---
+title: RENAME
+description: Rename a key
+---
+
+
+## Arguments
+
+<ParamField body="source" type="string" required>
+  The original key.
+</ParamField>
+
+
+<ParamField body="destination" type="string" required>
+  A new name for the key.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+ `OK`
+</ResponseField>
+
+<RequestExample>
+```ts Example
+ await redis.rename("old", "new");
+```
+</RequestExample>

package/docs/commands/generic/renamenx.mdx

@@ -0,0 +1,28 @@
+---
+title: RENAMENX
+description: Rename a key if it does not already exist.
+---
+
+
+## Arguments
+
+<ParamField body="source" type="string" required>
+  The original key.
+</ParamField>
+
+
+<ParamField body="destination" type="string" required>
+  A new name for the key.
+</ParamField>
+
+## Response
+
+<ResponseField type="0 | 1" required>
+ `1` if key was renamed, `0` if key was not renamed.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const renamed = await redis.renamenx("old", "new");
+```
+</RequestExample>

package/docs/commands/generic/scan.mdx

@@ -0,0 +1,38 @@
+---
+title: SCAN
+description: Scan the database for keys.
+---
+
+## Arguments
+
+<ParamField body="cursor" type="string">
+  The cursor value. Start with "0" on the first call, then use the cursor
+  returned by each call for the next. It's a string to safely support large
+  numbers that might exceed JavaScript's number limits.
+</ParamField>
+
+<ParamField body="options" type="Object">
+  <ParamField body="match" type="string">
+    Glob-style pattern to filter by field names.
+  </ParamField>
+  <ParamField body="count" type="number">
+    Number of fields to return per call.
+  </ParamField>
+  <ParamField body="type" type="string">
+    Filter by type. For example `string`, `hash`, `set`, `zset`, `list`,
+    `stream`.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="[string, string[]]" required>
+  Returns the next cursor and the list of matching keys. When the returned
+  cursor is "0", the scan is complete.
+</ResponseField>
+
+<RequestExample>
+```ts Basic
+const [cursor, keys] = await redis.scan(0, { match: "*" });
+```
+</RequestExample>

package/docs/commands/generic/touch.mdx

@@ -0,0 +1,23 @@
+---
+title: TOUCH
+description: Alters the last access time of one or more keys
+---
+
+
+## Arguments
+
+<ParamField body="keys" type="...string[]" required>
+  One or more keys.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of keys that were touched.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.touch("key1", "key2", "key3");
+```
+</RequestExample>

package/docs/commands/generic/ttl.mdx

@@ -0,0 +1,23 @@
+---
+title: TTL
+description: Return the expiration in seconds of a key.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key 
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of seconds until this expires, negative if the key does not exist or does not have an expiration set.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const seconds = await redis.ttl(key);
+```
+</RequestExample>

package/docs/commands/generic/type.mdx

@@ -0,0 +1,27 @@
+---
+title: TYPE
+description: Get the type of a key.
+---
+
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+## Response
+
+<ResponseField type="string" required>
+  The type of the key.
+
+  One of `string` | `list` | `set` | `zset` | `hash` | `none`
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.set("key", "value");
+const t = await redis.type("key");
+console.log(t) // "string"
+```
+</RequestExample>

package/docs/commands/generic/unlink.mdx

@@ -0,0 +1,29 @@
+---
+title: UNLINK
+description: Removes the specified keys. A key is ignored if it does not exist.
+---
+
+
+## Arguments
+
+<ParamField body="keys" type="...string[]" required>
+  One or more keys to unlink.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of keys that were unlinked.
+</ResponseField>
+
+<RequestExample>
+```ts Basic
+await redis.unlink("key1", "key2");
+```
+```ts Array
+// in case you have an array of keys
+const keys = ["key1", "key2"];
+await redis.unlink(...keys)
+
+```
+</RequestExample>