# @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

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

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

## Import Options

```typescript
// 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`](../../.docs/packages/platform-caching/index.md)

## Development

```bash
# Build
yarn nx build platform-caching

# Test
yarn nx test platform-caching

# Lint
yarn nx lint platform-caching
```