Upstash

RedisUpstash talks to Upstash over HTTPS using Effect's HTTP client, so it runs where raw sockets are not available, including Deno and Cloudflare Workers. It also runs on Node.js and Bun. Import it from @effect-kit/redis/upstash.

Example (Creating the Upstash Layer)

import { Config, Effect } from "effect";
import { Redis } from "@effect-kit/redis";
import { RedisUpstash } from "@effect-kit/redis/upstash";

const RedisLive = RedisUpstash.layerConfig(
  Config.all({
    url: Config.String("UPSTASH_REDIS_REST_URL"),
    token: Config.Redacted("UPSTASH_REDIS_REST_TOKEN"),
  }),
);

const program = Effect.gen(function* () {
  const redis = yield* Redis;
  return yield* redis.get("greeting");
});

export const runnable = program.pipe(Effect.provide(RedisLive));

Creating the layerCopy Anchor Link

The url must be https:, with no credentials, query string, hash or path. Authenticate with token (a Redacted string) or with credentials (see Credentials), not both. A plain-string token is a type error.

Provided servicesCopy Anchor Link

The layer provides Redis, BatchExecutor, CommandExecutor, RedisCredentials and UpstashEvents.

Example (The Services an Upstash Layer Provides)

import type { Layer } from "effect";
import { Redacted } from "effect";
import { RedisUpstash } from "@effect-kit/redis/upstash";

const RedisLive = RedisUpstash.layer({
  url: "https://example.upstash.io",
  token: Redacted.make("token"),
});

type Provided = Layer.Success<typeof RedisLive>;
       
type Provided = BatchExecutor | CommandExecutor | Redis | RedisCredentials | UpstashEvents

What works over HTTPCopy Anchor Link

Ordinary commands, pipelines and transactions work. A pipeline or transaction is one request. Pub/Sub is text only, through UpstashEvents.subscribe; see Pub/Sub.

These do not exist over HTTP:

• Sessions, WATCH and blocking commands.
• Client-side caching and tracking.
• Cluster and Sentinel routing. CLUSTER, SENTINEL, CLIENT and commands with an explicit node or slot target fail with UpstashError where reason is "unsupported" and delivery is "unsent".

Binary request positions are limited. Invalid UTF-8 in an argument fails with UpstashError and reason: "encoding". A transaction rejects commands whose replies are ambiguous, which means raw commands, custom commands and scripts.

redis.upstash holds Upstash's own commands, such as searchCreate, searchQuery, vectorCreate, vectorQuery and aclRestToken.

Handling UpstashErrorCopy Anchor Link

UpstashError has a stage (config, request, response or stream), a reason, and a delivery. Over HTTP, delivery is unsent, unknown or replied. It is unknown, never possibly-written: a request that failed in flight may have run.

A 429 response has reason: "rate-limit". When the response had a Retry-After header, retryAfterSeconds holds it. A 401 or 403 is reason: "authentication". The package does not retry either. Because the status errors have delivery: "unknown", wait and retry only commands that are safe to run twice.

Example (Reading the Retry Hint From a Rate Limit)

import { Effect } from "effect";
import { Redis } from "@effect-kit/redis";

export const read = Effect.gen(function* () {
  const redis = yield* Redis;
  return yield* redis.get("greeting");
}).pipe(
  Effect.catchTag("UpstashError", (error) =>
    error.reason === "rate-limit"
      ? Effect.logWarning(`rate limited, retry after ${error.retryAfterSeconds ?? "?"} seconds`)
      : Effect.fail(error),
  ),
);

Tested versionCopy Anchor Link

Upstash is tested against hosted instances in isolated tests, over both HTTP and native RESP. To use Upstash over a native socket instead, connect with RedisNode.layer and a rediss:// URL.