@breadstone/archipel-mcp 0.0.11 → 0.0.14

package/data/guides/blob-storage.md

@@ -1,242 +0,0 @@
----
-title: Blob Storage
-description: Upload, download, and manage files with multi-provider blob storage using Vercel, Azure, AWS S3, or custom providers.
-order: 7
----
-
-# Blob Storage
-
-This guide covers file storage with `platform-blob-storage`: choosing a provider, uploading and downloading files, generating signed URLs, and optionally tracking file metadata with persistence ports.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-blob-storage
-```
-
----
-
-## Choose a Provider
-
-`platform-blob-storage` abstracts file operations behind a unified `BlobService`. You select the provider at module registration time. Supported providers:
-
-| Provider   | Kind constant              | When to use                                 |
-| ---------- | -------------------------- | ------------------------------------------- |
-| **Vercel** | `BlobProviderKinds.Vercel` | Vercel-hosted apps with Vercel Blob storage |
-| **Azure**  | `BlobProviderKinds.Azure`  | Azure Blob Storage accounts                 |
-| **AWS S3** | `BlobProviderKinds.AwsS3`  | Amazon S3 or S3-compatible providers        |
-| **Custom** | `BlobProviderKinds.Custom` | Your own storage backend                    |
-
----
-
-## Module Registration
-
-```typescript
-import { Module } from '@nestjs/common';
-import { BlobModule, BlobProviderKinds } from '@breadstone/archipel-platform-blob-storage';
-
-@Module({
-  imports: [
-    BlobModule.forRoot({
-      provider: {
-        kind: BlobProviderKinds.AwsS3,
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-Each provider reads its credentials from environment variables via the `ConfigModule`. Set the variables for your chosen provider:
-
-### AWS S3
-
-```env
-BLOB_AWS_REGION=eu-central-1
-BLOB_AWS_BUCKET=my-app-uploads
-BLOB_AWS_ACCESS_KEY_ID=AKIA...
-BLOB_AWS_SECRET_ACCESS_KEY=secret...
-```
-
-### Azure Blob Storage
-
-```env
-BLOB_AZURE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
-BLOB_AZURE_CONTAINER=uploads
-```
-
-### Vercel Blob
-
-```env
-BLOB_VERCEL_TOKEN=your-vercel-blob-token
-```
-
----
-
-## Uploading Files
-
-Inject `BlobService` to upload files. It returns metadata about the stored blob.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { BlobService } from '@breadstone/archipel-platform-blob-storage';
-
-@Injectable()
-export class AvatarService {
-  private readonly _blobService: BlobService;
-
-  constructor(blobService: BlobService) {
-    this._blobService = blobService;
-  }
-
-  public async uploadAvatar(userId: string, file: Buffer, mimeType: string): Promise<string> {
-    const result = await this._blobService.upload({
-      key: `avatars/${userId}`,
-      body: file,
-      contentType: mimeType,
-    });
-
-    return result.url;
-  }
-}
-```
-
-### Handling Multipart Uploads in Controllers
-
-For HTTP file uploads, use the `@UploadedFile()` decorator with Multer:
-
-```typescript
-import { Controller, Post, UploadedFile, UseGuards, UseInterceptors } from '@nestjs/common';
-import { FileInterceptor } from '@nestjs/platform-express';
-import { JwtAuthGuard, User, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
-
-@Controller('avatars')
-export class AvatarController {
-  private readonly _avatarService: AvatarService;
-
-  constructor(avatarService: AvatarService) {
-    this._avatarService = avatarService;
-  }
-
-  @Post()
-  @UseGuards(JwtAuthGuard)
-  @UseInterceptors(FileInterceptor('file'))
-  public async upload(@User() user: IAuthSubject, @UploadedFile() file: Express.Multer.File): Promise<{ url: string }> {
-    const url = await this._avatarService.uploadAvatar(user.id, file.buffer, file.mimetype);
-    return { url };
-  }
-}
-```
-
----
-
-## Downloading and Signed URLs
-
-```typescript
-// Download a blob
-const content = await this._blobService.download('avatars/user-123');
-
-// Generate a time-limited signed URL for direct client access
-const signedUrl = await this._blobService.getSignedUrl('avatars/user-123', {
-  expiresIn: 3600, // seconds
-});
-```
-
-Signed URLs are useful for serving private files directly to the client without proxying through your server.
-
----
-
-## Deleting Files
-
-```typescript
-await this._blobService.delete('avatars/user-123');
-```
-
----
-
-## Tracking Metadata (Optional Ports)
-
-By default, `BlobService` performs storage operations without persisting metadata to your database. If you need to track uploaded files (for listing, auditing, or cleanup), implement the optional persistence ports.
-
-### BlobObjectPersistencePort
-
-Tracks blob metadata after upload and deletion:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { BlobObjectPersistencePort } from '@breadstone/archipel-platform-blob-storage';
-import { PrismaService } from '@breadstone/archipel-platform-database';
-
-@Injectable()
-export class PrismaBlobObjectAdapter extends BlobObjectPersistencePort {
-  private readonly _prisma: PrismaService;
-
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-
-  public async onUploaded(key: string, url: string, contentType: string, size: number): Promise<void> {
-    await this._prisma.blobObject.upsert({
-      where: { key },
-      create: { key, url, contentType, size },
-      update: { url, contentType, size },
-    });
-  }
-
-  public async onDeleted(key: string): Promise<void> {
-    await this._prisma.blobObject.deleteMany({ where: { key } });
-  }
-}
-```
-
-### BlobVariantPersistencePort
-
-Tracks image variants (thumbnails, resized versions):
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { BlobVariantPersistencePort } from '@breadstone/archipel-platform-blob-storage';
-import { PrismaService } from '@breadstone/archipel-platform-database';
-
-@Injectable()
-export class PrismaBlobVariantAdapter extends BlobVariantPersistencePort {
-  private readonly _prisma: PrismaService;
-
-  constructor(prisma: PrismaService) {
-    super();
-    this._prisma = prisma;
-  }
-
-  public async onVariantCreated(originalKey: string, variantKey: string, width: number, height: number): Promise<void> {
-    await this._prisma.blobVariant.create({
-      data: { originalKey, variantKey, width, height },
-    });
-  }
-}
-```
-
-### Register with Persistence
-
-```typescript
-BlobModule.forRoot({
-  provider: { kind: BlobProviderKinds.AwsS3 },
-  objectPersistence: PrismaBlobObjectAdapter,
-  variantPersistence: PrismaBlobVariantAdapter,
-}),
-```
-
----
-
-## Health Checks
-
-`platform-blob-storage` registers a health indicator automatically. It verifies connectivity to the configured provider. The result is included in your `/health` endpoint if you use `platform-core`'s health module.
-
----
-
-## Next Steps
-
-- See the [Implementing Ports](/guides/implementing-ports) guide for the general port/adapter pattern
-- Browse the [platform-blob-storage API reference](/packages/platform-blob-storage/api/) for all method signatures

package/data/guides/caching.md

@@ -1,255 +0,0 @@
----
-title: Caching
-description: Add layered caching to your NestJS application with in-memory LRU and Redis-backed implementations, TTL expiration, stale-while-revalidate, and metrics.
-order: 16
----
-
-# Caching
-
-This guide covers layered caching with `platform-caching`: choosing between in-memory and Redis backends, configuring TTL and LRU eviction, using stale-while-revalidate for low-latency reads, and integrating cache metrics with your observability stack.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-caching
-```
-
-For Redis-backed caching, also install `ioredis`:
-
-```bash
-yarn add ioredis
-```
-
----
-
-## Concepts
-
-`platform-caching` provides a generic `ILayeredCache<TKey, TValue>` interface with two implementations:
-
-| Implementation       | Backend   | Sync support | Best for                                 |
-| -------------------- | --------- | ------------ | ---------------------------------------- |
-| `MemoryLayeredCache` | In-memory | Yes          | Single-instance apps, fast local lookups |
-| `RedisLayeredCache`  | Redis     | No (async)   | Multi-instance deployments, shared state |
-
-Both implementations use a **loader function** pattern: when a cache miss occurs, the cache automatically calls a user-provided async function to load the value, stores it, and returns it. This eliminates repetitive "check cache → miss → load → store" boilerplate.
-
----
-
-## In-Memory Cache
-
-### Basic Setup
-
-Create a `MemoryLayeredCache` with a loader function that fetches the value on cache misses:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { MemoryLayeredCache } from '@breadstone/archipel-platform-caching';
-
-@Injectable()
-export class ProductCacheService {
-  private readonly _cache: MemoryLayeredCache<string, IProduct>;
-
-  constructor(productRepository: ProductRepository) {
-    this._cache = new MemoryLayeredCache<string, IProduct>(async (productId: string) =>
-      productRepository.findById(productId),
-    );
-  }
-
-  public async getProduct(productId: string): Promise<IProduct | undefined> {
-    return this._cache.getAsync(productId);
-  }
-
-  public invalidateProduct(productId: string): void {
-    this._cache.invalidate(productId);
-  }
-}
-```
-
-### TTL Expiration
-
-Set a time-to-live so entries automatically expire:
-
-```typescript
-this._cache = new MemoryLayeredCache<string, IProduct>(
-  async (id) => productRepository.findById(id),
-  { ttlMs: 60_000 }, // entries expire after 60 seconds
-);
-```
-
-### LRU Eviction
-
-Limit the number of entries to prevent unbounded memory growth. The oldest entry (least recently used) is evicted first:
-
-```typescript
-this._cache = new MemoryLayeredCache<string, IProduct>(async (id) => productRepository.findById(id), {
-  ttlMs: 300_000, // 5-minute TTL
-  maxEntries: 1000, // keep at most 1000 entries
-});
-```
-
-### Stale-While-Revalidate
-
-Serve expired entries immediately while refreshing in the background. This keeps latency low for frequently accessed data:
-
-```typescript
-this._cache = new MemoryLayeredCache<string, IProduct>(async (id) => productRepository.findById(id), {
-  ttlMs: 30_000,
-  staleWhileRevalidate: true, // return stale value, refresh async
-});
-```
-
-> **When to use:** Quasi-static reference data (categories, feature flags, configuration). Avoid for personalized or rapidly changing data where freshness is critical.
-
-### Synchronous Access
-
-`MemoryLayeredCache` supports synchronous `get()` and `set()` for cases where you've pre-warmed the cache or need zero-await lookups:
-
-```typescript
-// Pre-warm on startup
-await this._cache.warm('featured-product');
-
-// Later: synchronous read (no await needed)
-const product = this._cache.get('featured-product');
-```
-
----
-
-## Redis Cache
-
-### Basic Setup
-
-`RedisLayeredCache` provides the same `ILayeredCache` interface but stores entries in Redis. Synchronous methods (`get`, `set`, `invalidate`) throw — use the async variants.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { RedisLayeredCache } from '@breadstone/archipel-platform-caching/redis';
-
-@Injectable()
-export class SessionCacheService {
-  private readonly _cache: RedisLayeredCache<string, ISessionData>;
-
-  constructor(sessionRepository: SessionRepository) {
-    this._cache = new RedisLayeredCache<string, ISessionData>(
-      async (sessionId) => sessionRepository.findById(sessionId),
-      {
-        url: process.env['REDIS_URL'] ?? 'redis://localhost:6379',
-        keyPrefix: 'session:',
-        ttlSeconds: 3600, // 1-hour TTL
-      },
-    );
-  }
-
-  public async getSession(sessionId: string): Promise<ISessionData | undefined> {
-    return this._cache.getAsync(sessionId);
-  }
-
-  public async invalidateSession(sessionId: string): Promise<void> {
-    await this._cache.invalidateAsync(sessionId);
-  }
-}
-```
-
-### Custom Serialization
-
-By default, values are serialized with `JSON.stringify` and deserialized with `JSON.parse`. Override this for custom formats:
-
-```typescript
-this._cache = new RedisLayeredCache<string, ISessionData>(async (id) => sessionRepository.findById(id), {
-  url: 'redis://localhost:6379',
-  keyPrefix: 'session:',
-  serialize: (value) => msgpack.encode(value).toString('base64'),
-  deserialize: (raw) => msgpack.decode(Buffer.from(raw, 'base64')) as ISessionData,
-});
-```
-
-### Graceful Shutdown
-
-`RedisLayeredCache` implements `OnModuleDestroy` and automatically disconnects the Redis client when the NestJS module is destroyed. No manual cleanup is needed.
-
----
-
-## Cache Metrics
-
-Both implementations accept an optional `ICacheMetricsRecorder` to forward cache statistics to your observability backend.
-
-### Implementing a Metrics Recorder
-
-```typescript
-import type { ICacheMetricsRecorder } from '@breadstone/archipel-platform-caching';
-import { TelemetryFacade } from '@breadstone/archipel-platform-telemetry';
-
-export class TelemetryCacheMetricsRecorder implements ICacheMetricsRecorder {
-  private readonly _telemetry: TelemetryFacade;
-
-  constructor(telemetry: TelemetryFacade) {
-    this._telemetry = telemetry;
-  }
-
-  public recordHit(cache: string): void {
-    this._telemetry.recordCounter('cache_hits_total', 1, { cache });
-  }
-
-  public recordMiss(cache: string): void {
-    this._telemetry.recordCounter('cache_misses_total', 1, { cache });
-  }
-
-  public recordLoadSuccess(cache: string): void {
-    this._telemetry.recordCounter('cache_load_success_total', 1, { cache });
-  }
-
-  public recordLoadError(cache: string): void {
-    this._telemetry.recordCounter('cache_load_error_total', 1, { cache });
-  }
-
-  public recordEviction(cache: string): void {
-    this._telemetry.recordCounter('cache_evictions_total', 1, { cache });
-  }
-}
-```
-
-### Wiring It Up
-
-Pass the recorder when creating the cache:
-
-```typescript
-this._cache = new MemoryLayeredCache<string, IProduct>(async (id) => productRepository.findById(id), {
-  ttlMs: 60_000,
-  maxEntries: 500,
-  metricsRecorder: new TelemetryCacheMetricsRecorder(telemetry),
-  cacheName: 'products',
-});
-```
-
-When no metrics recorder is provided, a `NoopCacheMetricsRecorder` is used automatically — no setup needed.
-
----
-
-## Cache Statistics
-
-Both implementations expose a `stats()` method returning a snapshot of cache performance:
-
-```typescript
-const stats = this._cache.stats();
-console.log(stats.hits); // total cache hits
-console.log(stats.misses); // total cache misses
-console.log(stats.loads); // successful loader invocations
-console.log(stats.loadErrors); // failed loader invocations
-console.log(stats.evictions); // LRU evictions (MemoryLayeredCache only)
-```
-
-Use this for health checks or debug endpoints.
-
----
-
-## Best Practices
-
-| Practice                                  | Why                                                                |
-| ----------------------------------------- | ------------------------------------------------------------------ |
-| Set `maxEntries` for in-memory caches     | Prevents unbounded memory growth in long-running processes         |
-| Use `staleWhileRevalidate` for read-heavy | Keeps p99 latency low for popular keys                             |
-| Invalidate on writes                      | Call `invalidate(key)` after mutations to avoid serving stale data |
-| Use `cacheName` labels                    | Makes metrics dashboards filterable by cache instance              |
-| Keep TTLs short for user-specific data    | Personalized data should not be stale for extended periods         |
-| Use Redis for multi-instance deployments  | In-memory caches are not shared across application instances       |