@upstash/redis 1.40.0 → 1.41.0

package/docs/commands/zset/zrange.mdx

@@ -0,0 +1,85 @@
+---
+title: ZRANGE
+description: Returns the specified range of elements in the sorted set stored at key.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+
+<ParamField body="min" type="number | string" required>
+  The lower bound of the range.
+</ParamField>
+
+
+<ParamField body="max" type="number | string" required>
+  The upper bound of the range.
+</ParamField>
+
+
+<ParamField body="options"  >
+<Expandable>
+  <ParamField body="withScores" type="boolean">
+    Whether to include the scores in the response.
+  </ParamField>
+  <ParamField body="rev" type="boolean">
+    Whether to reverse the order of the response.
+    </ParamField>
+    <ParamField body="byScore" type="boolean">
+    Whether to use the score as the sort order.
+    </ParamField>
+    <ParamField body="byLex" type="boolean">
+    Whether to use lexicographical ordering.
+    </ParamField>
+    <ParamField body="offset" type="number">
+    The offset to start from.
+    </ParamField>
+    <ParamField body="count" type="number">
+    The number of elements to return.
+    </ParamField>
+    </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField type="TMember[]">
+    The values in the specified range.
+
+    If `withScores` is true, the response will have interleaved members and scores: `[TMember, number, TMember, number, ...]`
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+await redis.zadd("key", 
+    { score: 1, member: "m1" },
+    { score: 2, member: "m2" },
+)
+const res = await redis.zrange("key", 1, 3)
+console.log(res) // ["m2"]
+```
+
+```ts WithScores
+await redis.zadd("key", 
+    { score: 1, member: "m1" },
+    { score: 2, member: "m2" },
+)
+const res = await redis.zrange("key", 1, 3, { withScores: true })
+console.log(res) // ["m2", 2]
+```
+
+```ts ByScore
+await redis.zadd("key", 
+    { score: 1, member: "m1" },
+    { score: 2, member: "m2" },
+    { score: 3, member: "m3" },
+)
+const res = await redis.zrange("key", 1, 2, { byScore: true })
+console.log(res) // ["m1", "m2"]
+```
+</RequestExample>

package/docs/commands/zset/zrank.mdx

@@ -0,0 +1,29 @@
+---
+title: ZRANK
+description: Returns the rank of a member
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="member" type="TMember" required>
+  The member to get the rank of.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+    The rank of the member.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+const rank = await redis.rank("key", "member");
+```
+</RequestExample>

package/docs/commands/zset/zrem.mdx

@@ -0,0 +1,33 @@
+---
+title: ZREM
+description: Remove one or more members from a sorted set
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key of the sorted set
+</ParamField>
+
+
+<ParamField body="members" type="...TMember[]" required>
+  One or more members to remove
+</ParamField>
+## Response
+
+<ResponseField  required>
+    The number of members removed from the sorted set.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Single
+await redis.zrem("key", "member");
+```
+
+```ts Multiple
+await redis.zrem("key", "member1", "member2");
+```
+</RequestExample>

package/docs/commands/zset/zremrangebylex.mdx

@@ -0,0 +1,32 @@
+---
+title: ZREMRANGEBYLEX
+description: Remove all members in a sorted set between the given lexicographical range.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key of the sorted set
+</ParamField>
+
+<ParamField body="min" type="string" required>
+    The minimum lexicographical value to remove.
+</ParamField>
+<ParamField body="max" type="string" required>
+    The maximum lexicographical value to remove.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer"  required>
+    The number of elements removed from the sorted set.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+await redis.zremrangebylex("key", "alpha", "omega")
+```
+</RequestExample>

package/docs/commands/zset/zremrangebyrank.mdx

@@ -0,0 +1,32 @@
+---
+title: ZREMRANGEBYRANK
+description: Remove all members in a sorted set between the given ranks.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key of the sorted set
+</ParamField>
+
+<ParamField body="min" type="number" required>
+    The minimum rank to remove.
+</ParamField>
+<ParamField body="max" type="number" required>
+    The maximum rank to remove.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer"  required>
+    The number of elements removed from the sorted set.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+await redis.zremrangebyrank("key", 4, 20)
+```
+</RequestExample>

package/docs/commands/zset/zremrangebyscore.mdx

@@ -0,0 +1,32 @@
+---
+title: ZREMRANGEBYSCORE
+description: Remove all members in a sorted set between the given scores.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key of the sorted set
+</ParamField>
+
+<ParamField body="min" type="number" required>
+    The minimum score to remove.
+</ParamField>
+<ParamField body="max" type="number" required>
+    The maximum score to remove.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer"  required>
+    The number of elements removed from the sorted set.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+await redis.zremrangebyscore("key", 2, 5)
+```
+</RequestExample>

package/docs/commands/zset/zrevrank.mdx

@@ -0,0 +1,29 @@
+---
+title: ZREVRANK
+description: Returns the rank of a member in a sorted set, with scores ordered from high to low.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+<ParamField body="member" type="TMember" required>
+  The member to get the reverse rank of.
+</ParamField>
+
+## Response
+
+<ResponseField type="integer" required>
+    The reverse rank of the member.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+const rank = await redis.rank("key", "member");
+```
+</RequestExample>

package/docs/commands/zset/zscan.mdx

@@ -0,0 +1,58 @@
+---
+title: ZSCAN
+description: Scan a sorted set
+---
+
+## Arguments
+
+<ParamField body="key" type="string" required>
+  The key of the sorted set.
+</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 members.
+  </ParamField>
+  <ParamField body="count" type="number">
+    Number of members to return per call.
+  </ParamField>
+</ParamField>
+
+## Response
+
+<ResponseField type="[number, TMember[]]" required>
+  The new cursor and the members.
+  If the new cursor is `0` the iteration is complete.
+</ResponseField>
+
+<RequestExample>
+```ts Example
+await redis.zadd("key", 
+    { score: 1, member: "a" },
+    { score: 2, member: "ab" },
+    { score: 3, member: "b" },
+    { score: 4, member: "c" },
+    { score: 5, member: "d" },
+)
+const [newCursor, members] = await redis.zscan("key", 0, { match: "a*"});
+console.log(newCursor); // likely `0` since this is a very small set
+console.log(members); // ["a", "ab"]
+```
+
+```ts withCount
+await redis.zadd("key", 
+    { score: 1, member: "a" },
+    { score: 2, member: "ab" },
+    { score: 3, member: "b" },
+    { score: 4, member: "c" },
+    { score: 5, member: "d" },
+)
+const [newCursor, members] = await redis.zscan("key", 0, { match: "a*", count: 1});
+console.log(newCursor); // likely `0` since this is a very small set
+console.log(members); // ["a"]
+```
+</RequestExample>

package/docs/commands/zset/zscore.mdx

@@ -0,0 +1,34 @@
+---
+title: ZSCORE
+description: Returns the scores of a member.
+---
+
+
+## Arguments 
+
+<ParamField body="key" type="string" required>
+  The key to get.
+</ParamField>
+
+## Response
+
+<ResponseField body="member" type="TMember" required>
+    A member of the sortedset.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Example
+
+await redis.zadd("key", 
+    { score: 1, member: "m1" },
+    { score: 2, member: "m2" },
+    { score: 3, member: "m3" },
+    { score: 4, member: "m4" },
+)
+
+const score = await redis.zscore("key", "m2")
+console.log(score) // 2
+```
+</RequestExample>

package/docs/commands/zset/zunionstore.mdx

@@ -0,0 +1,98 @@
+---
+title: ZUNIONSTORE
+description: Writes the union between sets to a new key.
+---
+
+
+## Arguments 
+
+<ParamField body="destination" type="string" required>
+  The key to write the union to.
+</ParamField>
+
+<ParamField body="keys" type="integer" required>
+  How many keys to compare.
+</ParamField>
+
+<ParamField body="keys" type="string | string[]" required>
+  The keys to compare.
+</ParamField>
+
+<ParamField body="options">
+    <ParamField body="aggregate" type="sum | min | max">
+        The aggregation method.
+    </ParamField>
+
+    <ParamField body="weight" type="number">
+        The weight to apply to each key.
+    </ParamField>
+    
+    <ParamField body="weights" type="number[]">
+        The weights to apply to each key.
+    </ParamField>
+    
+</ParamField>
+
+## Response
+
+<ResponseField  required>
+    The number of elements in the resulting set.
+</ResponseField>
+
+
+
+<RequestExample>
+```ts Simple
+await redis.zadd(
+    "key1", 
+    { score: 1, member: "member1" },
+)
+await redis.zadd(
+    "key2",
+    { score: 1, member: "member1" },
+    { score: 2, member: "member2" },
+)
+
+const res = await redis.zunionstore("destination", 2, ["key1", "key2"]);
+console.log(res) // 2
+```
+
+```ts With Weights
+await redis.zadd(
+    "key1", 
+    { score: 1, member: "member1" },
+)
+await redis.zadd(
+    "key2",
+    { score: 1, member: "member1" },
+    { score: 2, member: "member2" },
+)
+const res = await redis.zunionstore(
+    "destination",
+    2,
+    ["key1", "key2"],
+    { weights: [2, 3] },
+);
+console.log(res) // 2
+```
+
+
+```ts Aggregate
+await redis.zadd(
+    "key1", 
+    { score: 1, member: "member1" },
+)
+await redis.zadd(
+    "key2",
+    { score: 1, member: "member1" },
+    { score: 2, member: "member2" },
+)
+const res = await redis.zunionstore(
+    "destination",
+    2,
+    ["key1", "key2"],
+    { aggregate: "sum" },
+);
+console.log(res) // 2
+```
+</RequestExample>

package/docs/deployment.mdx

@@ -0,0 +1,117 @@
+---
+title: Redis TypeScript SDK Deployment
+sidebarTitle: Deployment
+---
+
+We support various platforms, such as nodejs, cloudflare and fastly. Platforms
+differ slightly when it comes to environment variables and their `fetch` api.
+Please use the correct import when deploying to special platforms.
+
+## Node.js / Browser
+
+Examples: Vercel, Netlify, AWS Lambda
+
+If you are running on nodejs you can set `UPSTASH_REDIS_REST_URL` and
+`UPSTASH_REDIS_REST_TOKEN` as environment variable and create a redis instance
+like this:
+
+```ts
+import { Redis } from "@upstash/redis"
+
+const redis = new Redis({
+  url: <UPSTASH_REDIS_REST_URL>,
+  token: <UPSTASH_REDIS_REST_TOKEN>,
+})
+
+// or load directly from env
+const redis = Redis.fromEnv()
+```
+
+<Info>
+If you are running on nodejs v17 and earlier, `fetch` will not be natively
+supported. Platforms like Vercel, Netlify, Deno, Fastly etc. provide a polyfill
+for you. But if you are running on bare node, you need to either specify a
+polyfill yourself or change the import path slightly:
+
+```typescript
+import { Redis } from "@upstash/redis/with-fetch";
+```
+
+</Info>
+
+- [Code example](https://github.com/upstash/upstash-redis/blob/main/examples/nodejs)
+
+## Cloudflare Workers
+
+Cloudflare handles environment variables differently than Node.js. Please add
+`UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` using
+`wrangler secret put ...` or in the cloudflare dashboard.
+
+Afterwards you can create a redis instance:
+
+```ts
+import { Redis } from "@upstash/redis/cloudflare"
+
+const redis = new Redis({
+  url: <UPSTASH_REDIS_REST_URL>,
+  token: <UPSTASH_REDIS_REST_TOKEN>,
+})
+
+
+// or load directly from global env
+
+// service worker
+const redis = Redis.fromEnv()
+
+
+// module worker
+export default {
+  async fetch(request: Request, env: Bindings) {
+    const redis = Redis.fromEnv(env)
+    // ...
+  }
+}
+```
+
+- [Code example](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers)
+- [Code example typescript](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-typescript)
+- [Code example Wrangler 1](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-with-wrangler-1)
+- [Documentation](https://docs.upstash.com/redis/tutorials/cloudflare_workers_with_redis)
+
+## Fastly
+
+Fastly introduces a concept called
+[backend](https://developer.fastly.com/reference/api/services/backend/). You
+need to configure a backend in your `fastly.toml`. An example can be found
+[here](https://github.com/upstash/upstash-redis/blob/main/examples/fastly/fastly.toml).
+Until the fastly api stabilizes we recommend creating an instance manually:
+
+```ts
+import { Redis } from "@upstash/redis/fastly"
+
+const redis = new Redis({
+  url: <UPSTASH_REDIS_REST_URL>,
+  token: <UPSTASH_REDIS_REST_TOKEN>,
+  backend: <BACKEND_NAME>,
+})
+```
+
+- [Code example](https://github.com/upstash/upstash-redis/tree/main/examples/fastly)
+- [Documentation](https://blog.upstash.com/fastly-compute-edge-with-redis)
+
+## Deno
+
+Examples: [Deno Deploy](https://deno.com/deploy),
+[Netlify Edge](https://www.netlify.com/products/edge/)
+
+```ts
+import { Redis } from "npm:@upstash/redis"
+
+const redis = new Redis({
+  url: <UPSTASH_REDIS_REST_URL>,
+  token: <UPSTASH_REDIS_REST_TOKEN>,
+})
+
+// or
+const redis = Redis.fromEnv();
+```

package/docs/developing.mdx

@@ -0,0 +1,118 @@
+---
+title: Developing or Testing
+---
+
+When developing or testing your application, you might not want or can not use
+Upstash over the internet. In this case, you can use a community project called
+[Serverless Redis HTTP (SRH)](https://github.com/hiett/serverless-redis-http)
+created by [Scott Hiett](https://x.com/hiettdigital).
+
+SRH is a Redis proxy and connection pooler that uses HTTP rather than the Redis
+binary protocol. The aim of this project is to be entirely compatible with
+Upstash, and work with any Upstash supported Redis version.
+
+We are working with Scott together to keep SRH up to date with the latest
+Upstash features.
+
+## Use cases for SRH:
+
+- For usage in your CI pipelines, creating Upstash databases is tedious, or you
+  have lots of parallel runs.
+  - See [Using in GitHub Actions](#in-github-actions) on how to quickly get SRH
+    setup for this context.
+- For usage inside of Kubernetes, or any network whereby the Redis server is not
+  exposed to the internet.
+  - See [Using in Docker Compose](#via-docker-compose) for the various setup
+    options directly using the Docker Container.
+- For local development environments, where you have a local Redis server
+  running, or require offline access.
+  - See [Using the Docker Command](#via-docker-command), or
+    [Using Docker Compose](#via-docker-compose).
+
+## Setting up SRH
+
+### Via Docker command
+
+If you have a locally running Redis server, you can simply start an SRH
+container that connects to it. In this example, SRH will be running on port
+`8080`.
+
+```bash
+docker run \
+    -it -d -p 8080:80 --name srh \
+    -e SRH_MODE=env \
+    -e SRH_TOKEN=your_token_here \
+    -e SRH_CONNECTION_STRING="redis://your_server_here:6379" \
+    hiett/serverless-redis-http:latest
+```
+
+### Via Docker Compose
+
+If you wish to run in Kubernetes, this should contain all the basics would need
+to set that up. However, be sure to read the Configuration Options, because you
+can create a setup whereby multiple Redis servers are proxied.
+
+```yml
+version: "3"
+services:
+  redis:
+    image: redis
+    ports:
+      - "6379:6379"
+  serverless-redis-http:
+    ports:
+      - "8079:80"
+    image: hiett/serverless-redis-http:latest
+    environment:
+      SRH_MODE: env
+      SRH_TOKEN: example_token
+      SRH_CONNECTION_STRING: "redis://redis:6379" # Using `redis` hostname since they're in the same Docker network.
+```
+
+### In GitHub Actions
+
+SRH works nicely in GitHub Actions because you can run it as a container in a
+job's services. Simply start a Redis server, and then SRH alongside it. You
+don't need to worry about a race condition of the Redis instance not being
+ready, because SRH doesn't create a Redis connection until the first command
+comes in.
+
+```yml
+name: Test @upstash/redis compatibility
+on:
+  push:
+  workflow_dispatch:
+
+env:
+  SRH_TOKEN: example_token
+
+jobs:
+  container-job:
+    runs-on: ubuntu-latest
+    container: denoland/deno
+    services:
+      redis:
+        image: redis/redis-stack-server:6.2.6-v6 # 6.2 is the Upstash compatible Redis version
+      srh:
+        image: hiett/serverless-redis-http:latest
+        env:
+          SRH_MODE: env # We are using env mode because we are only connecting to one server.
+          SRH_TOKEN: ${{ env.SRH_TOKEN }}
+          SRH_CONNECTION_STRING: redis://redis:6379
+
+    steps:
+      # You can place your normal testing steps here. In this example, we are running SRH against the upstash/upstash-redis test suite.
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          repository: upstash/upstash-redis
+
+      - name: Run @upstash/redis Test Suite
+        run: deno test -A ./pkg
+        env:
+          UPSTASH_REDIS_REST_URL: http://srh:80
+          UPSTASH_REDIS_REST_TOKEN: ${{ env.SRH_TOKEN }}
+```
+
+A huge thanks goes out to [Scott](https://hiett.dev/) for creating this project,
+and for his continued efforts to keep it up to date with Upstash.