@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/nestjs/observability/references/logging-metrics.md

@@ -0,0 +1,175 @@
+# NestJS Logging & Metrics
+
+## Built-in Logger
+
+```typescript
+import { Logger, Injectable } from '@nestjs/common';
+
+@Injectable()
+export class UsersService {
+  private readonly logger = new Logger(UsersService.name);
+
+  async findOne(id: string) {
+    this.logger.log(`Finding user ${id}`);
+    this.logger.debug('Debug info');
+    this.logger.warn('Warning message');
+    this.logger.error('Error occurred', error.stack);
+    
+    return user;
+  }
+}
+```
+
+## Custom Logger
+
+```typescript
+import { LoggerService } from '@nestjs/common';
+import * as winston from 'winston';
+
+export class WinstonLogger implements LoggerService {
+  private logger: winston.Logger;
+
+  constructor() {
+    this.logger = winston.createLogger({
+      level: 'info',
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.json(),
+      ),
+      transports: [
+        new winston.transports.Console(),
+        new winston.transports.File({ filename: 'app.log' }),
+      ],
+    });
+  }
+
+  log(message: string, context?: string) {
+    this.logger.info(message, { context });
+  }
+
+  error(message: string, trace?: string, context?: string) {
+    this.logger.error(message, { trace, context });
+  }
+
+  warn(message: string, context?: string) {
+    this.logger.warn(message, { context });
+  }
+}
+
+// main.ts
+const app = await NestFactory.create(AppModule, {
+  logger: new WinstonLogger(),
+});
+```
+
+## Request Logging Middleware
+
+```typescript
+@Injectable()
+export class LoggingMiddleware implements NestMiddleware {
+  private readonly logger = new Logger('HTTP');
+
+  use(req: Request, res: Response, next: NextFunction) {
+    const { method, originalUrl } = req;
+    const requestId = req.headers['x-request-id'] || uuid();
+    
+    const start = Date.now();
+    
+    res.on('finish', () => {
+      const duration = Date.now() - start;
+      this.logger.log(
+        `${method} ${originalUrl} ${res.statusCode} ${duration}ms`,
+        { requestId },
+      );
+    });
+    
+    next();
+  }
+}
+```
+
+## Health Checks
+
+```typescript
+import { TerminusModule, HealthCheckService, HttpHealthIndicator, TypeOrmHealthIndicator } from '@nestjs/terminus';
+
+@Controller('health')
+export class HealthController {
+  constructor(
+    private health: HealthCheckService,
+    private http: HttpHealthIndicator,
+    private db: TypeOrmHealthIndicator,
+  ) {}
+
+  @Get()
+  check() {
+    return this.health.check([
+      () => this.db.pingCheck('database'),
+      () => this.http.pingCheck('api', 'https://api.example.com'),
+    ]);
+  }
+
+  @Get('liveness')
+  liveness() {
+    return { status: 'ok' };
+  }
+
+  @Get('readiness')
+  readiness() {
+    return this.health.check([
+      () => this.db.pingCheck('database'),
+    ]);
+  }
+}
+```
+
+## Prometheus Metrics
+
+```typescript
+import { PrometheusModule, makeCounterProvider, makeHistogramProvider } from '@willsoto/nestjs-prometheus';
+
+@Module({
+  imports: [
+    PrometheusModule.register({
+      path: '/metrics',
+      defaultMetrics: { enabled: true },
+    }),
+  ],
+  providers: [
+    makeCounterProvider({
+      name: 'http_requests_total',
+      help: 'Total HTTP requests',
+      labelNames: ['method', 'path', 'status'],
+    }),
+    makeHistogramProvider({
+      name: 'http_request_duration_seconds',
+      help: 'HTTP request duration',
+      labelNames: ['method', 'path'],
+      buckets: [0.1, 0.5, 1, 2, 5],
+    }),
+  ],
+})
+export class MetricsModule {}
+
+// Usage in interceptor
+@Injectable()
+export class MetricsInterceptor implements NestInterceptor {
+  constructor(
+    @InjectMetric('http_requests_total') private counter: Counter,
+    @InjectMetric('http_request_duration_seconds') private histogram: Histogram,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler) {
+    const req = context.switchToHttp().getRequest();
+    const start = Date.now();
+
+    return next.handle().pipe(
+      tap(() => {
+        const duration = (Date.now() - start) / 1000;
+        this.counter.inc({ method: req.method, path: req.path, status: 200 });
+        this.histogram.observe({ method: req.method, path: req.path }, duration);
+      }),
+    );
+  }
+}
+```

package/rules/nestjs/performance/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: NestJS Performance
+description: Fastify adapter, Scope management, and Compression.
+metadata:
+  labels: [nestjs, performance, fastify]
+  triggers:
+    files: ['main.ts']
+    keywords: [FastifyAdapter, compression, SINGLETON, REQUEST scope]
+---
+
+# Performance Tuning
+
+## Network & Runtime
+
+- **Adapter**: Use `FastifyAdapter` instead of Express (2x throughput).
+- **Compression**: Enable Gzip/Brotli compression.
+
+  ```typescript
+  // main.ts
+  app.use(compression());
+  ```
+
+- **Keep-Alive**: Configure `http.Agent` keep-alive settings to reuse TCP connections for upstream services.
+
+## Scope & Dependency Injection
+
+- **Default Scope**: Adhere to `SINGLETON` scope (default).
+- **Request Scope**: AVOID `REQUEST` scope unless absolutely necessary.
+  - **Pro Tip**: A single request-scoped service makes its entire injection chain request-scoped.
+  - **Solution**: Use **Durable Providers** (`durable: true`) for multi-tenancy.
+- **Lazy Loading**: Use `LazyModuleLoader` for heavyweight modules (e.g., Admin panels).
+
+## Caching Strategy
+
+- **Application Cache**: Use `@nestjs/cache-manager` for computation results.
+  - **Deep Dive**: See **[Caching & Redis](../caching/SKILL.md)** for L1/L2 strategies and Invalidation patterns.
+- **HTTP Cache**: Set `Cache-Control` headers for client-side caching (CDN/Browser).
+- **Distributed**: In microservices, use Redis store, not memory store.
+
+## Queues & Async Processing
+
+- **Offloading**: Never block the HTTP request for long-running tasks (Emails, Reports, webhooks).
+- **Tool**: Use `@nestjs/bull` (BullMQ) or RabbitMQ (`@nestjs/microservices`).
+  - **Pattern**: Producer (Controller) -> Queue -> Consumer (Processor).
+
+## Serialization
+
+- **Warning**: `class-transformer` is CPU expensive.
+- **Optimization**: For high-throughput READ endpoints, consider manual mapping or using `fast-json-stringify` (built-in fastify serialization) instead of interceptors.
+
+## Database Tuning
+
+- **Projections**: Always use `select: []` to fetch only needed columns.
+- **N+1**: Prevent N+1 queries by using `relations` carefully or `DataLoader` for Graph/Field resolvers.
+- **Connection Pooling**: Configure pool size (e.g., `pool: { min: 2, max: 10 }`) in config to match DB limits.
+
+## Profiling & Scaling
+
+- **Offloading**: Move CPU-heavy tasks (Image processing, Crypto) to `worker_threads`.
+- **Clustering**: For non-containerized environments, use `ClusterModule` to utilize all CPU cores. In K8s, prefer ReplicaSets.

package/rules/nestjs/performance/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Performance References
+
+## References
+
+- [**Performance Patterns**](performance-patterns.md) - Caching, compression, clustering
+
+## Quick Checks
+
+- [ ] Enable compression middleware
+- [ ] Use caching strategically
+- [ ] Implement request/response interceptors
+- [ ] Enable clustering for multi-core
+- [ ] Profile and optimize hot paths

package/rules/nestjs/performance/references/performance-patterns.md

@@ -0,0 +1,107 @@
+# NestJS Performance Patterns
+
+## Compression
+
+```typescript
+import compression from 'compression';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.use(compression());
+  await app.listen(3000);
+}
+```
+
+## Response Caching Interceptor
+
+```typescript
+import { CacheInterceptor, CacheKey, CacheTTL } from '@nestjs/cache-manager';
+
+@Controller('products')
+@UseInterceptors(CacheInterceptor)
+export class ProductsController {
+  @Get()
+  @CacheKey('all-products')
+  @CacheTTL(300) // 5 minutes
+  findAll() {
+    return this.productsService.findAll();
+  }
+}
+```
+
+## Request Timeout
+
+```typescript
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { timeout } from 'rxjs/operators';
+
+@Injectable()
+export class TimeoutInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler) {
+    return next.handle().pipe(timeout(5000));
+  }
+}
+```
+
+## Database Query Optimization
+
+```typescript
+@Injectable()
+export class UsersService {
+  // Pagination
+  async findAll(page = 1, limit = 20) {
+    return this.userRepo.find({
+      skip: (page - 1) * limit,
+      take: limit,
+      select: ['id', 'name', 'email'], // Select only needed fields
+    });
+  }
+
+  // Eager loading
+  async findWithOrders(id: string) {
+    return this.userRepo.findOne({
+      where: { id },
+      relations: ['orders', 'orders.items'],
+    });
+  }
+}
+```
+
+## Clustering
+
+```typescript
+// main.ts
+import cluster from 'cluster';
+import os from 'os';
+
+if (cluster.isPrimary) {
+  const numCPUs = os.cpus().length;
+  for (let i = 0; i < numCPUs; i++) {
+    cluster.fork();
+  }
+  cluster.on('exit', (worker) => {
+    console.log(`Worker ${worker.process.pid} died`);
+    cluster.fork();
+  });
+} else {
+  bootstrap();
+}
+```
+
+## Lazy Loading Modules
+
+```typescript
+@Module({})
+export class AppModule {
+  static forRoot(): DynamicModule {
+    return {
+      module: AppModule,
+      imports: [
+        LazyModuleLoader.forFeature([
+          () => import('./reports/reports.module').then(m => m.ReportsModule),
+        ]),
+      ],
+    };
+  }
+}
+```

package/rules/nestjs/real-time/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: NestJS Real-Time
+description: WebSocket and SSE selection strategies and scaling.
+metadata:
+  labels: [nestjs, websockets, sse, socket.io]
+  triggers:
+    files: ['**/*.gateway.ts', '**/*.controller.ts']
+    keywords: [WebSocketGateway, SubscribeMessage, Sse, Socket.io]
+---
+
+# Real-Time & WebSockets
+
+## Selection Strategy (Critical)
+
+- **WebSockets (Bi-directional)**: Use for Chat, Multiplayer Games, Collaborative Editing.
+  - _High Complexity_: Requires custom scaling (Redis Adapter) and sticky sessions (sometimes).
+- **Server-Sent Events (SSE) (Uni-directional)**: Use for Notifications, Live Feeds, Tickers, CI Log streaming.
+  - _Low Complexity_: Standard HTTP. Works with standard Load Balancers. Easy to secure.
+  - _NestJS_: Use `@Sse('route')` returning `Observable<MessageEvent>`.
+- **Long Polling**: Use **only** as a fallback or for extremely low-frequency updates (e.g., job status check every 10m).
+  - _Impact_: High header overhead. Blocks threads if not handled carefully.
+
+## WebSockets Implementation
+
+- **Socket.io**: Default choice. Features "Rooms", "Namespaces", and automatic reconnection. Heavy protocol.
+- **Fastify/WS**: Use `ws` adapter if performance is critical (e.g., high-frequency trading updates) and you don't need "Rooms" logic.
+
+## Scaling (Critical)
+
+- **WebSockets**: In K8s, a client connects to Pod A. If Pod B emits an event, the client won't receive it.
+  - **Solution**: **Redis Adapter** (`@socket.io/redis-adapter`). Every pod publishes to Redis; Redis distributes to all other pods.
+- **SSE**: Stateless. No special adapter needed, but be aware of **Connection Limits** (6 concurrent connections per domain in HTTP/1.1; virtually unlimited in HTTP/2).
+  - **Rule**: Must use **HTTP/2** for SSE at scale.
+
+## Security
+
+- **Handshake Auth**: Standard HTTP Guards don't trigger on Ws connection efficiently.
+  - **Pattern**: Validate JWT during the `handleConnection()` lifecycle method. Disconnect immediately if invalid.
+- **Rate Limiting**: Sockets are expensive. Apply strict throttling on "Message" events to prevent flooding.
+
+## Architecture
+
+- **Gateway != Service**: The `WebSocketGateway` should **only** handle client comms (Join Room, Ack message).
+  - **Rule**: Delegate business logic to a Service or Command Bus.
+- **Events**: Use `AsyncApi` or `SocketApi` decorators (from community packages) to document WS events similarly to OpenAPI.

package/rules/nestjs/real-time/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Real-time References
+
+## References
+
+- [**WebSocket Patterns**](websocket-patterns.md) - Gateways, events, rooms
+
+## Quick Checks
+
+- [ ] Use @WebSocketGateway decorator
+- [ ] Handle connection/disconnection
+- [ ] Rooms for grouped messaging
+- [ ] Authentication via handshake
+- [ ] Proper error handling

package/rules/nestjs/real-time/references/websocket-patterns.md

@@ -0,0 +1,121 @@
+# NestJS WebSocket Patterns
+
+## Gateway Setup
+
+```typescript
+import {
+  WebSocketGateway,
+  WebSocketServer,
+  SubscribeMessage,
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  ConnectedSocket,
+  MessageBody,
+} from '@nestjs/websockets';
+import { Server, Socket } from 'socket.io';
+
+@WebSocketGateway({
+  cors: { origin: '*' },
+  namespace: '/chat',
+})
+export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
+  @WebSocketServer()
+  server: Server;
+
+  handleConnection(client: Socket) {
+    console.log(`Client connected: ${client.id}`);
+  }
+
+  handleDisconnect(client: Socket) {
+    console.log(`Client disconnected: ${client.id}`);
+  }
+
+  @SubscribeMessage('message')
+  handleMessage(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() data: { room: string; message: string },
+  ) {
+    this.server.to(data.room).emit('message', {
+      sender: client.id,
+      message: data.message,
+    });
+  }
+
+  @SubscribeMessage('join')
+  handleJoin(
+    @ConnectedSocket() client: Socket,
+    @MessageBody() room: string,
+  ) {
+    client.join(room);
+    client.emit('joined', room);
+  }
+}
+```
+
+## Authentication
+
+```typescript
+@WebSocketGateway()
+export class AuthenticatedGateway implements OnGatewayConnection {
+  constructor(private authService: AuthService) {}
+
+  async handleConnection(client: Socket) {
+    try {
+      const token = client.handshake.auth.token;
+      const user = await this.authService.validateToken(token);
+      client.data.user = user;
+    } catch {
+      client.disconnect();
+    }
+  }
+
+  @SubscribeMessage('protected-event')
+  handleProtected(@ConnectedSocket() client: Socket) {
+    const user = client.data.user;
+    return { user: user.name };
+  }
+}
+```
+
+## Broadcasting
+
+```typescript
+@Injectable()
+export class NotificationsService {
+  constructor(
+    @Inject('CHAT_GATEWAY')
+    private gateway: ChatGateway,
+  ) {}
+
+  // Broadcast to all
+  broadcastToAll(event: string, data: any) {
+    this.gateway.server.emit(event, data);
+  }
+
+  // To specific room
+  broadcastToRoom(room: string, event: string, data: any) {
+    this.gateway.server.to(room).emit(event, data);
+  }
+
+  // To specific client
+  sendToClient(clientId: string, event: string, data: any) {
+    this.gateway.server.to(clientId).emit(event, data);
+  }
+}
+```
+
+## Module Setup
+
+```typescript
+@Module({
+  providers: [
+    ChatGateway,
+    {
+      provide: 'CHAT_GATEWAY',
+      useExisting: ChatGateway,
+    },
+  ],
+  exports: ['CHAT_GATEWAY'],
+})
+export class WebSocketModule {}
+```

package/rules/nestjs/scheduling/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: NestJS Scheduling
+description: Distributed cron jobs and locking patterns.
+metadata:
+  labels: [nestjs, cron, scheduling, redis]
+  triggers:
+    files: ['**/*.service.ts']
+    keywords: ["@Cron, CronExpression, ScheduleModule"]
+---
+
+# Task Scheduling & Jobs
+
+## Distributed Cron (Critical)
+
+- **Problem**: `@Cron()` runs on **every** instance. In K8s with 3 pods, your "Daily Report" runs 3 times.
+- **Solution**: **Distributed Locking** using Redis.
+  - **Pattern**: Using a decorator to wrap the cron method.
+  - **Logic**: `SET resource_name my_random_value NX PX 30000` (Redis Atomic Set).
+
+## Cron Decorator Pattern
+
+- **Implementation**:
+
+  ```typescript
+  @Cron(CronExpression.EVERY_MINUTE)
+  @DistributedLock({ key: 'send_emails', ttl: 5000 })
+  async handleCron() {
+    // Only runs if lock acquired
+  }
+  ```
+
+- **Tools**: Use `nestjs-redlock` or custom Redis wrapper via `redlock` library.
+
+## Job Robustness
+
+- **Isolation**: Never perform heavy processing inside the Cron handler.
+  - **Pattern**: Cron -> Push Job ID to Queue (BullMQ) -> Worker processes it.
+  - **Why**: Cron schedulers can get blocked by the Event Loop; Workers are scalable.
+- **Error Handling**: Wrap ALL cron logic in `try/catch`. Uncaught exceptions in a Cron job can crash the entire Node process.

package/rules/nestjs/scheduling/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Scheduling References
+
+## References
+
+- [**Scheduling Patterns**](scheduling-patterns.md) - Cron jobs, intervals, timeouts, queues
+
+## Quick Checks
+
+- [ ] Use @Cron for recurring tasks
+- [ ] Use queues for heavy background jobs
+- [ ] Handle job failures gracefully
+- [ ] Implement distributed locking for clusters
+- [ ] Monitor job execution times