UpstashRedis

Upstash Redis

Typed Upstash Redis REST API client for Deno, Bun, Node.js and Cloudflare Workers: Redis over plain HTTPS, with no TCP client or connection pool. It covers GET/SET/DEL/EXISTS/EXPIRE/INCR/INCRBY, hash (HGET/HSET) and list (LPUSH/RPUSH/LRANGE) commands, request-level pipelining, and a low-level execute() escape hatch for anything not otherwise typed. A lightweight alternative to @upstash/redis for the commands it covers.

Overview

Upstash exposes every Redis database it hosts over a REST API in addition to the normal Redis wire protocol: a command is a JSON array (["SET", "key", "value"]) posted to the database's REST URL, and the response is a small JSON envelope ({"result": ...} or {"error": ...}). This connect wraps that API with one typed method per command, Guardian schemas for every request/response shape, and a single UpstashRedisError class for every failure mode.

import { UpstashRedis } from '@tundraconnect/upstash-redis';

const client = new UpstashRedis({
  auth: { type: 'BEARER', token: 'AAAAA...', prefix: 'Bearer' },
  baseURL: 'https://us1-merry-cat-32748.upstash.io',
});

await client.set('foo', 'bar', { ex: 60 });
console.log(await client.get('foo')); // 'bar'

Testing your code

Your tests don't need to fake HTTP. Have your code take a UpstashRedis instance and pass in a stand-in that returns the shapes from @tundraconnect/upstash-redis/schemas or throws a real UpstashRedisError:

import { UpstashRedisError } from '@tundraconnect/upstash-redis/errors';

const outage = new UpstashRedisError('SERVICE_UNAVAILABLE', { status: 503 });
console.log(outage.code);

To exercise the client itself against a fake transport, subclass it and reassign the protected _fetch.

Documentation

Topic	Description
API	Client configuration and endpoint methods
Errors	Error codes and diagnostic metadata
Schemas	Public Guardian schemas and inferred types

Upstream

• Vendor API reference
• Create a vendor account — the free tier includes 10 databases and 500K commands/month, no card required.

Installation

Deno:

deno add jsr:@tundraconnect/upstash-redis

Bun:

bunx jsr add @tundraconnect/upstash-redis

Node.js:

npx jsr add @tundraconnect/upstash-redis

Quick Start

Create a database in the Upstash console, copy its REST URL and REST token, then:

import { UpstashRedis } from '@tundraconnect/upstash-redis';

const client = new UpstashRedis({
  auth: { type: 'BEARER', token: 'AAAAA...', prefix: 'Bearer' },
  baseURL: 'https://us1-merry-cat-32748.upstash.io',
});

// Set a key with a 60-second expiry, then read it back.
await client.set('foo', 'bar', { ex: 60 });
const value = await client.get('foo'); // 'bar'

// Hashes and lists work the same way.
await client.hset('employee:1', { name: 'Ada', salary: 100000 });
await client.rpush('queue', 'job-1', 'job-2');

// Batch several commands in one round trip (not atomic — see the API docs).
const results = await client.pipeline([
  ['INCR', 'visits'],
  ['GET', 'foo'],
]);

Every method throws UpstashRedisError on failure — see Errors for the full code list and how to branch on error.code.

License

MIT. Part of Tundra Connect, typed vendor API clients for Deno, Bun, Node.js and Cloudflare Workers.