@breadstone/archipel-mcp 0.0.7 → 0.0.8

package/data/packages/platform-caching/api/Interface.ILayeredCacheOptions.md

@@ -0,0 +1,76 @@
+---
+title: 'Interface: ILayeredCacheOptions'
+generated: true
+editUrl: false
+---
+
+# Interface: ILayeredCacheOptions
+
+Defined in: [MemoryLayeredCache.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L16)
+
+Configuration options for [MemoryLayeredCache](Class.MemoryLayeredCache).
+
+## Properties
+
+### cacheName?
+
+```ts
+optional cacheName?: string;
+```
+
+Defined in: [MemoryLayeredCache.ts:58](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L58)
+
+An optional name / label for the cache instance, used in metrics.
+Defaults to `'memory'`.
+
+---
+
+### maxEntries?
+
+```ts
+optional maxEntries?: number;
+```
+
+Defined in: [MemoryLayeredCache.ts:42](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L42)
+
+Maximum number of entries retained in the cache. Oldest entries are
+evicted first (LRU). Defaults to infinite.
+
+---
+
+### metricsRecorder?
+
+```ts
+optional metricsRecorder?: ICacheMetricsRecorder;
+```
+
+Defined in: [MemoryLayeredCache.ts:50](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L50)
+
+Optional metrics recorder forwarded cache operation statistics.
+Falls back to [NoopCacheMetricsRecorder](Class.NoopCacheMetricsRecorder) when omitted.
+
+---
+
+### staleWhileRevalidate?
+
+```ts
+optional staleWhileRevalidate?: boolean;
+```
+
+Defined in: [MemoryLayeredCache.ts:34](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L34)
+
+When `true`, expired entries are served immediately while a background
+refresh is triggered. Defaults to `false`.
+
+---
+
+### ttlMs?
+
+```ts
+optional ttlMs?: number;
+```
+
+Defined in: [MemoryLayeredCache.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L26)
+
+Time to live in milliseconds. Entries older than this are considered expired.
+Defaults to infinite (no expiration).

package/data/packages/platform-caching/api/Interface.IRedisLayeredCacheOptions.md

@@ -0,0 +1,122 @@
+---
+title: 'Interface: IRedisLayeredCacheOptions\<TValue\>'
+generated: true
+editUrl: false
+---
+
+# Interface: IRedisLayeredCacheOptions\<TValue\>
+
+Defined in: [redis/RedisLayeredCache.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L18)
+
+Configuration options for [RedisLayeredCache](Class.RedisLayeredCache).
+
+## Type Parameters
+
+| Type Parameter | Description                              |
+| -------------- | ---------------------------------------- |
+| `TValue`       | The type of values stored in this cache. |
+
+## Properties
+
+### cacheName?
+
+```ts
+optional cacheName?: string;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L68)
+
+An optional name / label for the cache instance, used in metrics.
+Defaults to `'redis'`.
+
+---
+
+### deserialize?
+
+```ts
+optional deserialize?: (raw) => TValue;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L53)
+
+Custom deserialization function. Defaults to `JSON.parse`.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `raw`     | `string` |
+
+#### Returns
+
+`TValue`
+
+---
+
+### keyPrefix
+
+```ts
+keyPrefix: string;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:32](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L32)
+
+Key prefix applied to all Redis keys managed by this cache instance.
+
+---
+
+### metricsRecorder?
+
+```ts
+optional metricsRecorder?: ICacheMetricsRecorder;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:60](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L60)
+
+Optional metrics recorder forwarded cache operation statistics.
+
+---
+
+### serialize?
+
+```ts
+optional serialize?: (value) => string;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:46](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L46)
+
+Custom serialization function. Defaults to `JSON.stringify`.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `value`   | `TValue` |
+
+#### Returns
+
+`string`
+
+---
+
+### ttlSeconds?
+
+```ts
+optional ttlSeconds?: number;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L39)
+
+Optional TTL in seconds applied to every stored entry.
+
+---
+
+### url
+
+```ts
+url: string;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L25)
+
+Redis connection URL (e.g. `redis://localhost:6379`).

package/data/packages/platform-caching/api/index.md

@@ -0,0 +1,25 @@
+---
+title: '@breadstone/archipel-platform-caching'
+generated: true
+editUrl: false
+---
+
+# @breadstone/archipel-platform-caching
+
+## Classes
+
+| Class                                                      | Description                                                                                                                                                           |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [MemoryLayeredCache](Class.MemoryLayeredCache)             | In-memory layered cache with LRU eviction, TTL expiration and optional stale-while-revalidate support. Falls back to an asynchronous loader function on cache misses. |
+| [NoopCacheMetricsRecorder](Class.NoopCacheMetricsRecorder) | No-op implementation of [ICacheMetricsRecorder](Interface.ICacheMetricsRecorder) used as the default when no external metrics backend is configured.                  |
+| [RedisLayeredCache](Class.RedisLayeredCache)               | Redis-backed layered cache implementation. Falls back to an asynchronous loader function when the requested key is not present in Redis.                              |
+
+## Interfaces
+
+| Interface                                                        | Description                                                                                                                         |
+| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| [ICacheMetricsRecorder](Interface.ICacheMetricsRecorder)         | Metrics recorder for cache operations. Implementations can forward measurements to Prometheus, OpenTelemetry, or any other backend. |
+| [ICacheStats](Interface.ICacheStats)                             | Cache statistics snapshot returned by cache implementations.                                                                        |
+| [ILayeredCache](Interface.ILayeredCache)                         | Generic layered cache contract supporting synchronous and asynchronous access patterns with optional warm-up and statistics.        |
+| [ILayeredCacheOptions](Interface.ILayeredCacheOptions)           | Configuration options for [MemoryLayeredCache](Class.MemoryLayeredCache).                                                           |
+| [IRedisLayeredCacheOptions](Interface.IRedisLayeredCacheOptions) | Configuration options for [RedisLayeredCache](Class.RedisLayeredCache).                                                             |

package/data/packages/platform-caching/index.md

@@ -0,0 +1,116 @@
+---
+title: platform-caching
+description: Layered caching with in-memory LRU and Redis-backed implementations, TTL, stale-while-revalidate, and metrics.
+order: 15
+tags: [caching, lru, redis, ttl, stale-while-revalidate, metrics]
+package: '@breadstone/archipel-platform-caching'
+---
+
+# 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`
+
+## Quick Start
+
+```typescript
+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:
+
+```typescript
+import { RedisLayeredCache } from '@breadstone/archipel-platform-caching/redis';
+
+const cache = new RedisLayeredCache<string, IProduct>(redisClient, async (key) => productRepository.findById(key), {
+  ttlMs: 300_000,
+  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                                             |
+| ---------------------- | ----------------------- | ---------------- | ------------------------------------------------------- |
+| `ttlMs`                | `number`                | ∞                | Time-to-live in milliseconds.                           |
+| `staleWhileRevalidate` | `boolean`               | `false`          | Serve stale entries while refreshing in the background. |
+| `metricsRecorder`      | `ICacheMetricsRecorder` | Noop             | Pluggable metrics hook.                                 |
+| `cacheName`            | `string`                | `'redis'`        | Label used in metrics and logging.                      |
+| `serialize`            | `(value) => string`     | `JSON.stringify` | Custom serializer for cache values.                     |
+| `deserialize`          | `(raw) => value`        | `JSON.parse`     | Custom deserializer for cache entries.                  |
+
+---
+
+## Metrics
+
+Implement `ICacheMetricsRecorder` to forward cache statistics to your telemetry system:
+
+```typescript
+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.
+
+---
+
+## API Reference
+
+See the full [API documentation](./api/) for all exported types and classes.