@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/hash/hpexpire.mdx

@@ -0,0 +1,50 @@
+---
+title: HPEXPIRE
+description: Sets an expiration time for a field in a hash in milliseconds.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="string | number | (string | number)[]" required>
+  The field or list of fields within the hash to set the expiry for.
+</ParamField>
+
+<ParamField body="milliseconds" type="number" required>
+  The time-to-live (TTL) in milliseconds.
+</ParamField>
+
+<ParamField body="option" type="string" optional>
+  Optional condition for setting the expiration:
+  - `NX`: Set the expiration only if the field does not already have an expiration.
+  - `XX`: Set the expiration only if the field already has an expiration.
+  - `GT`: Set the expiration only if the new TTL is greater than the current TTL.
+  - `LT`: Set the expiration only if the new TTL is less than the current TTL.
+
+  For more details, see [HPEXPIRE documentation](/redis/commands/hash/hpexpire).
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  A list of integers indicating whether the expiry was successfully set.
+
+  - `-2` if the field does not exist in the hash or if key doesn't exist.
+  - `0` if the expiration was not set due to the condition.
+  - `1` if the expiration was successfully set.
+  - `2` if called with 0 seconds/milliseconds or a past Unix time.
+
+  For more details, see [HPEXPIRE documentation](/redis/commands/hash/hpexpire).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+const expirationSet = await redis.hpexpire("my-key", "my-field", 1000);
+
+console.log(expirationSet); // [1]
+```
+</RequestExample>

package/docs/commands/hash/hpexpireat.mdx

@@ -0,0 +1,48 @@
+---
+title: HPEXPIREAT
+description: Sets an expiration time for field(s) in a hash in milliseconds since the Unix epoch.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="string | number | (string | number)[]" required>
+  The field(s) to set an expiration time for.
+</ParamField>
+
+<ParamField body="timestamp" type="number" required>
+  The expiration time as a Unix timestamp in milliseconds.
+</ParamField>
+
+<ParamField body="option" type="string" optional>
+  Optional condition for setting the expiration:
+  - `NX`: Set the expiration only if the field does not already have an expiration.
+  - `XX`: Set the expiration only if the field already has an expiration.
+  - `GT`: Set the expiration only if the new TTL is greater than the current TTL.
+  - `LT`: Set the expiration only if the new TTL is less than the current TTL.
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  A list of integers indicating whether the expiry was successfully set.
+
+  - `-2` if the field does not exist in the hash or if key doesn't exist.
+  - `0` if the expiration was not set due to the condition.
+  - `1` if the expiration was successfully set.
+  - `2` if called with 0 seconds/milliseconds or a past Unix time.
+
+  For more details, see [HPEXPIREAT documentation](/redis/commands/hash/hpexpireat).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+const expirationSet = await redis.hpexpireat("my-key", "my-field", Date.now() + 1000);
+
+console.log(expirationSet); // [1]
+```
+</RequestExample>

package/docs/commands/hash/hpexpiretime.mdx

@@ -0,0 +1,35 @@
+---
+title: HPEXPIRETIME
+description: Retrieves the expiration time of a field in a hash in milliseconds.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="string | number | (string | number)[]" required>
+  The field(s) to retrieve the expiration time for.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The expiration time in milliseconds since the Unix epoch.
+
+  - `-2` if the field does not exist in the hash or if the key doesn't exist.
+  - `-1` if the field exists but has no associated expiration.
+
+  For more details, see [HPEXPIRETIME documentation](/redis/commands/hash/hpexpiretime).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+await redis.hpexpireat("my-key", "my-field", Date.now() + 1000);
+const expireTime = await redis.hpexpiretime("my-key", "my-field");
+
+console.log(expireTime); // e.g., 1697059200000
+```
+</RequestExample>

package/docs/commands/hash/hpttl.mdx

@@ -0,0 +1,35 @@
+---
+title: HPTTL
+description: Retrieves the remaining time-to-live (TTL) for field(s) in a hash in milliseconds.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="string | number | (string | number)[]" required>
+  The field(s) to retrieve the TTL for.
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  The remaining TTL in milliseconds for each field.
+
+  - `-2` if the field does not exist in the hash or if the key doesn't exist.
+  - `-1` if the field exists but has no associated expiration.
+
+  For more details, see [HPTTL documentation](/redis/commands/hash/hpttl).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+await redis.hpexpire("my-key", "my-field", 1000);
+const ttl = await redis.hpttl("my-key", "my-field");
+
+console.log(ttl); // e.g., [950]
+```
+</RequestExample>

package/docs/commands/hash/hrandfield.mdx

@@ -0,0 +1,57 @@
+---
+title: HRANDFIELD
+description: Return a random field from a hash
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="count" type="integer">
+  Optionally return more than one field.
+</ParamField>
+
+<ParamField body="withValues" type="boolean">
+  Return the values of the fields as well.
+</ParamField>
+
+## Response
+
+<ResponseField type="Record<string, unknown>" required>
+  An object containing the fields and their values.
+</ResponseField>
+
+<RequestExample>
+```ts Basic
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas"
+ });
+const randomField = await redis.hrandfield("key");
+console.log(randomField); // one of "id", "username" or  "name"
+```
+
+```ts Multiple Fields
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas",
+});
+const randomFields = await redis.hrandfield("key", 2);
+console.log(randomFields); // ["id", "username"] or any other combination
+```
+
+```ts With Values
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas",
+});
+const randomFields = await redis.hrandfield("key", 2, true);
+console.log(randomFields); // { id: "1", username: "chronark" } or any other combination
+```
+
+</RequestExample>

package/docs/commands/hash/hscan.mdx

@@ -0,0 +1,65 @@
+---
+title: HSCAN
+description: Scan a hash for fields.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</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 field names.
+  </ParamField>
+  <ParamField body="count" type="number">
+    Number of fields to return per call.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="[number, string[]]" required>
+  The new cursor and the fields array in format `[field, value, field, value]`.
+  If the new cursor is `0` the iteration is complete.
+</ResponseField>
+
+<RequestExample>
+```ts Basic
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas"
+ });
+const [newCursor, fields] = await redis.hscan("key", 0);
+console.log(newCursor); // likely `0` since this is a very small hash
+console.log(fields); // ["id", 1, "username", "chronark", "name", "andreas"]
+```
+
+```ts Match
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas",
+});
+const [newCursor, fields] = await redis.hscan("key", 0, { match: "user*" });
+console.log(newCursor); // likely `0` since this is a very small hash
+console.log(fields); // ["username", "chronark"]
+```
+
+
+```ts Count
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas",
+});
+const [newCursor, fields] = await redis.hscan("key", 0, { count: 2 });
+console.log(fields); // ["id", 1, "name", "andreas", "username", "chronark"]
+```
+</RequestExample>

package/docs/commands/hash/hset.mdx

@@ -0,0 +1,32 @@
+---
+title: HSET
+description: Write one or more fields to a hash.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="{ [fieldName]: TValue }" required>
+  An object of fields and their values.
+
+</ParamField>
+
+
+## Response
+
+<ResponseField type="integer" required>
+  The number of fields that were added.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas"
+  });
+```
+</RequestExample>

package/docs/commands/hash/hsetex.mdx

@@ -0,0 +1,186 @@
+---
+title: HSETEX
+description: Set hash fields with expiration support.
+---
+
+The `HSETEX` command sets the specified fields with their values and optionally sets their expiration time or TTL. It supports conditional operations to control when fields should be set.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="options" type="object">
+  Options for conditional setting and expiration.
+
+  <Expandable title="properties">
+    <ParamField body="conditional" type="'FNX' | 'fnx' | 'FXX' | 'fxx'">
+      Conditional setting options (case-insensitive):
+      - `FNX`: Only set fields if the hash does not exist
+      - `FXX`: Only set fields if the hash already exists
+    </ParamField>
+
+    <ParamField body="expiration" type="object">
+      Expiration options for the hash.
+
+      <Expandable title="expiration">
+        <ParamField body="ex" type="number">
+          Set expiration time in seconds.
+        </ParamField>
+
+        <ParamField body="px" type="number">
+          Set expiration time in milliseconds.
+        </ParamField>
+
+        <ParamField body="exat" type="number">
+          Set expiration as Unix timestamp in seconds.
+        </ParamField>
+
+        <ParamField body="pxat" type="number">
+          Set expiration as Unix timestamp in milliseconds.
+        </ParamField>
+
+        <ParamField body="keepttl" type="true">
+          Retain the existing time to live (TTL) associated with the hash key when setting fields. If the hash has an expiration, it will be preserved. Set to `true` to enable.
+        </ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="fields" type="{ [fieldName]: TValue }" required>
+  An object of fields and their values to set.
+</ParamField>
+
+## Response
+
+<ResponseField type="number" required>
+  The number of fields that were set. Returns 0 if conditions are not met (e.g., `conditional: "FNX"` but hash exists, or `conditional: "FXX"` but hash doesn't exist).
+</ResponseField>
+
+<RequestExample>
+```ts Basic Example
+// Set fields with 1 hour expiration
+await redis.hsetex("user:123", { expiration: { ex: 3600 } }, { 
+  name: "John", 
+  email: "john@example.com" 
+});
+```
+
+```ts With FNX (only if hash doesn't exist)
+// Set fields only if the hash doesn't exist
+const result = await redis.hsetex(
+  "user:456", 
+  { conditional: "FNX" }, 
+  { name: "Jane", age: "25" }
+);
+console.log(result); // 2 (if hash didn't exist)
+
+// Try again - will return 0 since hash now exists
+const result2 = await redis.hsetex(
+  "user:456", 
+  { conditional: "FNX" }, 
+  { email: "jane@example.com" }
+);
+console.log(result2); // 0
+```
+
+```ts With FXX (only if hash exists)
+// First create the hash
+await redis.hset("session:abc", { token: "xyz" });
+
+// Update only if hash exists
+const result = await redis.hsetex(
+  "session:abc", 
+  { conditional: "FXX" }, 
+  { user: "john" }
+);
+console.log(result); // 1 (hash exists, field added)
+
+// Try on non-existent hash
+const result2 = await redis.hsetex(
+  "session:nonexistent", 
+  { conditional: "FXX" }, 
+  { user: "jane" }
+);
+console.log(result2); // 0 (hash doesn't exist)
+```
+
+```ts With PX (milliseconds)
+// Set fields with 30 second expiration
+await redis.hsetex("cache:data", { expiration: { px: 30000 } }, { 
+  value: "cached data",
+  timestamp: Date.now().toString()
+});
+```
+
+```ts With EXAT (Unix timestamp in seconds)
+// Set expiration to specific timestamp
+const futureTime = Math.floor(Date.now() / 1000) + 7200; // 2 hours from now
+await redis.hsetex("temp:data", { expiration: { exat: futureTime } }, { 
+  info: "temporary information" 
+});
+```
+
+```ts With PXAT (Unix timestamp in milliseconds)
+// Set expiration to specific timestamp in milliseconds
+const futureTime = Date.now() + 300000; // 5 minutes from now
+await redis.hsetex("session:xyz", { expiration: { pxat: futureTime } }, { 
+  token: "abc123",
+  user: "john"
+});
+```
+
+```ts Combined: Conditional + Expiration
+// Set fields only if hash doesn't exist, with 1 hour expiration
+await redis.hsetex(
+  "user:789", 
+  { 
+    conditional: "FNX", 
+    expiration: { ex: 3600 } 
+  }, 
+  { 
+    name: "Alice",
+    email: "alice@example.com",
+    created: Date.now().toString()
+  }
+);
+```
+
+```ts With KEEPTTL
+// First set fields with expiration
+await redis.hsetex("cache:data", { expiration: { ex: 300 } }, { 
+  value: "cached" 
+});
+
+// Later update fields while retaining the existing TTL
+const result = await redis.hsetex(
+  "cache:data", 
+  { expiration: { keepttl: true } }, 
+  { updated: "yes" }
+);
+console.log(result); // 1
+
+// Verify TTL is still 300 seconds (or less if time passed)
+const ttl = await redis.ttl("cache:data");
+console.log(ttl); // Should be > 0 and <= 300 (TTL was retained)
+```
+
+```ts Without Options
+// Just set fields without expiration or conditions
+await redis.hsetex("data:simple", undefined, { 
+  field1: "value1", 
+  field2: "value2" 
+});
+```
+</RequestExample>
+
+## Use Cases
+
+- **Session Management**: Create sessions with automatic expiration
+- **Cache with TTL**: Store cached data that expires automatically
+- **Temporary Data**: Create temporary records with built-in cleanup
+- **Rate Limiting**: Store rate limit counters with automatic reset
+- **Conditional Updates**: Ensure data consistency with FNX/FXX options
+

package/docs/commands/hash/hsetnx.mdx

@@ -0,0 +1,30 @@
+---
+title: HSETNX
+description: Write a field to a hash but only if the field does not exist.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="field" type="string" required>
+  The name of the field.
+</ParamField>
+
+<ParamField body="value" type="TValue" required>
+  Any value, if it's not a string it will be serialized to JSON.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  `1` if the field was set, `0` if it already existed.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hsetnx("key", "id", 1)
+```
+</RequestExample>

package/docs/commands/hash/hstrlen.mdx

@@ -0,0 +1,28 @@
+---
+title: HSTRLEN
+description: Returns the string length of a value in a hash.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="field" type="string" required>
+  The name of the field.
+</ParamField>
+
+
+
+## Response
+
+<ResponseField type="integer" required>
+  `0` if the hash or field does not exist. Otherwise the length of the string.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+const length = await redis.hstrlen("key", "field")
+```
+</RequestExample>

package/docs/commands/hash/httl.mdx

@@ -0,0 +1,35 @@
+---
+title: HTTL
+description: Retrieves the remaining time-to-live (TTL) for field(s) in a hash in seconds.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="string | number | (string | number)[]" required>
+  The field(s) to retrieve the TTL for.
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  The remaining TTL in seconds for each field.
+
+  - `-2` if the field does not exist in the hash or if the key doesn't exist.
+  - `-1` if the field exists but has no associated expiration.
+
+  For more details, see [HTTL documentation](/redis/commands/hash/httl).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+await redis.hexpire("my-key", "my-field", 10);
+const ttl = await redis.httl("my-key", "my-field");
+
+console.log(ttl); // e.g., [9]
+```
+</RequestExample>

package/docs/commands/hash/hvals.mdx

@@ -0,0 +1,29 @@
+---
+title: HVALS
+description: Returns all values in the hash stored at key.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+
+
+## Response
+
+<ResponseField type="unknown[]" required>
+  All values in the hash, or an empty list when key does not exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  field1: "Hello",
+  field2: "World",
+})
+const values = await redis.hvals("key")
+console.log(values) // ["Hello", "World"]
+```
+</RequestExample>

package/docs/commands/json/arrappend.mdx

@@ -0,0 +1,35 @@
+---
+title: JSON.ARRAPPEND
+description: Append values to the array at path in the JSON document at key.
+---
+<Tip>
+To specify a string as an array value to append, wrap the quoted string with an additional set of single quotes. Example: '"silver"'.
+</Tip>
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+    The key of the json entry.
+</ParamField>
+<ParamField body="path" type="string" required>
+    The path of the array. `$` is the root.
+</ParamField>
+
+
+
+<ParamField body="value" type="...TValue[]" required>
+    One or more values to append to the array.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="integer[]" required>
+  The length of the array after the appending.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.json.arrappend("key", "$.path.to.array", "a");
+```
+</RequestExample>