@biggora/claude-plugins 1.2.2 → 1.3.0

package/src/skills/nest-best-practices/references/techniques-fastify.md

@@ -0,0 +1,137 @@
+---
+name: fastify
+description: Using Fastify as the HTTP adapter for better performance
+---
+
+# Fastify (Performance)
+
+Fastify is a high-performance alternative to Express, achieving nearly 2x better benchmark results.
+
+## Installation
+
+```bash
+npm install @nestjs/platform-fastify
+```
+
+## Setup
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import {
+  FastifyAdapter,
+  NestFastifyApplication,
+} from '@nestjs/platform-fastify';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter(),
+  );
+  
+  // Fastify listens only on localhost by default
+  await app.listen(3000, '0.0.0.0');
+}
+bootstrap();
+```
+
+## Fastify Options
+
+```typescript
+new FastifyAdapter({
+  logger: true,
+  trustProxy: true,
+});
+```
+
+## Middleware Differences
+
+Fastify middleware receives raw `req` and `res` objects:
+
+```typescript
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { FastifyRequest, FastifyReply } from 'fastify';
+
+@Injectable()
+export class LoggerMiddleware implements NestMiddleware {
+  use(req: FastifyRequest['raw'], res: FastifyReply['raw'], next: () => void) {
+    console.log('Request...');
+    next();
+  }
+}
+```
+
+## Redirect Response
+
+```typescript
+@Get()
+redirect(@Res() res: FastifyReply) {
+  res.status(302).redirect('/login');
+}
+```
+
+## Route Config
+
+```typescript
+import { RouteConfig } from '@nestjs/platform-fastify';
+
+@RouteConfig({ output: 'hello world' })
+@Get()
+index(@Req() req: FastifyRequest) {
+  return req.routeConfig.output;
+}
+```
+
+## Route Constraints
+
+```typescript
+import { RouteConstraints } from '@nestjs/platform-fastify';
+
+@RouteConstraints({ version: '1.2.x' })
+@Get()
+newFeature() {
+  return 'Works only for version >= 1.2.x';
+}
+```
+
+## Registering Plugins
+
+```typescript
+import compression from '@fastify/compress';
+import helmet from '@fastify/helmet';
+import fastifyCookie from '@fastify/cookie';
+
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter(),
+);
+
+await app.register(compression);
+await app.register(helmet);
+await app.register(fastifyCookie, { secret: 'my-secret' });
+```
+
+## Platform-Specific Packages
+
+When using Fastify, replace Express packages with Fastify equivalents:
+
+| Express | Fastify |
+|---------|---------|
+| `express-session` | `@fastify/secure-session` |
+| `cookie-parser` | `@fastify/cookie` |
+| `compression` | `@fastify/compress` |
+| `helmet` | `@fastify/helmet` |
+| `multer` | Not compatible |
+
+## Key Points
+
+- Provides significant performance improvements
+- Not all Express middleware is compatible
+- Use `NestFastifyApplication` type for proper typings
+- Default listener is `localhost` only (specify `0.0.0.0` for external access)
+- File upload (multer) is not compatible with Fastify
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/performance
+-->

package/src/skills/nest-best-practices/references/techniques-file-upload.md

@@ -0,0 +1,140 @@
+---
+name: file-upload
+description: File upload handling with multer integration
+---
+
+# File Upload
+
+NestJS uses [multer](https://github.com/expressjs/multer) middleware for handling `multipart/form-data` file uploads.
+
+## Installation
+
+```bash
+npm i -D @types/multer
+```
+
+## Single File Upload
+
+```typescript
+import { Controller, Post, UseInterceptors, UploadedFile } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { Express } from 'express';
+
+@Controller('upload')
+export class UploadController {
+  @Post()
+  @UseInterceptors(FileInterceptor('file'))
+  uploadFile(@UploadedFile() file: Express.Multer.File) {
+    console.log(file);
+    return { filename: file.originalname };
+  }
+}
+```
+
+## File Validation
+
+Use `ParseFilePipe` with built-in validators:
+
+```typescript
+@Post()
+uploadFile(
+  @UploadedFile(
+    new ParseFilePipe({
+      validators: [
+        new MaxFileSizeValidator({ maxSize: 1000000 }), // 1MB
+        new FileTypeValidator({ fileType: 'image/jpeg' }),
+      ],
+    }),
+  )
+  file: Express.Multer.File,
+) {
+  return { filename: file.originalname };
+}
+```
+
+Using builder pattern:
+
+```typescript
+@UploadedFile(
+  new ParseFilePipeBuilder()
+    .addFileTypeValidator({ fileType: 'jpeg' })
+    .addMaxSizeValidator({ maxSize: 1000000 })
+    .build({ errorHttpStatusCode: HttpStatus.UNPROCESSABLE_ENTITY }),
+)
+file: Express.Multer.File,
+```
+
+## Multiple Files (Same Field)
+
+```typescript
+@Post('uploads')
+@UseInterceptors(FilesInterceptor('files', 10)) // max 10 files
+uploadFiles(@UploadedFiles() files: Array<Express.Multer.File>) {
+  return files.map(f => f.originalname);
+}
+```
+
+## Multiple Files (Different Fields)
+
+```typescript
+@Post('uploads')
+@UseInterceptors(FileFieldsInterceptor([
+  { name: 'avatar', maxCount: 1 },
+  { name: 'background', maxCount: 1 },
+]))
+uploadFiles(
+  @UploadedFiles() files: {
+    avatar?: Express.Multer.File[],
+    background?: Express.Multer.File[]
+  },
+) {
+  return { avatar: files.avatar?.[0], background: files.background?.[0] };
+}
+```
+
+## Any Files
+
+```typescript
+@Post('any')
+@UseInterceptors(AnyFilesInterceptor())
+uploadAny(@UploadedFiles() files: Array<Express.Multer.File>) {
+  return files;
+}
+```
+
+## Configure Destination
+
+```typescript
+import { MulterModule } from '@nestjs/platform-express';
+
+@Module({
+  imports: [
+    MulterModule.register({ dest: './uploads' }),
+  ],
+})
+export class UploadModule {}
+```
+
+Async configuration:
+
+```typescript
+MulterModule.registerAsync({
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    dest: configService.get('UPLOAD_DEST'),
+  }),
+  inject: [ConfigService],
+});
+```
+
+## Key Points
+
+- `FileInterceptor` field name must match form field name
+- Not compatible with Fastify adapter
+- Use `fileIsRequired: false` for optional files
+- Multer only processes `multipart/form-data`
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/file-upload
+-->

package/src/skills/nest-best-practices/references/techniques-http-module.md

@@ -0,0 +1,176 @@
+---
+name: http-module
+description: Making HTTP requests with @nestjs/axios
+---
+
+# HTTP Module
+
+NestJS wraps Axios for making HTTP requests to external services.
+
+## Installation
+
+```bash
+npm install @nestjs/axios axios
+```
+
+## Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { HttpModule } from '@nestjs/axios';
+
+@Module({
+  imports: [HttpModule],
+  providers: [CatsService],
+})
+export class CatsModule {}
+```
+
+## Basic Usage
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { HttpService } from '@nestjs/axios';
+import { firstValueFrom } from 'rxjs';
+import { AxiosResponse } from 'axios';
+
+@Injectable()
+export class CatsService {
+  constructor(private readonly httpService: HttpService) {}
+
+  // Using Observable
+  findAll(): Observable<AxiosResponse<Cat[]>> {
+    return this.httpService.get('https://api.example.com/cats');
+  }
+
+  // Using Promise
+  async findAllAsync(): Promise<Cat[]> {
+    const { data } = await firstValueFrom(
+      this.httpService.get<Cat[]>('https://api.example.com/cats'),
+    );
+    return data;
+  }
+}
+```
+
+## HTTP Methods
+
+```typescript
+// GET
+this.httpService.get('/users');
+
+// POST
+this.httpService.post('/users', { name: 'John' });
+
+// PUT
+this.httpService.put('/users/1', { name: 'Jane' });
+
+// PATCH
+this.httpService.patch('/users/1', { name: 'Jane' });
+
+// DELETE
+this.httpService.delete('/users/1');
+```
+
+## Configuration
+
+```typescript
+HttpModule.register({
+  timeout: 5000,
+  maxRedirects: 5,
+  baseURL: 'https://api.example.com',
+  headers: {
+    'Authorization': 'Bearer token',
+  },
+});
+```
+
+## Async Configuration
+
+```typescript
+HttpModule.registerAsync({
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    timeout: configService.get('HTTP_TIMEOUT'),
+    maxRedirects: configService.get('HTTP_MAX_REDIRECTS'),
+    baseURL: configService.get('API_URL'),
+  }),
+  inject: [ConfigService],
+});
+```
+
+## Error Handling
+
+```typescript
+import { catchError, firstValueFrom } from 'rxjs';
+import { AxiosError } from 'axios';
+
+async findAll(): Promise<Cat[]> {
+  const { data } = await firstValueFrom(
+    this.httpService.get<Cat[]>('/cats').pipe(
+      catchError((error: AxiosError) => {
+        this.logger.error(error.response?.data);
+        throw new HttpException(
+          'External API error',
+          HttpStatus.BAD_GATEWAY,
+        );
+      }),
+    ),
+  );
+  return data;
+}
+```
+
+## Direct Axios Access
+
+Access the underlying Axios instance:
+
+```typescript
+@Injectable()
+export class CatsService {
+  constructor(private readonly httpService: HttpService) {}
+
+  async findAll(): Promise<Cat[]> {
+    const { data } = await this.httpService.axiosRef.get('/cats');
+    return data;
+  }
+}
+```
+
+## Interceptors
+
+Add Axios interceptors:
+
+```typescript
+@Injectable()
+export class CatsService implements OnModuleInit {
+  constructor(private readonly httpService: HttpService) {}
+
+  onModuleInit() {
+    this.httpService.axiosRef.interceptors.request.use((config) => {
+      config.headers['X-Request-Id'] = uuid();
+      return config;
+    });
+
+    this.httpService.axiosRef.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        // Log error
+        return Promise.reject(error);
+      },
+    );
+  }
+}
+```
+
+## Key Points
+
+- Returns RxJS Observables by default
+- Use `firstValueFrom` or `lastValueFrom` for Promises
+- `AxiosResponse` is from `axios` package
+- Configuration passed directly to Axios constructor
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/http-module
+-->

package/src/skills/nest-best-practices/references/techniques-logging.md

@@ -0,0 +1,146 @@
+---
+name: logging
+description: Built-in logger, custom loggers, and JSON logging
+---
+
+# Logging
+
+NestJS provides a built-in `Logger` class with customizable behavior.
+
+## Basic Usage
+
+```typescript
+import { Logger, Injectable } from '@nestjs/common';
+
+@Injectable()
+export class CatsService {
+  private readonly logger = new Logger(CatsService.name);
+
+  findAll() {
+    this.logger.log('Finding all cats');
+    this.logger.warn('Warning message');
+    this.logger.error('Error message', error.stack);
+    this.logger.debug('Debug info');
+    this.logger.verbose('Verbose output');
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+const app = await NestFactory.create(AppModule, {
+  logger: new ConsoleLogger({
+    logLevels: ['error', 'warn', 'log'],  // Filter log levels
+    timestamp: true,                       // Show timestamps
+    json: true,                           // JSON format output
+    colors: false,                        // Disable colors
+    prefix: 'MyApp',                      // Custom prefix
+  }),
+});
+```
+
+Disable logging:
+
+```typescript
+const app = await NestFactory.create(AppModule, { logger: false });
+```
+
+Specific log levels only:
+
+```typescript
+const app = await NestFactory.create(AppModule, {
+  logger: ['error', 'warn'],
+});
+```
+
+## JSON Logging
+
+Enable structured JSON logging for production:
+
+```typescript
+const app = await NestFactory.create(AppModule, {
+  logger: new ConsoleLogger({ json: true }),
+});
+```
+
+Output:
+
+```json
+{
+  "level": "log",
+  "pid": 19096,
+  "timestamp": 1607370779834,
+  "message": "Starting Nest application...",
+  "context": "NestFactory"
+}
+```
+
+## Custom Logger
+
+Implement `LoggerService` interface:
+
+```typescript
+import { LoggerService, Injectable } from '@nestjs/common';
+
+@Injectable()
+export class MyLogger implements LoggerService {
+  log(message: any, ...optionalParams: any[]) {}
+  error(message: any, ...optionalParams: any[]) {}
+  warn(message: any, ...optionalParams: any[]) {}
+  debug?(message: any, ...optionalParams: any[]) {}
+  verbose?(message: any, ...optionalParams: any[]) {}
+}
+```
+
+## Extend Built-in Logger
+
+```typescript
+import { ConsoleLogger } from '@nestjs/common';
+
+export class MyLogger extends ConsoleLogger {
+  error(message: any, stack?: string, context?: string) {
+    // Custom logic (e.g., send to external service)
+    super.error(message, stack, context);
+  }
+}
+```
+
+## Dependency Injection
+
+Use DI for custom logger with configuration:
+
+```typescript
+// Create LoggerModule
+@Module({
+  providers: [MyLogger],
+  exports: [MyLogger],
+})
+export class LoggerModule {}
+
+// Use in main.ts
+const app = await NestFactory.create(AppModule, { bufferLogs: true });
+app.useLogger(app.get(MyLogger));
+```
+
+## Transient Logger
+
+For unique logger instances per service:
+
+```typescript
+@Injectable({ scope: Scope.TRANSIENT })
+export class MyLogger extends ConsoleLogger {}
+
+// Usage
+@Injectable()
+export class CatsService {
+  constructor(private myLogger: MyLogger) {
+    this.myLogger.setContext('CatsService');
+  }
+}
+```
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/logger
+-->