Use cache when the same data is read far more often than it changes. Use coalesce (single-flight) when many callers ask for the same thing at the same moment, a cache stampede after a deploy or a cold key, but every answer must be fresh. Use stale fallback when every call must go through, yet an old answer beats an error. Don’t cache writes, or per-user data under a shared key.
Polly-style builder with a shortcut for every strategy: addRetry(), addTimeout(), addCircuitBreaker(), …
Convenient, but it bundles every strategy. For the smallest browser bundle use PipelineBuilder with
retryStrategy(), timeoutStrategy(), … instead; the two are interchangeable.
The type parameters track which errors the pipeline can raise, for pipeline.settle() + Outcome.match().
ResiliencePipelineBuilder adds Polly-style addRetry() / addTimeout() / … shortcuts on top, at the cost of
bundling every strategy. Strategies run in the order they are added: the first one added is the outermost.
Options are validated and strategy state (e.g. circuit breaker) is created on build().
Key.key(context), by default context.operationKey. An undefined key skips the cache entirely.
Fresh hit (age < ttl): return the stored value. The callback doesn’t run. OnCacheHit.
Too old (age ≥ ttl + staleTtl): delete the entry.
Miss: OnCacheMiss, then call through. Concurrent misses for the same key share one call (OnCoalesced).
Success: store it if shouldCache agrees (and ttl + staleTtl > 0). Failures are never stored.
Failure with an entry still in its stale window, and shouldServeStale agrees: return the stale value instead. OnStaleServed.
The store is read on every call and may be remote. A store that throws never fails the call: a failed get counts as a miss, a failed set or delete is skipped, and each is reported as OnCacheStoreFailed.
Polly-style builder with a shortcut for every strategy: addRetry(), addTimeout(), addCircuitBreaker(), …
Convenient, but it bundles every strategy. For the smallest browser bundle use PipelineBuilder with
retryStrategy(), timeoutStrategy(), … instead; the two are interchangeable.
The type parameters track which errors the pipeline can raise, for pipeline.settle() + Outcome.match().
addStaleFallback / staleFallbackStrategy remembers the last good value per key and returns it only when a call fails. Fresh calls always go through. It is the cache strategy with ttl: 0, staleTtl: maxAge and coalesce: false; see fallback for how it fits with other fallbacks.
Option
Type
Default
Description
maxAge
Duration
required
How old a last-good value may be and still be served.
Polly-style builder with a shortcut for every strategy: addRetry(), addTimeout(), addCircuitBreaker(), …
Convenient, but it bundles every strategy. For the smallest browser bundle use PipelineBuilder with
retryStrategy(), timeoutStrategy(), … instead; the two are interchangeable.
The type parameters track which errors the pipeline can raise, for pipeline.settle() + Outcome.match().
MemoryCacheStore is the default: an in-process Map bounded by maxEntries (default 1000), evicting the least recently used entry. It ignores the TTL hint; the strategy deletes expired entries when it reads them and LRU bounds the rest. It also has size and clear().
import {
classMemoryCacheStore
In-process store, bounded by maxEntries (least recently used goes first).
Polly-style builder with a shortcut for every strategy: addRetry(), addTimeout(), addCircuitBreaker(), …
Convenient, but it bundles every strategy. For the smallest browser bundle use PipelineBuilder with
retryStrategy(), timeoutStrategy(), … instead; the two are interchangeable.
The type parameters track which errors the pipeline can raise, for pipeline.settle() + Outcome.match().
Polly-style builder with a shortcut for every strategy: addRetry(), addTimeout(), addCircuitBreaker(), …
Convenient, but it bundles every strategy. For the smallest browser bundle use PipelineBuilder with
retryStrategy(), timeoutStrategy(), … instead; the two are interchangeable.
The type parameters track which errors the pipeline can raise, for pipeline.settle() + Outcome.match().
Polly-style builder with a shortcut for every strategy: addRetry(), addTimeout(), addCircuitBreaker(), …
Convenient, but it bundles every strategy. For the smallest browser bundle use PipelineBuilder with
retryStrategy(), timeoutStrategy(), … instead; the two are interchangeable.
The type parameters track which errors the pipeline can raise, for pipeline.settle() + Outcome.match().
ttlMs = ttl + staleTtl: how long the entry can still be useful. Remote stores can expire it natively.
set(
key: string
key:string,
entry: CacheEntry
entry:
(alias) interfaceCacheEntry
importCacheEntry
CacheEntry,
ttlMs: number
ttlMs:number):
interfacePromise<T>
Represents the completion of an asynchronous operation
Promise<void>;
MyCacheStore.delete(key: string): Promise<void>
delete(
key: string
key:string):
interfacePromise<T>
Represents the completion of an asynchronous operation
Promise<void>;
}
// CacheEntry = { value: unknown; storedAt: number } (epoch ms from the pipeline's clock)
The strategy decides freshness from storedAt, so a store only has to keep entries. RedisCacheStore (Redis) is ready-made. Values must survive the store’s serialization (JSON for Redis).
