@breadstone/archipel-mcp 0.0.53 → 0.0.55

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

@@ -1,167 +0,0 @@
----
-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, health]
-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`
-
-<InstallTabs />
-
-## 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), {
-  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/redis`
-**SDK:** `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:
-
-```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.
-
----
-
-## Health Check
-
-The `CachingHealthIndicator` reports the caching subsystem as available. Import it from the `/health` subpath:
-
-```typescript
-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](./api/) for all exported types and classes.

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

@@ -1,226 +0,0 @@
----
-title: platform-configuration
-description: Type-safe configuration management with strategy-based resolution for NestJS applications.
-order: 2
-tags: [configuration, config, environment, dotenv, strategy-pattern]
-package: '@breadstone/archipel-platform-configuration'
----
-
-# platform-configuration
-
-Type-safe configuration management for NestJS applications. Provides compile-time safe config keys, a strategy-based resolution pattern (environment variables, `.env` files, or custom sources), a global NestJS module, and a central registry for config discovery and validation.
-
-> **Note:** This package was extracted from [`platform-core`](../platform-core/). Re-exports are still available from `platform-core` for backward compatibility.
-
-**Package:** `@breadstone/archipel-platform-configuration`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule, EnvironmentConfigStrategy } from '@breadstone/archipel-platform-configuration';
-
-@Module({
-  imports: [
-    ConfigModule.forRoot({
-      strategyFactory: () => new EnvironmentConfigStrategy(),
-    }),
-  ],
-})
-export class AppModule {}
-```
-
----
-
-## Config Keys
-
-Type-safe config keys encode both the key name and the expected value type at compile time. This eliminates scattered `process.env` access and provides IDE autocomplete, "find usages", and refactoring support.
-
-### Defining Config Keys
-
-```typescript
-import { createConfigKey } from '@breadstone/archipel-platform-configuration';
-
-export const DATABASE_URL = createConfigKey<string>('DATABASE_URL');
-export const CACHE_TTL = createConfigKey<number>('CACHE_TTL');
-export const FEATURE_ENABLED = createConfigKey<boolean>('FEATURE_ENABLED');
-```
-
-### IConfigKey Interface
-
-```typescript
-interface IConfigKey<TType = unknown> {
-  readonly _type?: TType; // Phantom type — compile-time only
-  readonly key: string; // The unique string identifier
-}
-```
-
----
-
-## ConfigModule
-
-### forRoot — Application Root
-
-Call once in the root module to bootstrap the global `ConfigService`.
-
-```typescript
-ConfigModule.forRoot({
-  strategyFactory: () => new EnvironmentConfigStrategy(),
-  statics: { APP_VERSION: '1.0.0' }, // optional static overrides
-});
-```
-
-### register — Library Modules
-
-Call in each library module to declare configuration dependencies.
-
-```typescript
-import { createConfigKey, type IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
-
-const SMTP_HOST = createConfigKey<string>('SMTP_HOST');
-const SMTP_PORT = createConfigKey<number>('SMTP_PORT');
-
-export const MAIL_CONFIG_ENTRIES: ReadonlyArray<IConfigRegistryEntry> = [
-  { key: SMTP_HOST, module: 'mailing', required: true, description: 'SMTP server hostname' },
-  { key: SMTP_PORT, module: 'mailing', required: false, defaultValue: 587, description: 'SMTP port' },
-];
-
-@Module({
-  imports: [ConfigModule.register('mailing', MAIL_CONFIG_ENTRIES)],
-})
-export class MailModule {}
-```
-
-### IConfigModuleOptions
-
-| Property          | Type                       | Description                                                    |
-| ----------------- | -------------------------- | -------------------------------------------------------------- |
-| `strategyFactory` | `() => ConfigStrategyBase` | Factory that creates the resolution strategy for config values |
-| `statics`         | `Record<string, string>`   | Optional key-value overrides injected at startup               |
-
----
-
-## ConfigService
-
-Injected globally after `ConfigModule.forRoot()`. Automatically parses raw string values into numbers, booleans, and null.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { ConfigService } from '@breadstone/archipel-platform-configuration';
-
-@Injectable()
-export class SmtpClient {
-  private readonly _host: string;
-  private readonly _port: number;
-
-  constructor(configService: ConfigService) {
-    this._host = configService.get<string>('SMTP_HOST');
-    this._port = configService.tryGet<number>('SMTP_PORT', 587);
-  }
-}
-```
-
-| Method                     | Description                                                           |
-| -------------------------- | --------------------------------------------------------------------- |
-| `get<T>(key)`              | Returns the parsed value. Throws `ConfigKeyNotFoundError` if missing. |
-| `tryGet<T>(key, fallback)` | Returns the parsed value, or `fallback` if the key is not set.        |
-| `has(key)`                 | Returns `true` if the key exists in the strategy.                     |
-
----
-
-## ConfigRegistry
-
-Static, global registry that collects all configuration keys registered by platform libraries. Enables a central overview of every environment variable the application depends on, grouped by source module.
-
-```typescript
-import { ConfigRegistry } from '@breadstone/archipel-platform-configuration';
-
-// All registered entries
-const all = ConfigRegistry.getAll();
-
-// Grouped by module
-const grouped = ConfigRegistry.getByModule();
-// Map { 'mailing' => [...], 'authentication' => [...] }
-```
-
----
-
-## Strategies
-
-### EnvironmentConfigStrategy
-
-Resolves values from `process.env`.
-
-```typescript
-import { EnvironmentConfigStrategy } from '@breadstone/archipel-platform-configuration';
-
-ConfigModule.forRoot({
-  strategyFactory: () => new EnvironmentConfigStrategy(),
-});
-```
-
-### FileConfigStrategy
-
-Resolves values from a `.env` file on disk using `dotenv`.
-
-```typescript
-import { FileConfigStrategy } from '@breadstone/archipel-platform-configuration';
-
-ConfigModule.forRoot({
-  strategyFactory: () => new FileConfigStrategy('.env'),
-});
-```
-
-### Custom Strategies
-
-Extend `ConfigStrategyBase` to implement custom resolution (e.g. Azure App Configuration, AWS Parameter Store).
-
-```typescript
-import { ConfigStrategyBase } from '@breadstone/archipel-platform-configuration';
-
-export class AzureAppConfigStrategy extends ConfigStrategyBase {
-  public initialize(): void {
-    // Connect to Azure App Configuration
-  }
-
-  public resolve<T>(key: string): T {
-    // Fetch from Azure
-  }
-
-  public tryResolve<T>(key: string, fallback: T): T {
-    // Attempt fetch, return fallback on miss
-  }
-
-  public has(key: string): boolean {
-    // Check existence
-  }
-}
-```
-
----
-
-## Error Handling
-
-| Error                    | Description                                                                         |
-| ------------------------ | ----------------------------------------------------------------------------------- |
-| `ConfigKeyNotFoundError` | Thrown when `get()` is called for a key that does not exist in the active strategy. |
-
----
-
-## Module Summary
-
-| Export                      | Type           | Description                                        |
-| --------------------------- | -------------- | -------------------------------------------------- |
-| `ConfigModule`              | NestJS Module  | Global configuration bootstrap and registration    |
-| `ConfigService`             | Service        | Type-safe config value access                      |
-| `ConfigRegistry`            | Static class   | Central registry of all registered config entries  |
-| `ConfigStrategyBase`        | Abstract class | Base class for configuration resolution strategies |
-| `EnvironmentConfigStrategy` | Strategy       | Resolves from `process.env`                        |
-| `FileConfigStrategy`        | Strategy       | Resolves from `.env` files via dotenv              |
-| `createConfigKey<T>()`      | Factory        | Creates a typed config key                         |
-| `IConfigKey<T>`             | Interface      | Typed config key contract                          |
-| `IConfigRegistryEntry<T>`   | Interface      | Registry entry with module, required, default      |
-| `IConfigModuleOptions`      | Interface      | Options for `ConfigModule.forRoot()`               |
-| `ConfigKeyNotFoundError`    | Error          | Thrown on missing required config keys             |