@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/hash/hdel.mdx

@@ -0,0 +1,28 @@
+---
+title: HDEL
+description: Deletes one or more hash fields.
+---
+
+
+## Arguments
+
+<ParamField body="key"type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="fields" required>
+  One or more fields to delete.
+</ParamField>
+
+## Response
+
+<ResponseField  type="integer" required>
+    The number of fields that were removed from the hash.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hdel(key, 'field1', 'field2');
+// returns 5
+```
+</RequestExample>

package/docs/commands/hash/hexists.mdx

@@ -0,0 +1,30 @@
+---
+title: HEXISTS
+description: Checks if a field exists in a hash.
+---
+
+
+## Arguments
+
+<ParamField body="key"type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="field"type="string" required>
+ The field to check.
+</ParamField>
+
+## Response
+
+<ResponseField  type="integer" required>
+   `1` if the hash contains `field`. `0` if the hash does not contain `field`, or `key` does not exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", "field", "value");
+const exists = await redis.hexists("key", "field");
+
+console.log(exists); // 1
+```
+</RequestExample>

package/docs/commands/hash/hexpire.mdx

@@ -0,0 +1,49 @@
+---
+title: HEXPIRE
+description: Sets an expiration time for one or more fields in a hash.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="field" type="string | number | (string | number)[]" required>
+  The field or fields to set an expiration time for.
+</ParamField>
+
+<ParamField body="seconds" type="number" required>
+  The time-to-live (TTL) in seconds.
+</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 [HEXPIRE documentation](/redis/commands/hash/hexpire).
+</ResponseField>
+
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+const expirationSet = await redis.hexpire("my-key", "my-field", 1);
+
+console.log(expirationSet); // 1
+```
+</RequestExample>

package/docs/commands/hash/hexpireat.mdx

@@ -0,0 +1,48 @@
+---
+title: HEXPIREAT
+description: Sets an expiration time for field(s) in a hash in seconds 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 seconds.
+</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 [HEXPIREAT documentation](/redis/commands/hash/hexpireat).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+const expirationSet = await redis.hexpireat("my-key", "my-field", Math.floor(Date.now() / 1000) + 10);
+
+console.log(expirationSet); // [1]
+```
+</RequestExample>

package/docs/commands/hash/hexpiretime.mdx

@@ -0,0 +1,35 @@
+---
+title: HEXPIRETIME
+description: Retrieves the expiration time of 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 expiration time for.
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  The expiration time in seconds since the Unix epoch 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 [HEXPIRETIME documentation](/redis/commands/hash/hexpiretime).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+await redis.hexpireat("my-key", "my-field", Math.floor(Date.now() / 1000) + 10);
+const expireTime = await redis.hexpiretime("my-key", "my-field");
+
+console.log(expireTime); // e.g., [1697059200]
+```
+</RequestExample>

package/docs/commands/hash/hget.mdx

@@ -0,0 +1,29 @@
+---
+title: HGET
+description: Retrieves the value of a hash field.
+---
+
+
+## Arguments
+
+<ParamField body="key"type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="field"type="string" required>
+ The field to get.
+</ParamField>
+
+## Response
+
+<ResponseField  type="TValue | null" required>
+  The value of the field, or `null`, when field is not present in the hash or key does not exist.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {field: "value"});
+const field = await redis.hget("key", "field");
+console.log(field); // "value"
+```
+</RequestExample>

package/docs/commands/hash/hgetall.mdx

@@ -0,0 +1,27 @@
+---
+title: HGETALL
+description: Retrieves all fields from a hash.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+## Response
+
+<ResponseField type="TValue | null" required>
+  An object with all fields in the hash.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  field1: "value1",
+  field2: "value2",
+  });
+const hash = await redis.hgetall("key");
+console.log(hash); // { field1: "value1", field2: "value2" }
+```
+</RequestExample>

package/docs/commands/hash/hgetdel.mdx

@@ -0,0 +1,67 @@
+---
+title: HGETDEL
+description: Get and delete hash fields atomically.
+---
+
+The `HGETDEL` command returns the values of the specified fields and then atomically deletes them from the hash. This is useful when you need to retrieve and remove data in a single atomic operation.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="...string[]" required>
+  One or more field names to get and delete.
+</ParamField>
+
+## Response
+
+<ResponseField type="Record<string, TValue | null> | null" required>
+  An object containing the field names and their values in the format `{[fieldName: string]: TValue | null}`. Returns `null` for fields that do not exist. If the hash doesn't exist or all fields are non-existent, `null` is returned.
+</ResponseField>
+
+<RequestExample>
+```ts Basic Example
+// Set some hash fields
+await redis.hset("user:123", { name: "John", age: "30", email: "john@example.com" });
+
+// Get and delete specific fields
+const result = await redis.hgetdel("user:123", "name", "email");
+console.log(result); // { name: "John", email: "john@example.com" }
+
+// Verify fields were deleted
+const name = await redis.hget("user:123", "name");
+console.log(name); // null
+```
+
+```ts Multiple Fields
+await redis.hset("session:abc", { 
+  token: "xyz123", 
+  user: "john", 
+  expires: "2024-12-31" 
+});
+
+// Get and delete all fields
+const session = await redis.hgetdel("session:abc", "token", "user", "expires");
+console.log(session); 
+// { token: "xyz123", user: "john", expires: "2024-12-31" }
+```
+
+```ts Non-existent Fields
+await redis.hset("user:456", { name: "Jane" });
+
+// Get and delete with non-existent field
+const result = await redis.hgetdel("user:456", "name", "email");
+console.log(result); // { name: "Jane", email: null }
+```
+</RequestExample>
+
+## Use Cases
+
+- **Session Management**: Retrieve and invalidate session data atomically
+- **Cache Cleanup**: Get cached data while removing it from storage
+- **Queue Processing**: Fetch and remove job data in a single operation
+- **Temporary Data**: Retrieve one-time use tokens or codes while deleting them
+
+

package/docs/commands/hash/hgetex.mdx

@@ -0,0 +1,123 @@
+---
+title: HGETEX
+description: Get hash fields with expiration support.
+---
+
+The `HGETEX` command returns the values of the specified fields and optionally sets their expiration time or TTL. This allows you to retrieve hash data while managing its lifetime in a single operation.
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="options" type="object" required>
+  Expiration options for the hash fields. The options are mutually exclusive - you can only use one at a time.
+
+  <Expandable title="properties">
+    <ParamField body="ex" type="number">
+      Set expiration time in seconds. Cannot be used with other expiration options.
+    </ParamField>
+
+    <ParamField body="px" type="number">
+      Set expiration time in milliseconds. Cannot be used with other expiration options.
+    </ParamField>
+
+    <ParamField body="exat" type="number">
+      Set expiration as Unix timestamp in seconds. Cannot be used with other expiration options.
+    </ParamField>
+
+    <ParamField body="pxat" type="number">
+      Set expiration as Unix timestamp in milliseconds. Cannot be used with other expiration options.
+    </ParamField>
+
+    <ParamField body="persist" type="true">
+      Remove expiration from the hash. Must be set to `true`. Cannot be used with other expiration options.
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="fields" type="...string[]" required>
+  One or more field names to get.
+</ParamField>
+
+## Response
+
+<ResponseField type="Record<string, TValue | null> | null" required>
+  An object containing the field names and their values in the format `{[fieldName: string]: TValue | null}`. Returns `null` for fields that do not exist. If the hash doesn't exist or all fields are non-existent, `null` is returned.
+</ResponseField>
+
+<RequestExample>
+```ts With EX (seconds)
+await redis.hset("user:123", { name: "John", email: "john@example.com" });
+
+// Get fields and set expiration to 60 seconds
+const result = await redis.hgetex("user:123", { ex: 60 }, "name", "email");
+console.log(result); // { name: "John", email: "john@example.com" }
+```
+
+```ts With PX (milliseconds)
+await redis.hset("session:abc", { token: "xyz123", user: "john" });
+
+// Get fields and set expiration to 30000 milliseconds (30 seconds)
+const result = await redis.hgetex("session:abc", { px: 30000 }, "token", "user");
+console.log(result); // { token: "xyz123", user: "john" }
+```
+
+```ts With EXAT (Unix timestamp in seconds)
+await redis.hset("cache:data", { value: "cached" });
+
+// Set expiration to specific timestamp (1 hour from now)
+const futureTime = Math.floor(Date.now() / 1000) + 3600;
+const result = await redis.hgetex("cache:data", { exat: futureTime }, "value");
+console.log(result); // { value: "cached" }
+```
+
+```ts With PXAT (Unix timestamp in milliseconds)
+await redis.hset("temp:data", { info: "temporary" });
+
+// Set expiration to specific timestamp in milliseconds
+const futureTime = Date.now() + 60000; // 1 minute from now
+const result = await redis.hgetex("temp:data", { pxat: futureTime }, "info");
+console.log(result); // { info: "temporary" }
+```
+
+```ts With PERSIST
+await redis.hset("user:456", { name: "Jane" });
+await redis.expire("user:456", 300); // Set 5 minute expiration
+
+// Get fields and remove expiration
+const result = await redis.hgetex("user:456", { persist: true }, "name");
+console.log(result); // { name: "Jane" }
+
+// Verify expiration was removed
+const ttl = await redis.ttl("user:456");
+console.log(ttl); // -1 (no expiration)
+```
+
+```ts Without Expiration Options
+await redis.hset("data:xyz", { field1: "value1", field2: "value2" });
+
+// Just get fields without changing expiration
+// Pass an empty object or an object with no expiration properties
+const result = await redis.hgetex("data:xyz", {}, "field1", "field2");
+console.log(result); // { field1: "value1", field2: "value2" }
+```
+
+```ts Non-existent Fields
+await redis.hset("user:789", { name: "Bob" });
+
+// Get fields including one that doesn't exist
+const result = await redis.hgetex("user:789", {}, "name", "email");
+console.log(result); // { name: "Bob", email: null }
+```
+</RequestExample>
+
+## Use Cases
+
+- **Session Management**: Retrieve session data and extend its lifetime
+- **Cache Refresh**: Get cached data and update its TTL
+- **Temporary Data**: Access temporary data while managing its expiration
+- **Rate Limiting**: Fetch rate limit data and reset expiration
+
+

package/docs/commands/hash/hincrby.mdx

@@ -0,0 +1,34 @@
+---
+title: HINCRBY
+description: Increments the value of a hash field by a given amount
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="field" type="string" required>
+  The field to increment
+</ParamField>
+
+<ParamField body="increment" type="integer" required>
+  How much to increment the field by. Can be negative to subtract.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+  The new value of the field after the increment.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  field: 20,
+  });
+const after = await redis.hincrby("key", "field", 2);
+console.log(after); // 22
+```
+</RequestExample>

package/docs/commands/hash/hincrbyfloat.mdx

@@ -0,0 +1,34 @@
+---
+title: HINCRBYFLOAT
+description: Increments the value of a hash field by a given float value.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="field" type="string" required>
+  The field to increment
+</ParamField>
+
+<ParamField body="increment" type="float" required>
+  How much to increment the field by. Can be negative to subtract.
+</ParamField>
+
+## Response
+
+<ResponseField type="float" required>
+  The new value of the field after the increment.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  field: 20,
+  });
+const after = await redis.hincrby("key", "field", 2.5);
+console.log(after); // 22.5
+```
+</RequestExample>

package/docs/commands/hash/hkeys.mdx

@@ -0,0 +1,28 @@
+---
+title: HKEYS
+description: Return all field names in the hash stored at key.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="string[]" required>
+  The field names of the hash
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  });
+const fields = await redis.hkeys("key");
+console.log(fields); // ["id", "username"]
+```
+</RequestExample>

package/docs/commands/hash/hlen.mdx

@@ -0,0 +1,28 @@
+---
+title: HLEN
+description: Returns the number of fields contained in the hash stored at key.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="integer" required>
+  How many fields are in the hash.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  });
+const fields = await redis.hlen("key");
+console.log(fields); // 2
+```
+</RequestExample>

package/docs/commands/hash/hmget.mdx

@@ -0,0 +1,33 @@
+---
+title: HMGET
+description: Return the requested fields and their values.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="fields" type="...string[]" required>
+  One or more fields to get.
+</ParamField>
+
+
+## Response
+
+<ResponseField type="Record<string, unknown>" required>
+ An object containing the fields and their values.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("key", {
+  id: 1,
+  username: "chronark",
+  name: "andreas"
+  });
+const fields = await redis.hmget("key", "username", "name");
+console.log(fields); // { username: "chronark", name: "andreas" }
+```
+</RequestExample>

package/docs/commands/hash/hpersist.mdx

@@ -0,0 +1,37 @@
+---
+title: HPERSIST
+description: Remove the expiration from one or more fields in a hash.
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the hash.
+</ParamField>
+
+<ParamField body="field" type="string | number | (string | number)[]" required>
+  The field or fields to remove the expiration from.
+</ParamField>
+
+## Response
+
+<ResponseField type="number[]" required>
+  A list of integers indicating the result 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 set.
+  - `1` if the expiration was successfully removed.
+
+  For more details, see [HPERSIST documentation](/redis/commands/hash/hpersist).
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.hset("my-key", "my-field", "my-value");
+await redis.hpexpire("my-key", "my-field", 1000);
+
+const expirationRemoved = await redis.hpersist("my-key", "my-field");
+
+console.log(expirationRemoved); // [1]
+```
+</RequestExample>