@biggora/claude-plugins 1.2.2 → 1.3.1

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

@@ -0,0 +1,163 @@
+---
+name: events
+description: Event-driven architecture with @nestjs/event-emitter
+---
+
+# Events
+
+The `@nestjs/event-emitter` package provides event-driven architecture for decoupled application design.
+
+## Installation
+
+```bash
+npm install @nestjs/event-emitter
+```
+
+## Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { EventEmitterModule } from '@nestjs/event-emitter';
+
+@Module({
+  imports: [EventEmitterModule.forRoot()],
+})
+export class AppModule {}
+```
+
+## Dispatching Events
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+
+@Injectable()
+export class OrdersService {
+  constructor(private eventEmitter: EventEmitter2) {}
+
+  createOrder(data: CreateOrderDto) {
+    const order = this.ordersRepository.create(data);
+    
+    this.eventEmitter.emit('order.created', new OrderCreatedEvent({
+      orderId: order.id,
+      userId: data.userId,
+    }));
+
+    return order;
+  }
+}
+```
+
+## Listening to Events
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+
+@Injectable()
+export class NotificationsListener {
+  @OnEvent('order.created')
+  handleOrderCreated(event: OrderCreatedEvent) {
+    // Send notification to user
+    console.log(`Order ${event.orderId} created`);
+  }
+
+  @OnEvent('order.created', { async: true })
+  async sendEmailNotification(event: OrderCreatedEvent) {
+    await this.emailService.send(event);
+  }
+}
+```
+
+## Wildcard Listeners
+
+Enable wildcards in configuration:
+
+```typescript
+EventEmitterModule.forRoot({
+  wildcard: true,
+  delimiter: '.',
+})
+```
+
+Use wildcards:
+
+```typescript
+@OnEvent('order.*')
+handleAllOrderEvents(event: any) {
+  // Handles order.created, order.updated, order.shipped, etc.
+}
+
+@OnEvent('**')
+handleAllEvents(event: any) {
+  // Handles all events
+}
+```
+
+## Configuration Options
+
+```typescript
+EventEmitterModule.forRoot({
+  wildcard: false,              // Enable wildcard patterns
+  delimiter: '.',               // Namespace delimiter
+  newListener: false,           // Emit newListener event
+  removeListener: false,        // Emit removeListener event
+  maxListeners: 10,            // Max listeners per event
+  verboseMemoryLeak: false,    // Show event name in leak warning
+  ignoreErrors: false,         // Don't throw on unhandled errors
+});
+```
+
+## Listener Options
+
+```typescript
+@OnEvent('order.created', {
+  async: true,          // Handle asynchronously
+  prependListener: true, // Add to beginning of listener array
+  suppressErrors: true,  // Don't throw errors
+})
+handleOrderCreated(event: OrderCreatedEvent) {}
+```
+
+## Event Class Pattern
+
+```typescript
+export class OrderCreatedEvent {
+  constructor(
+    public readonly orderId: string,
+    public readonly userId: string,
+    public readonly createdAt: Date = new Date(),
+  ) {}
+}
+```
+
+## Preventing Event Loss
+
+Events emitted before `onApplicationBootstrap` may be missed:
+
+```typescript
+@Injectable()
+export class MyService implements OnApplicationBootstrap {
+  constructor(
+    private eventEmitter: EventEmitter2,
+    private eventEmitterReadinessWatcher: EventEmitterReadinessWatcher,
+  ) {}
+
+  async onApplicationBootstrap() {
+    await this.eventEmitterReadinessWatcher.waitUntilReady();
+    this.eventEmitter.emit('app.ready', {});
+  }
+}
+```
+
+## Key Points
+
+- Event subscribers cannot be request-scoped
+- Multiple listeners can subscribe to the same event
+- Events are great for decoupling modules
+- Use async: true for non-blocking event handling
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/events
+-->

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
+-->