API Reference

Environment name override. When omitted, falls back to process.env.NODE_ENV or "development".

Values "development" and "test" use in-memory cache and rate limiting.

When true (default), use in-memory cache and rate-limit backends during static build phases (phase-production-build, phase-export via NEXT_PHASE).

Legacy Upstash credentials or client.

Mutually exclusive with store. Use store: upstashStore({ url, token }) for new projects.

Explicit store implementation (preferred).

Application logger. Defaults to a silent no-op logger.

Override default TTL seconds per duration name (short | medium | long). Accepts either a flat map (applied to the active environment) or a nested { development?, production? } map. Used by getTTL() and withCache(..., { ttl }).

Default key generator for all withCache wrappers. Per-call keyGenerator in CacheOptions overrides this.

Default for withCache when cacheFailures is omitted. Default false.

Default stale-while-revalidate window in seconds for withCache.

Clears all cached entries.

Works with the in-memory dev store or stores that implement clear(). Returns an error in production when the active store does not support clearing.

Returns the lazily initialized CacheStore backing this client.

Returns cache statistics when the active store supports synchronous stats.

Available for the in-memory store; returns null for Redis/Upstash backends.

Resolves a TTL duration name to seconds for the active environment.

Respects createCache({ ttl }) overrides and built-in CACHE_TTL defaults.

Returns the underlying InMemoryCache when the active store is in-memory.

Returns null for Redis or Upstash backends.

Deletes cache keys matching a glob pattern under an optional prefix.

Deletes a single cache key by exact match.

Tears down the active store instance and resets lazy initialization.

Useful in tests to isolate cache state between cases.

Wraps an async function with read-through caching.

Caches successful return values and Result successes by default. Supports opt-in negative caching, stale-while-revalidate, and per-call TTL/key options via CacheOptions.

Opt-in negative caching for failed Result values. Default from createCache({ cacheFailures }) or false.

Builds the cache key suffix from function arguments.

The prefix is prepended automatically as `${prefix}:${suffix}`. Overrides createCache({ keyGenerator }) for this call. Falls back to function name plus serialized args when omitted.

Key namespace prepended to every cache key.

Stale-while-revalidate window in seconds. Overrides createCache({ staleWhileRevalidate }).

TTL duration bucket for cached successes.

Resolved to seconds via CacheClient.getTTL for the active environment.

When true, always includes page (default 1) and limit (default 10).

Max key length before replacing the param segment with an MD5 hash.

Separator between key segments.