@upstash/redis 1.40.0 → 1.41.0

package/docs/getstarted.mdx

@@ -0,0 +1,68 @@
+---
+title: Redis TypeScript SDK Getting Started
+sidebarTitle: Get Started
+description: "Install @upstash/redis, connect to your Upstash Redis database over HTTP, and run your first commands from TypeScript or JavaScript."
+---
+
+<Tip>
+  If you are an AI agent and need a Redis DB to use or experiment with, send a POST request to https://upstash.com/start-redis. Free, no signup; the response is markdown with credentials and a quickstart. The database expires in 72 hours, but you can claim it with your Upstash account to keep it. Especially useful for AI agents that need scratch storage on the fly. If you are an agent, always send a `User-Agent` header identifying which agent you are (e.g. `claude-code`, `cursor`, `codex`, `opencode`) on every request you make to this API.
+</Tip>
+
+
+Install `@upstash/redis` from npm:
+
+```bash
+npm install @upstash/redis
+```
+
+```bash
+yarn add @upstash/redis
+```
+
+```bash
+pnpm add @upstash/redis
+```
+
+In Deno, import it straight from npm with no install step:
+
+```ts
+import { Redis } from "npm:@upstash/redis";
+```
+
+## Basic Usage:
+
+```ts
+import { Redis } from "@upstash/redis"
+
+const redis = new Redis({
+  url: <UPSTASH_REDIS_REST_URL>,
+  token: <UPSTASH_REDIS_REST_TOKEN>,
+})
+
+// string
+await redis.set('key', 'value');
+let data = await redis.get('key');
+console.log(data)
+
+await redis.set('key2', 'value2', {ex: 1});
+
+// sorted set
+await redis.zadd('scores', { score: 1, member: 'team1' })
+data = await redis.zrange('scores', 0, 100 )
+console.log(data)
+
+// list
+await redis.lpush('elements', 'magnesium')
+data = await redis.lrange('elements', 0, 100 )
+console.log(data)
+
+// hash
+await redis.hset('people', {name: 'joe'})
+data = await redis.hget('people', 'name' )
+console.log(data)
+
+// sets
+await redis.sadd('animals', 'cat')
+data  = await redis.spop('animals', 1)
+console.log(data)
+```

package/docs/overview.mdx

@@ -0,0 +1,29 @@
+---
+title: Redis TypeScript SDK Overview
+sidebarTitle: Overview
+---
+
+[@upstash/redis](https://github.com/upstash/redis-js)
+is an HTTP/REST based Redis client built on top of
+[Upstash REST API](/redis/features/restapi).
+
+[![Tests](https://github.com/upstash/redis-js/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/redis-js/actions/workflows/tests.yaml)
+![npm (scoped)](https://img.shields.io/npm/v/@upstash/redis)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/@upstash/redis)
+
+It is the only connectionless (HTTP based) Redis client and designed for:
+
+- Serverless functions (AWS Lambda)
+- Cloudflare Workers (see
+  [the example](https://github.com/upstash/redis-js/tree/main/examples/cloudflare-workers))
+- Fastly Compute@Edge (see
+  [the example](https://github.com/upstash/redis-js/tree/main/examples/fastly))
+- Next.js (see [the quickstart](/redis/quickstarts/nextjs-app-router)), Jamstack
+- Client side web/mobile applications
+- WebAssembly
+- and other environments where HTTP is preferred over TCP.
+
+See
+[the list of APIs](/redis/features/restapi#rest-redis-api-compatibility)
+supported by the Upstash REST API. For typed `@upstash/redis` command helpers,
+see the [TypeScript SDK command reference](/redis/sdks/ts/commands/overview).

package/docs/pipelining/auto-pipeline.mdx

@@ -0,0 +1,108 @@
+---
+title: Auto-Pipelining
+---
+
+### Auto Pipelining
+
+Auto pipelining allows you to use the Redis client as usual
+while in the background it tries to send requests in batches
+whenever possible.
+
+In a nutshell, the client will accumulate commands in a pipeline
+and wait for a short amount of time for more commands to arrive.
+When there are no more commands, it will execute them as a batch.
+
+This feature is enabled by default. To disable it, simply pass `enableAutoPipelining: false`
+when creating the Redis client:
+
+<CodeGroup>
+
+```ts Redis
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv({
+  enableAutoPipelining: false
+});
+```
+
+```ts fromEnv
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({
+  url: <UPSTASH_REDIS_REST_URL>,
+  token: <UPSTASH_REDIS_REST_TOKEN>,
+  enableAutoPipelining: true
+})
+```
+</CodeGroup>
+
+This is especially useful in cases when we want to make async
+requests or when we want to make requests in batches.
+
+```ts
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv({
+  latencyLogging: false,
+  enableAutoPipelining: true
+});
+
+// async call to redis. Not executed right away, instead
+// added to the pipeline
+redis.hincrby("Brooklyn", "visited", 1);
+
+// making requests in batches
+const brooklynInfo = Promise.all([
+  redis.hget("Brooklyn", "coordinates"),
+  redis.hget("Brooklyn", "population")
+]);
+
+// when we call await, the three commands are executed
+// as a pipeline automatically. A single PIPELINE command
+// is executed instead of three requests and the results
+// are returned:
+const [ coordinates, population ] = await brooklynInfo;
+```
+
+The benefit of auto pipelining is that it reduces the number
+of HTTP requests made like pipelining and transaction while
+being extremely simple to enable and use. It's especially
+useful in cases like Vercel Edge and [Cloudflare Workers, where the number of
+simultaneous requests is limited by 6](https://developers.cloudflare.com/workers/platform/limits/#account-plan-limits).
+
+To learn more about how auto pipelining can be utilized in a
+project, see
+[the auto-pipeline example project under `upstash-redis` repository](https://github.com/upstash/upstash-redis/tree/main/examples/auto-pipeline)
+
+### How it Works
+
+For auto pipeline to work, the client keeps an active pipeline
+and adds incoming commands to this pipeline. After the command
+is added to the pipeline, execution of the pipeline is delayed
+by releasing the control of the Node thread.
+
+The pipeline executes when one of these two conditions are met:
+No more commands are being added or at least one of the commands
+added is being 'awaited'.
+
+This means that if you are awaiting every time you run a command,
+you won't benefit much from auto pipelining since each await will
+trigger a pipeline:
+
+```ts
+const foo = await redis.get("foo") // makes a PIPELINE call
+const bar = await redis.get("bar") // makes another PIPELINE call
+```
+
+In these cases, we suggest using `Promise.all`:
+
+```ts
+// makes a single PIPELINE call:
+const [ foo, bar ] = await Promise.all([
+  redis.get("foo"),
+  redis.get("bar")
+])
+```
+
+In addition to resulting in a single PIPELINE call, the commands
+in `Promise.all` are executed in the order they are written!

package/docs/pipelining/pipeline-transaction.mdx

@@ -0,0 +1,65 @@
+---
+title: Pipeline & Transaction
+---
+
+### Pipeline
+
+Pipelining commands allows you to send a single http request with multiple
+commands. Keep in mind, that the execution of pipelines is not atomic and the
+execution of other commands can interleave.
+
+```ts
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({
+  /* auth */
+});
+
+const p = redis.pipeline();
+
+// Now you can chain multiple commands to create your pipeline:
+
+p.set("key", 2);
+p.incr("key");
+
+// or inline:
+p.hset("key2", "field", { hello: "world" }).hvals("key2");
+
+// Execute the pipeline once you are done building it:
+// `exec` returns an array where each element represents the response of a command in the pipeline.
+// You can optionally provide a type like this to get a typed response.
+const res = await p.exec<[Type1, Type2, Type3]>();
+```
+
+For more information about pipelines using REST see
+[here](https://blog.upstash.com/pipeline).
+
+If you wish to benefit from pipeline automatically,
+you can simply enable auto-pipelining to make your redis client
+handle the commands in batches in the background. See
+[the Auto-pipelining page](https://docs.upstash.com/redis/sdks/ts/pipelining/auto-pipeline).
+
+### Transaction
+
+Remember that the pipeline is able to send multiple commands at once but
+can't execute them atomically. With transactions, you can make the commands
+execute atomically.
+
+```ts
+import { Redis } from "@upstash/redis";
+
+const redis = new Redis({
+  /* auth */
+});
+
+const p = redis.multi();
+
+p.set("key", 2);
+p.incr("key");
+
+// or inline:
+p.hset("key2", "field", { hello: "world" }).hvals("key2");
+
+// execute the transaction
+const res = await p.exec<[Type1, Type2, Type3]>();
+```

package/docs/retries.mdx

@@ -0,0 +1,24 @@
+---
+title: Redis TypeScript SDK Retries
+sidebarTitle: Retries
+---
+
+By default `@upstash/redis` will retry sending you request when network errors
+occur. It will retry 5 times with a backoff of
+`(retryCount) => Math.exp(retryCount) * 50` milliseconds.
+
+You can customize this in the `Redis` constructor:
+
+```ts
+new Redis({
+  url: UPSTASH_REDIS_REST_URL,
+  token: UPSTASH_REDIS_REST_TOKEN,
+  retry: {
+    retries: 5,
+    backoff: (retryCount) => Math.exp(retryCount) * 50,
+  },
+});
+```
+
+The exact type definition can be found
+[here](https://github.com/upstash/upstash-redis/blob/4948b049e0d580d1de0a4cbfeac5565d7e035cc4/pkg/http.ts#LL31C1-L49C5).

package/docs/troubleshooting.mdx

@@ -0,0 +1,80 @@
+---
+title: Redis TypeScript SDK Troubleshooting
+sidebarTitle: Troubleshooting
+---
+
+## ReferenceError: fetch is not defined
+
+#### Problem
+
+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 add a polyfill.
+
+#### Solution
+
+```bash
+npm i isomorphic-fetch
+```
+
+```ts
+import { Redis } from "@upstash/redis";
+import "isomorphic-fetch";
+
+const redis = new Redis({
+  /*...*/
+});
+```
+
+## Hashed Response
+
+The response from a server is not what you expect but looks like a hash?
+
+```ts
+await redis.set("key", "value");
+const data = await redis.get("key");
+console.log(data);
+
+// dmFsdWU=
+```
+
+#### Problem
+
+Versions of `@upstash/redis` before 1.40.0 request base64 encoded responses from
+the server by default. If a response reaches your code without being decoded,
+you see the base64 encoded value.
+
+#### Solution
+
+Upgrade to `@upstash/redis` 1.40.0 or later, which requests plain responses by
+default, or set `responseEncoding` to `false` in the options.
+
+```ts
+const redis = new Redis({
+  // ...
+  responseEncoding: false,
+});
+```
+
+## Large numbers are returned as string
+
+You are trying to load a large number and it is returned as a string instead.
+
+```ts
+await redis.set("key", "101600000000150081467");
+const res = await redis("get");
+
+// "101600000000150081467"
+```
+
+#### Problem
+
+Javascript can not handle numbers larger than `2^53 -1` safely and would return
+wrong results when trying to deserialize them. In these cases the default
+deserializer will return them as string instead. This might cause a mismatch
+with your custom types.
+
+#### Solution
+
+Please be aware that this is a limitation of javascript and take special care
+when handling large numbers.