@breadstone/archipel-mcp 0.0.6 → 0.0.8

package/data/packages/{platform-core → platform-caching}/api/Class.MemoryLayeredCache.md

@@ -6,9 +6,11 @@ editUrl: false
 
 # Class: MemoryLayeredCache\<TKey, TValue\>
 
-Defined in: [cache/MemoryLayeredCache.ts:66](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L66)
+Defined in: [MemoryLayeredCache.ts:73](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L73)
 
-In-memory layered cache implementation.
+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.
 
 ## Type Parameters
 
@@ -29,14 +31,16 @@ In-memory layered cache implementation.
 new MemoryLayeredCache<TKey, TValue>(loadFn, options?): MemoryLayeredCache<TKey, TValue>;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:87](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L87)
+Defined in: [MemoryLayeredCache.ts:100](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L100)
+
+Initializes a new instance of the MemoryLayeredCache class.
 
 #### Parameters
 
-| Parameter  | Type                                                     |
-| ---------- | -------------------------------------------------------- |
-| `loadFn`   | (`key`) => `Promise`\<`TValue` \| `undefined`\>          |
-| `options?` | [`ILayeredCacheOptions`](Interface.ILayeredCacheOptions) |
+| Parameter  | Type                                                     | Description                                      |
+| ---------- | -------------------------------------------------------- | ------------------------------------------------ |
+| `loadFn`   | (`key`) => `Promise`\<`TValue` \| `undefined`\>          | Async loader invoked on cache misses.            |
+| `options?` | [`ILayeredCacheOptions`](Interface.ILayeredCacheOptions) | Optional configuration for TTL, LRU and metrics. |
 
 #### Returns
 
@@ -50,9 +54,9 @@ Defined in: [cache/MemoryLayeredCache.ts:87](https://github.com/RueDeRennes/arch
 get(key): TValue | undefined;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:107](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L107)
+Defined in: [MemoryLayeredCache.ts:115](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L115)
 
-Retrieves a value from the cache.
+Retrieves a value from the cache synchronously.
 
 #### Parameters
 
@@ -64,6 +68,8 @@ Retrieves a value from the cache.
 
 `TValue` \| `undefined`
 
+The cached value or `undefined` on a miss.
+
 #### Implementation of
 
 [`ILayeredCache`](Interface.ILayeredCache).[`get`](Interface.ILayeredCache#get)
@@ -76,9 +82,9 @@ Retrieves a value from the cache.
 getAsync(key): Promise<TValue | undefined>;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:133](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L133)
+Defined in: [MemoryLayeredCache.ts:136](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L136)
 
-Retrieves a value from the cache (asynchronous).
+Retrieves a value from the cache asynchronously.
 
 #### Parameters
 
@@ -90,6 +96,8 @@ Retrieves a value from the cache (asynchronous).
 
 `Promise`\<`TValue` \| `undefined`\>
 
+A promise resolving to the cached value or `undefined` on a miss.
+
 #### Implementation of
 
 [`ILayeredCache`](Interface.ILayeredCache).[`getAsync`](Interface.ILayeredCache#getasync)
@@ -102,9 +110,9 @@ Retrieves a value from the cache (asynchronous).
 invalidate(key): void;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:193](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L193)
+Defined in: [MemoryLayeredCache.ts:180](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L180)
 
-Invalidates a key in the cache.
+Invalidates a key in the cache synchronously.
 
 #### Parameters
 
@@ -128,9 +136,9 @@ Invalidates a key in the cache.
 invalidateAsync(key): Promise<void>;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:203](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L203)
+Defined in: [MemoryLayeredCache.ts:185](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L185)
 
-Invalidates a key in the cache (asynchronous).
+Invalidates a key in the cache asynchronously.
 
 #### Parameters
 
@@ -154,16 +162,16 @@ Invalidates a key in the cache (asynchronous).
 set(key, value): void;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:161](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L161)
+Defined in: [MemoryLayeredCache.ts:158](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L158)
 
-Sets a value in the cache.
+Stores a value in the cache synchronously.
 
 #### Parameters
 
-| Parameter | Type     | Description       |
-| --------- | -------- | ----------------- |
-| `key`     | `TKey`   | The key to set.   |
-| `value`   | `TValue` | The value to set. |
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `key`     | `TKey`   | The key to store.   |
+| `value`   | `TValue` | The value to store. |
 
 #### Returns
 
@@ -181,16 +189,16 @@ Sets a value in the cache.
 setAsync(key, value): Promise<void>;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:175](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L175)
+Defined in: [MemoryLayeredCache.ts:166](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L166)
 
-Sets a value in the cache (asynchronous).
+Stores a value in the cache asynchronously.
 
 #### Parameters
 
-| Parameter | Type     | Description       |
-| --------- | -------- | ----------------- |
-| `key`     | `TKey`   | The key to set.   |
-| `value`   | `TValue` | The value to set. |
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `key`     | `TKey`   | The key to store.   |
+| `value`   | `TValue` | The value to store. |
 
 #### Returns
 
@@ -208,15 +216,15 @@ Sets a value in the cache (asynchronous).
 stats(): ICacheStats;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:207](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L207)
+Defined in: [MemoryLayeredCache.ts:190](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L190)
 
-Retrieves cache statistics.
+Returns current cache statistics.
 
 #### Returns
 
 [`ICacheStats`](Interface.ICacheStats)
 
-The cache statistics.
+The cache statistics snapshot.
 
 #### Implementation of
 
@@ -230,9 +238,9 @@ The cache statistics.
 warm(key): Promise<TValue | undefined>;
 ```
 
-Defined in: [cache/MemoryLayeredCache.ts:182](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/cache/MemoryLayeredCache.ts#L182)
+Defined in: [MemoryLayeredCache.ts:174](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/MemoryLayeredCache.ts#L174)
 
-Proactively warms the cache for a given key (optional).
+Proactively warms the cache for a given key.
 
 #### Parameters
 
@@ -244,7 +252,7 @@ Proactively warms the cache for a given key (optional).
 
 `Promise`\<`TValue` \| `undefined`\>
 
-The value that was loaded and cached, or undefined if not found.
+The value that was loaded and cached, or `undefined` if not found.
 
 #### Implementation of
 

package/data/packages/platform-caching/api/Class.NoopCacheMetricsRecorder.md

@@ -0,0 +1,158 @@
+---
+title: 'Class: NoopCacheMetricsRecorder'
+generated: true
+editUrl: false
+---
+
+# Class: NoopCacheMetricsRecorder
+
+Defined in: [NoopCacheMetricsRecorder.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/NoopCacheMetricsRecorder.ts#L13)
+
+No-op implementation of [ICacheMetricsRecorder](Interface.ICacheMetricsRecorder) used as the default
+when no external metrics backend is configured.
+
+## Implements
+
+- [`ICacheMetricsRecorder`](Interface.ICacheMetricsRecorder)
+
+## Constructors
+
+### Constructor
+
+```ts
+new NoopCacheMetricsRecorder(): NoopCacheMetricsRecorder;
+```
+
+#### Returns
+
+`NoopCacheMetricsRecorder`
+
+## Methods
+
+### recordEviction()?
+
+```ts
+optional recordEviction(_cache): void;
+```
+
+Defined in: [NoopCacheMetricsRecorder.ts:38](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/NoopCacheMetricsRecorder.ts#L38)
+
+Records a cache eviction.
+
+#### Parameters
+
+| Parameter | Type     | Description             |
+| --------- | -------- | ----------------------- |
+| `_cache`  | `string` | The cache name / label. |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ICacheMetricsRecorder`](Interface.ICacheMetricsRecorder).[`recordEviction`](Interface.ICacheMetricsRecorder#recordeviction)
+
+---
+
+### recordHit()
+
+```ts
+recordHit(_cache): void;
+```
+
+Defined in: [NoopCacheMetricsRecorder.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/NoopCacheMetricsRecorder.ts#L18)
+
+Records a cache hit.
+
+#### Parameters
+
+| Parameter | Type     | Description             |
+| --------- | -------- | ----------------------- |
+| `_cache`  | `string` | The cache name / label. |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ICacheMetricsRecorder`](Interface.ICacheMetricsRecorder).[`recordHit`](Interface.ICacheMetricsRecorder#recordhit)
+
+---
+
+### recordLoadError()
+
+```ts
+recordLoadError(_cache): void;
+```
+
+Defined in: [NoopCacheMetricsRecorder.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/NoopCacheMetricsRecorder.ts#L33)
+
+Records a failed cache load.
+
+#### Parameters
+
+| Parameter | Type     | Description             |
+| --------- | -------- | ----------------------- |
+| `_cache`  | `string` | The cache name / label. |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ICacheMetricsRecorder`](Interface.ICacheMetricsRecorder).[`recordLoadError`](Interface.ICacheMetricsRecorder#recordloaderror)
+
+---
+
+### recordLoadSuccess()
+
+```ts
+recordLoadSuccess(_cache): void;
+```
+
+Defined in: [NoopCacheMetricsRecorder.ts:28](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/NoopCacheMetricsRecorder.ts#L28)
+
+Records a successful cache load.
+
+#### Parameters
+
+| Parameter | Type     | Description             |
+| --------- | -------- | ----------------------- |
+| `_cache`  | `string` | The cache name / label. |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ICacheMetricsRecorder`](Interface.ICacheMetricsRecorder).[`recordLoadSuccess`](Interface.ICacheMetricsRecorder#recordloadsuccess)
+
+---
+
+### recordMiss()
+
+```ts
+recordMiss(_cache): void;
+```
+
+Defined in: [NoopCacheMetricsRecorder.ts:23](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/NoopCacheMetricsRecorder.ts#L23)
+
+Records a cache miss.
+
+#### Parameters
+
+| Parameter | Type     | Description             |
+| --------- | -------- | ----------------------- |
+| `_cache`  | `string` | The cache name / label. |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ICacheMetricsRecorder`](Interface.ICacheMetricsRecorder).[`recordMiss`](Interface.ICacheMetricsRecorder#recordmiss)

package/data/packages/platform-caching/api/Class.RedisLayeredCache.md

@@ -0,0 +1,296 @@
+---
+title: 'Class: RedisLayeredCache\<TKey, TValue\>'
+generated: true
+editUrl: false
+---
+
+# Class: RedisLayeredCache\<TKey, TValue\>
+
+Defined in: [redis/RedisLayeredCache.ts:84](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L84)
+
+Redis-backed layered cache implementation. Falls back to an asynchronous
+loader function when the requested key is not present in Redis.
+
+## Remarks
+
+Synchronous methods (`get`, `set`, `invalidate`) throw because Redis
+is inherently asynchronous. Use the `*Async` variants instead.
+
+## Type Parameters
+
+| Type Parameter | Description                   |
+| -------------- | ----------------------------- |
+| `TKey`         | The type of the cache keys.   |
+| `TValue`       | The type of the cache values. |
+
+## Implements
+
+- [`ILayeredCache`](Interface.ILayeredCache)\<`TKey`, `TValue`\>
+- `OnModuleDestroy`
+
+## Constructors
+
+### Constructor
+
+```ts
+new RedisLayeredCache<TKey, TValue>(loadFn, options): RedisLayeredCache<TKey, TValue>;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:109](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L109)
+
+Initializes a new instance of the RedisLayeredCache class.
+
+#### Parameters
+
+| Parameter | Type                                                                           | Description                                         |
+| --------- | ------------------------------------------------------------------------------ | --------------------------------------------------- |
+| `loadFn`  | (`key`) => `Promise`\<`TValue` \| `undefined`\>                                | Async loader invoked on cache misses.               |
+| `options` | [`IRedisLayeredCacheOptions`](Interface.IRedisLayeredCacheOptions)\<`TValue`\> | Redis connection and cache behaviour configuration. |
+
+#### Returns
+
+`RedisLayeredCache`\<`TKey`, `TValue`\>
+
+## Methods
+
+### get()
+
+```ts
+get(key): TValue | undefined;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:126](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L126)
+
+Not supported — Redis is inherently asynchronous.
+
+#### Parameters
+
+| Parameter | Type   |
+| --------- | ------ |
+| `key`     | `TKey` |
+
+#### Returns
+
+`TValue` \| `undefined`
+
+#### Throws
+
+Always throws. Use [getAsync](#getasync) instead.
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`get`](Interface.ILayeredCache#get)
+
+---
+
+### getAsync()
+
+```ts
+getAsync(key): Promise<TValue | undefined>;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:131](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L131)
+
+Retrieves a value from the cache asynchronously.
+
+#### Parameters
+
+| Parameter | Type   | Description          |
+| --------- | ------ | -------------------- |
+| `key`     | `TKey` | The key to retrieve. |
+
+#### Returns
+
+`Promise`\<`TValue` \| `undefined`\>
+
+A promise resolving to the cached value or `undefined` on a miss.
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`getAsync`](Interface.ILayeredCache#getasync)
+
+---
+
+### invalidate()
+
+```ts
+invalidate(key): void;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:188](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L188)
+
+Not supported — Redis is inherently asynchronous.
+
+#### Parameters
+
+| Parameter | Type   |
+| --------- | ------ |
+| `key`     | `TKey` |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+Always throws. Use [invalidateAsync](#invalidateasync) instead.
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`invalidate`](Interface.ILayeredCache#invalidate)
+
+---
+
+### invalidateAsync()
+
+```ts
+invalidateAsync(key): Promise<void>;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:193](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L193)
+
+Invalidates a key in the cache asynchronously.
+
+#### Parameters
+
+| Parameter | Type   | Description            |
+| --------- | ------ | ---------------------- |
+| `key`     | `TKey` | The key to invalidate. |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`invalidateAsync`](Interface.ILayeredCache#invalidateasync)
+
+---
+
+### onModuleDestroy()
+
+```ts
+onModuleDestroy(): Promise<void>;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:214](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L214)
+
+Gracefully disconnects the Redis client when the NestJS module is destroyed.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+```ts
+OnModuleDestroy.onModuleDestroy;
+```
+
+---
+
+### set()
+
+```ts
+set(key, value): void;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:162](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L162)
+
+Not supported — Redis is inherently asynchronous.
+
+#### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `key`     | `TKey`   |
+| `value`   | `TValue` |
+
+#### Returns
+
+`void`
+
+#### Throws
+
+Always throws. Use [setAsync](#setasync) instead.
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`set`](Interface.ILayeredCache#set)
+
+---
+
+### setAsync()
+
+```ts
+setAsync(key, value): Promise<void>;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:167](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L167)
+
+Stores a value in the cache asynchronously.
+
+#### Parameters
+
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `key`     | `TKey`   | The key to store.   |
+| `value`   | `TValue` | The value to store. |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`setAsync`](Interface.ILayeredCache#setasync)
+
+---
+
+### stats()
+
+```ts
+stats(): ICacheStats;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:202](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L202)
+
+Returns current cache statistics.
+
+#### Returns
+
+[`ICacheStats`](Interface.ICacheStats)
+
+The cache statistics snapshot.
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`stats`](Interface.ILayeredCache#stats)
+
+---
+
+### warm()
+
+```ts
+warm(key): Promise<TValue | undefined>;
+```
+
+Defined in: [redis/RedisLayeredCache.ts:179](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-caching/src/redis/RedisLayeredCache.ts#L179)
+
+Proactively warms the cache for a given key.
+
+#### Parameters
+
+| Parameter | Type   | Description      |
+| --------- | ------ | ---------------- |
+| `key`     | `TKey` | The key to warm. |
+
+#### Returns
+
+`Promise`\<`TValue` \| `undefined`\>
+
+The value that was loaded and cached, or `undefined` if not found.
+
+#### Implementation of
+
+[`ILayeredCache`](Interface.ILayeredCache).[`warm`](Interface.ILayeredCache#warm)