@upstash/redis 0.0.0-ci.f55d85c5 → 0.0.0-ci.f6da5d747c9564bc95fccdbfe16a9aa10cd30367-20251125191507

package/README.md

@@ -7,45 +7,32 @@ of [Upstash REST API](https://docs.upstash.com/features/restapi).
 ![npm (scoped)](https://img.shields.io/npm/v/@upstash/redis)
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@upstash/redis)
 
+> [!NOTE]  
+> **This project is in GA Stage.**
+>
+> The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes. The Upstash team is committed to maintaining and improving its functionality.
+
 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/upstash-redis/tree/master/examples/cloudflare-workers))
+  [the example](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers))
 - Fastly Compute@Edge (see
-  [the example](https://github.com/upstash/upstash-redis/tree/master/examples/fastly))
+  [the example](https://github.com/upstash/upstash-redis/tree/main/examples/fastly))
 - Next.js, Jamstack ...
 - Client side web/mobile applications
 - WebAssembly
 - and other environments where HTTP is preferred over TCP.
 
 See
-[the list of APIs](https://docs.upstash.com/features/restapi#rest---redis-api-compatibility)
+[the list of APIs](https://upstash.com/docs/redis/overall/rediscompatibility)
 supported.
 
-## Upgrading to v1.4.0 **(ReferenceError: fetch is not defined)**
-
-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 to:
-
-```typescript
-import { Redis } from "@upstash/redis/with-fetch";
-```
-
-## Upgrading from v0.2.0?
-
-Please read the
-[migration guide](https://github.com/upstash/upstash-redis#migrating-to-v1). For
-further explanation we wrote a
-[blog post](https://blog.upstash.com/upstash-redis-sdk-v1).
-
 ## Quick Start
 
 ### Install
 
-#### npm
+#### Node.js
 
 ```bash
 npm install @upstash/redis
@@ -54,26 +41,14 @@ npm install @upstash/redis
 #### Deno
 
 ```ts
-import { Redis } from "https://deno.land/x/upstash_redis/mod.ts";
+import { Redis } from "https://esm.sh/@upstash/redis";
 ```
 
 ### Create database
 
 Create a new redis database on [upstash](https://console.upstash.com/)
 
-### Environments
-
-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
-
-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:
+## Basic Usage:
 
 ```ts
 import { Redis } from "@upstash/redis"
@@ -83,279 +58,88 @@ const redis = new Redis({
   token: <UPSTASH_REDIS_REST_TOKEN>,
 })
 
-// or load directly from env
-const redis = Redis.fromEnv()
-```
-
-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 to:
+// string
+await redis.set('key', 'value');
+let data = await redis.get('key');
+console.log(data)
 
-```typescript
-import { Redis } from "@upstash/redis/with-fetch";
-```
+await redis.set('key3', 'value3', {ex: 1});
 
-- [Code example](https://github.com/upstash/upstash-redis/blob/main/examples/nodejs)
+// sorted set
+await redis.zadd('scores', { score: 1, member: 'team1' })
+data = await redis.zrange('scores', 0, 100 )
+console.log(data)
 
-#### Cloudflare Workers
+// list
+await redis.lpush('elements', 'magnesium')
+data = await redis.lrange('elements', 0, 100 )
+console.log(data)
 
-Cloudflare handles environment variables differently than nodejs. Please add
-`UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` using
-`wrangler secret put ...` or in the cloudflare dashboard.
+// hash
+await redis.hset('people', {name: 'joe'})
+data = await redis.hget('people', 'name' )
+console.log(data)
 
-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)
-    // ...
-  }
-}
+// sets
+await redis.sadd('animals', 'cat')
+data  = await redis.spop('animals', 1)
+console.log(data)
 ```
 
-- [Code example service worker](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers)
-- [Code example module worker](https://github.com/upstash/upstash-redis/tree/main/examples/cloudflare-workers-modules)
-- [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>,
-})
-```
+## Troubleshooting
 
-- [Code example](https://github.com/upstash/upstash-redis/tree/main/examples/fastly)
-- [Documentation](https://blog.upstash.com/fastly-compute-edge-with-redi)
+We have a
+[dedicated page](https://docs.upstash.com/redis/sdks/javascriptsdk/troubleshooting)
+for common problems. If you can't find a solution, please
+[open an issue](https://github.com/upstash/upstash-redis/issues/new).
 
-#### Deno
+## Docs
 
-Examples: [Deno Deploy](https://deno.com/deploy),
-[Netlify Edge](https://www.netlify.com/products/edge/)
+See [the documentation](https://upstash.com/docs/redis/sdks/ts/overview) for
+details.
 
-```ts
-import { Redis } from "https://deno.land/x/upstash_redis/mod.ts"
+## Contributing
 
-const redis = new Redis({
-  url: <UPSTASH_REDIS_REST_URL>,
-  token: <UPSTASH_REDIS_REST_TOKEN>,
-})
+### [Install Bun](https://bun.sh/docs/installation)
 
-// or
-const redis = Redis.fromEnv();
-```
+### Database
 
-### Working with types
+Create a new redis database on [upstash](https://console.upstash.com/) and copy
+the url and token
 
-Most commands allow you to provide a type to make working with typescript
-easier.
+### Running tests
 
-```ts
-const data = await redis.get<MyCustomType>("key");
-// data is typed as `MyCustomType`
+```sh
+bun run test
 ```
 
-## Migrating to v1
-
-### Explicit authentication
+### Building
 
-The library is no longer automatically trying to load connection secrets from
-environment variables. You must either supply them yourself:
-
-```ts
-import { Redis } from "@upstash/redis"
-
-const redis = new Redis({
-  url: <UPSTASH_REDIS_REST_URL>,
-  token: <UPSTASH_REDIS_REST_TOKEN>,
-})
+```sh
+bun run build
 ```
 
-Or use one of the static constructors to load from environment variables:
-
-```ts
-// Nodejs
-import { Redis } from "@upstash/redis";
-const redis = Redis.fromEnv();
-```
+### Telemetry
 
-```ts
-// or when deploying to cloudflare workers
-import { Redis } from "@upstash/redis/cloudflare";
-const redis = Redis.fromEnv();
-```
+This library sends anonymous telemetry data to help us improve your experience.
+We collect the following:
 
-### Error handling
+- SDK version
+- Platform (Deno, Cloudflare, Vercel)
+- Runtime version (node@18.x)
 
-Errors are now thrown automatically instead of being returned to you.
+You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
+to any truthy value.
 
-```ts
-// old
-const { data, error } = await set("key", "value");
-if (error) {
-  throw new Error(error);
-}
-
-// new
-const data = await redis.set("key", "value"); // error is thrown automatically
+```sh
+UPSTASH_DISABLE_TELEMETRY=1
 ```
 
-## Pipeline
-
-`v1.0.0` introduces redis pipelines. Pipelining commands allows you to send a
-single http request with multiple commands.
+Alternatively, you can pass `enableTelemetry: false` when initializing the Redis client:
 
 ```ts
-import { Redis } from "@upstash/redis";
-
 const redis = new Redis({
-  /* auth */
+  // ...,
+  enableTelemetry: false,
 });
-
-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).
-
-### Advanced
-
-A low level `Command` class can be imported from `@upstash/redis` in case you
-need more control about types and or (de)serialization.
-
-By default all objects you are storing in redis are serialized using
-`JSON.stringify` and recursively deserialized as well. Here's an example how you
-could customize that behaviour. Keep in mind that you need to provide a `fetch`
-polyfill if you are running on nodejs. We recommend
-[isomorphic-fetch](https://www.npmjs.com/package/isomorphic-fetch).
-
-```ts
-import { Command } from "@upstash/redis/commands"
-import { HttpClient } from "@upstash/redis/http"
-
-/**
- * TData represents what the user will enter or receive,
- * TResult is the raw data returned from upstash, which may need to be
- * transformed or parsed.
- */
-const deserialize: (raw: TResult) => TData = ...
-
-class CustomGetCommand<TData, TResult> extends Command<TData | null, TResult | null> {
-  constructor(key: string, ) {
-    super(["get", key], { deserialize })
-  }
-}
-
-const client = new HttpClient({
-  baseUrl: <UPSTASH_REDIS_REST_URL>,
-  headers: {
-    authorization: `Bearer ${<UPSTASH_REDIS_REST_TOKEN>}`,
-  },
-})
-
-const res = new CustomGetCommand("key").exec(client)
-```
-
-### Additional information
-
-#### `keepalive`
-
-`@upstash/redis` is capable of reusing connections where possible to minimize
-latency. Connections can be reused if the client is stored in memory and not
-initialized with every new function invocation. The easiest way to achieve this
-is by creating the client outside of your handler and adding an https agent:
-
-```ts
-// Nextjs api route
-import { Redis } from "@upstash/redis";
-import https from "https";
-
-const redis = Redis.fromEnv({
-  agent: new https.Agent({ keepAlive: true }),
-});
-
-export default async function (req, res) {
-  // use redis here
-}
-```
-
-Whenever your hot lambda receives a new request the client is already
-initialized and the previously established connection to upstash is reused.
-
-#### Javascript MAX_SAFE_INTEGER
-
-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.
-
-```ts
-await redis.set("key", "101600000000150081467");
-const res = await redis<number>("get");
-```
-
-In this example `res` will still be a string despite the type annotation. Please
-keep that in mind and adjust accordingly.
-
-## Docs
-
-See [the documentation](https://docs.upstash.com/features/javascriptsdk) for
-details.
-
-## Contributing
-
-### [Install Deno](https://deno.land/#installation)
-
-### Database
-
-Create a new redis database on [upstash](https://console.upstash.com/) and copy
-the url and token
-
-### Running tests
-
-```sh
-UPSTASH_REDIS_REST_URL=".." UPSTASH_REDIS_REST_TOKEN=".." deno test -A
-```
-
-```
 ```