Upstash Cache

UpstashRedisCache is the Cache component’s serverless backend. It talks to Upstash Redis over its HTTP REST API, with no persistent TCP connection, which makes it a natural fit for edge and serverless runtimes. It implements the same ICache interface as every other backend, so you can develop against the filesystem or a local Redis and switch to Upstash in production without changing a single call site.

What this backend offers

The HTTP REST transport means no TCP pooling, so it runs in edge functions and short-lived runtimes where pooling is awkward. The interface is the same ICache you use elsewhere: get, set, delete, has, deleteByPrefix, and clear. Every key is prefixed with a namespace (default cache), which lets several apps share one Upstash database without colliding. The bulk operations, deleteByPrefix() and clear(), use cursor-based SCAN with pipelined deletes so they stay efficient on large keyspaces. The class registers with @decorator.cache() and resolves from the container.

Installation

UpstashRedisCache ships with @talosjs/cache and depends on the Upstash Redis client.

bun add @talosjs/cache @upstash/redis

Environment variables

Variable	Required	Purpose
`CACHE_UPSTASH_REDIS_REST_URL`	Yes	Upstash Redis REST URL. Missing throws `CacheException` (`CONFIG_REQUIRED`).
`CACHE_UPSTASH_REDIS_REST_TOKEN`	Yes	Upstash Redis REST token. Missing throws `CacheException` (`CONFIG_REQUIRED`).

CACHE_UPSTASH_REDIS_REST_URL=https://your-db.upstash.io
CACHE_UPSTASH_REDIS_REST_TOKEN=your_rest_token

Both can also be passed through constructor options (url, token), which take precedence over the environment. Either way they are validated when the cache is constructed, so misconfiguration fails fast.

Options

UpstashRedisCache accepts an options object as its second constructor argument:

Option	Type	Default	Purpose
`namespace`	`string`	`"cache"`	Key prefix; every key is stored as `<namespace>:<key>`.
`url`	`string`	`CACHE_UPSTASH_REDIS_REST_URL`	Override the REST URL.
`token`	`string`	`CACHE_UPSTASH_REDIS_REST_TOKEN`	Override the REST token.

How it works

Keys are namespaced before they hit Redis: set("user:1", …) with the default namespace writes cache:user:1. Reads, writes, and existence checks map straight onto Upstash commands, while the bulk operations iterate the keyspace with SCAN and delete matches in a pipeline.

Method	Purpose
`get<T>(key)`	Read a value, or `undefined` if absent.
`set<T>(key, value, ttl?)`	Write a value; `ttl` (seconds) sets an expiry via `EX`.
`delete(key)`	Delete one key; returns whether a key was removed.
`has(key)`	Whether a key exists.
`deleteByPrefix(prefix)`	`SCAN` + pipelined delete of `<namespace>:<prefix>*`; returns the count deleted.
`clear()`	`SCAN` + pipelined delete of every key under the namespace.

Usage

The API is identical to every other cache backend.

import { container } from "@talosjs/container";
import { UpstashRedisCache } from "@talosjs/cache";

const cache = container.get(UpstashRedisCache);

// Write with a 5-minute TTL
await cache.set("user:123", { id: 123, name: "Ada" }, 300);

// Read it back
const user = await cache.get<{ id: number; name: string }>("user:123");

// Existence and removal
await cache.has("user:123"); // true
await cache.delete("user:123"); // true

// Bulk operations
await cache.deleteByPrefix("user:"); // delete every user:* key, returns the count
await cache.clear(); // empty the whole namespace

To run several isolated caches against one Upstash database, give each its own namespace:

import { decorator } from "@talosjs/cache";
import { UpstashRedisCache } from "@talosjs/cache";
import { AppEnv } from "@talosjs/app-env";
import { inject } from "@talosjs/container";

@decorator.cache()
export class SessionCache extends UpstashRedisCache {
  constructor(@inject(AppEnv) env: AppEnv) {
    super(env, { namespace: "sessions" });
  }
}

Use in the app

In an @talosjs/app application, pass UpstashRedisCache to the cache slot of your App config. The framework registers it and exposes it as the "cache" container constant.

bun add @talosjs/app @talosjs/cache @upstash/redis

import { App } from "@talosjs/app";
import { UpstashRedisCache } from "@talosjs/cache";
import { TerminalLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [TerminalLogger],
  cache: UpstashRedisCache,
});

await app.run();

With a cache configured, any route that declares a cache key has its response cached automatically. The framework builds the cache key from the route’s cache prefix, HTTP method, URL, and the authenticated user’s id:

import { Route } from "@talosjs/routing";

@Route.get("/api/products", {
  name: "products",
  version: 1,
  description: "List products",
  cache: "products", // response cached through the configured UpstashRedisCache
})
export class ProductsController {
  public async index(context: ContextType<ProductsRouteType>) {
    return context.response.json(await this.products.findAll());
  }
}

You can also reach the same instance anywhere for manual caching, either by injecting it or by reading the constant:

import { container } from "@talosjs/container";
import type { ICache } from "@talosjs/cache";

const cache = container.getConstant<ICache>("cache"); // the app's configured cache

Set CACHE_UPSTASH_REDIS_REST_URL and CACHE_UPSTASH_REDIS_REST_TOKEN in your .env.yml (or environment) so the cache can connect.

Exceptions

UpstashRedisCache throws CacheException on misconfiguration, carrying a machine-readable key.

Key	When
`CONFIG_REQUIRED`	The REST URL or token is missing from both options and the environment.

import { CacheException } from "@talosjs/cache";

try {
  const cache = container.get(UpstashRedisCache);
} catch (error) {
  if (error instanceof CacheException && error.key === "CONFIG_REQUIRED") {
    logger.error("Upstash cache is misconfigured", error.data);
  }
  throw error;
}

Caching without surprises

Pass ttl (seconds) on set() for anything volatile so transient values expire instead of piling up. Give each concern its own namespace (sessions, rate counters, query cache) so clear() and deleteByPrefix() only touch what you mean them to. Group related keys with structured prefixes like user:123:profile, which lets deleteByPrefix("user:123:") invalidate them together. Load the REST URL and token from .env, never from source. And since the ICache calls stay identical, develop against the filesystem or a local Redis and switch to Upstash for production. See the Cache component for the full interface and the other backends.

Getting Started

AI

Framework

Command Line

Upstash Cache

What this backend offers

Installation

Environment variables

Options

How it works

Usage

Use in the app

Exceptions

Caching without surprises

​What this backend offers

​Installation

​Environment variables

​Options

​How it works

​Usage

​Use in the app

​Exceptions

​Caching without surprises

What this backend offers

Installation

Environment variables

Options

How it works

Usage

Use in the app

Exceptions

Caching without surprises