@breadstone/archipel-platform-caching

Layered caching infrastructure for NestJS with in-memory LRU+TTL+SWR and optional Redis-backed implementations.

Features

• In-memory LRU cache — MemoryLayeredCache with TTL, max entries, and stale-while-revalidate
• Redis cache — RedisLayeredCache for distributed caching via ioredis
• Layered architecture — Consistent API across memory and Redis implementations
• Tree-shakable — Redis support in separate sub-export to avoid bundling ioredis when not needed
• Health checks — CachingHealthIndicator for readiness probes (separate /health subpath)

⚠️ Environment Variables

Core (optional)

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

Redis provider

| Variable | Required | Default | Description | | ------------------- | -------- | ------- | ----------------------------------- | | REDIS_URL | yes | - | Redis connection URL | | REDIS_KEY_PREFIX | no | '' | Key prefix for all Redis cache keys | | REDIS_TTL_SECONDS | no | - | TTL in seconds for Redis entries |

Quick Start

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

const cache = new MemoryLayeredCache<string, number>(async (key) => fetchFromDatabase(key), {
  ttlMs: 60_000,
  maxEntries: 1000,
});

Import Options

// Main import (in-memory)
import { MemoryLayeredCache } from '@breadstone/archipel-platform-caching';

// Redis (tree-shakable sub-export)
import { RedisLayeredCache } from '@breadstone/archipel-platform-caching/redis';

// Health indicator (optional)
import { CachingHealthIndicator } from '@breadstone/archipel-platform-caching/health';

Lifecycle

• Shutdown (OnModuleDestroy): RedisLayeredCache disconnects from Redis gracefully.

Peer Dependencies

| Package | Required | Notes | | --------------------------------------------- | -------- | ----------------------------- | | @breadstone/archipel-platform-configuration | Yes | Typed config key support | | @nestjs/common | Yes | NestJS core | | ioredis | No | Required only for Redis cache | | @breadstone/archipel-platform-health | No | Required for health indicator | | @nestjs/terminus | No | Required for health indicator |

Documentation

📖 Package Docs: .docs/packages/platform-caching/index.md

Development

# Build
yarn nx build platform-caching

# Test
yarn nx test platform-caching

# Lint
yarn nx lint platform-caching