platform-caching

Layered caching library providing both an in-memory LRU cache and a Redis-backed distributed cache. Both implementations share the ILayeredCache contract and support TTL expiration, stale-while-revalidate, warm-up, and pluggable metrics recording.

Package: @breadstone/archipel-platform-caching

npm install @breadstone/archipel-platform-caching

Quick Start

import { MemoryLayeredCache } from '@breadstone/archipel-platform-caching';

const cache = new MemoryLayeredCache<string, IProduct>(async (key) => productRepository.findById(key), {
  ttlMs: 60_000,
  maxEntries: 500,
  staleWhileRevalidate: true,
});

const product = await cache.getAsync('prod-123');

For Redis-backed caching:

import { RedisLayeredCache } from '@breadstone/archipel-platform-caching/redis';

const cache = new RedisLayeredCache<string, IProduct>(redisClient, async (key) => productRepository.findById(key), {
  url: 'redis://localhost:6379',
  keyPrefix: 'products:',
  ttlSeconds: 300,
  cacheName: 'products',
});

---

ILayeredCache Interface

Both implementations share this contract:

Method	Description
get(key)	Synchronous cache lookup.
getAsync(key)	Asynchronous cache lookup — triggers the load function on a miss.
set(key, value)	Synchronous write.
setAsync(key, value)	Asynchronous write.
invalidate(key)	Synchronous eviction.
invalidateAsync(key)	Asynchronous eviction.
warm(key)	Proactively loads and caches a value.
stats()	Returns hit/miss/eviction counters as ICacheStats.

---

Configuration Options

ILayeredCacheOptions (In-Memory)

Property	Type	Default	Description
ttlMs	number	∞	Time-to-live in milliseconds.
staleWhileRevalidate	boolean	false	Serve stale entries while refreshing in the background.
maxEntries	number	∞	LRU eviction threshold.
metricsRecorder	ICacheMetricsRecorder	Noop	Pluggable metrics hook.
cacheName	string	'memory'	Label used in metrics and logging.

IRedisLayeredCacheOptions

Property	Type	Default	Description
url	string	—	Redis connection URL (e.g. redis://localhost:6379).
keyPrefix	string	—	Key prefix applied to all Redis keys.
ttlSeconds	number	∞	Time-to-live in seconds.
serialize	(value) => string	JSON.stringify	Custom serializer for cache values.
deserialize	(raw) => value	JSON.parse	Custom deserializer for cache entries.
metricsRecorder	ICacheMetricsRecorder	Noop	Pluggable metrics hook.
cacheName	string	'redis'	Label used in metrics and logging.

---

Environment Variables

Core (optional)

Variable	Description	Default	Required
CACHE_DEFAULT_TTL_MS	Default cache TTL in milliseconds	—	No
CACHE_MAX_ENTRIES	Maximum number of entries retained in an in-memory cache	—	No
CACHE_STALE_WHILE_REVALIDATE	Whether expired entries are served during background refresh	false	No

Redis

Subpath: @breadstone/archipel-platform-caching/redisSDK: ioredis ≥ 5.0.0

Variable	Description	Default	Required
REDIS_URL	Redis connection URL	—	Yes
REDIS_KEY_PREFIX	Key prefix for all Redis cache keys	''	No
REDIS_TTL_SECONDS	TTL in seconds for Redis entries	—	No

---

Metrics

Implement ICacheMetricsRecorder to forward cache statistics to your telemetry system:

import { ICacheMetricsRecorder } from '@breadstone/archipel-platform-caching';

class TelemetryCacheRecorder implements ICacheMetricsRecorder {
  recordHit(cacheName: string): void {
    /* increment counter */
  }
  recordMiss(cacheName: string): void {
    /* increment counter */
  }
  recordLoadSuccess(cacheName: string, durationMs: number): void {
    /* histogram */
  }
  recordLoadError(cacheName: string): void {
    /* increment counter */
  }
  recordEviction(cacheName: string): void {
    /* increment counter */
  }
}

When no recorder is provided, NoopCacheMetricsRecorder is used as a silent fallback.

---

Health Check

The CachingHealthIndicator reports the caching subsystem as available. Import it from the /health subpath:

import { CachingHealthIndicator } from '@breadstone/archipel-platform-caching/health';
import { HealthModule } from '@breadstone/archipel-platform-health';

@Module({
  imports: [
    CachingModule,
    HealthModule.withIndicators([CachingHealthIndicator]),
  ],
})
export class AppModule {}

Key	Check	Dependencies
caching	Always reports up	None

---

API Reference

See the full API documentation for all exported types and classes.