@upstash/redis

@upstash/redis is the official TypeScript client for Upstash’s HTTP REST API in front of Redis. Instead of holding a persistent TCP connection like traditional Redis drivers, every command is sent as a single HTTPS request, which makes it a natural fit for AWS Lambda, Cloudflare Workers, Fastly Compute@Edge, Vercel Functions, and other short-lived or connectionless execution environments.

The client covers the full Redis command surface — strings, hashes, lists, sets, sorted sets, geo, bitmaps, RedisJSON, and Redis Functions/scripts — with typed method signatures, plus pipelining, transactions, retries, and optional read-your-writes consistency.

What You Get

• A Redis client class with 200+ typed command methods covering strings, hashes, lists, sets, sorted sets, streams, geo, bitmaps, and RedisJSON
• Platform-specific builds for Node.js, Cloudflare Workers, and Fastly Compute@Edge exported from dedicated subpaths
• Pipeline and multi/transaction APIs plus an automatic request-batching proxy for reducing round trips
• Built-in retry-with-backoff, base64 response decoding, and optional read-your-writes consistency tracking

Common Use Cases

• Caching database query results and API responses in serverless functions
• Rate limiting and request throttling at the edge
• Session storage and feature flagging for jamstack and single-page applications
• Lightweight pub/sub and streaming via server-sent events for real-time features

Under The Hood

Architecture — The library is centered on a Redis class (pkg/redis.ts) that composes roughly 200 typed *Command classes (e.g. GetCommand, HSetCommand, ZAddCommand under pkg/commands/) with a single HttpClient (pkg/http.ts) that implements the Requester interface. Each command serializes its Redis arguments into a JSON body and calls requester.request(), which POSTs to the Upstash REST endpoint, retries on network failure with exponential backoff, and decodes base64-encoded results back into native JS types (pkg/http.ts, decode()/base64decode()). Pipeline and Script/ScriptRo (pkg/pipeline.ts, pkg/script.ts) reuse the same command classes but batch them into one HTTP call, and auto-pipeline.ts wraps the Redis instance in a Proxy that auto-batches same-tick calls, distinguishing read/write commands via a READ_COMMANDS set for read-your-writes correctness. Three thin platform entry points (platforms/nodejs.ts, cloudflare.ts, fastly.ts) construct the same Redis core with runtime-appropriate fetch/agent options.

Tech Stack — Pure TypeScript, built with tsup into CJS/ESM/.d.ts bundles (tsup.config.ts), tested with Bun’s built-in test runner (bun test). The published package has exactly one runtime dependency, uncrypto (for cross-runtime crypto), keeping the client lightweight and tree-shakeable. The repo is a pnpm workspace (pnpm-workspace.yaml) housing @upstash/redis alongside sibling search-redis/search-ioredis packages, released via a Changesets-driven GitHub Actions pipeline with separate stable and canary publish flows.

Code Quality — Very high test density: 213 *.test.ts files sit directly alongside their corresponding pkg/commands/*.ts implementation files (e.g. redis.test.ts, pipeline.test.ts, auto-pipeline.test.ts, read-your-writes.test.ts), plus dedicated integration tests for Redis Functions. Error handling is centralized in three purpose-built classes (UpstashError, UrlError, UpstashJSONParseError in pkg/error.ts) that wrap raw REST failures with actionable messages, and the HTTP layer’s retry, backoff, and base64-decoding paths are exercised directly in http.test.ts. Naming is consistent throughout — every command file exports a single <Name>Command class extending a shared Command base.

API Design — The public API deliberately mirrors familiar Redis client conventions (redis.get(), redis.hset(), redis.zadd()), so anyone who has used ioredis or redis-py can be productive immediately; getting started requires only new Redis({ url, token }) with no connection lifecycle to manage. Extensive inline TSDoc comments on option types (RetryConfig, HttpClientConfig) and 26 runnable examples spanning Next.js, Cloudflare Workers, AWS Lambda, Azure Functions, and more keep the barrier to entry low despite the large command surface.