@biggora/claude-plugins 1.2.2 → 1.3.1

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

package/src/skills/nest-best-practices/references/techniques-mvc-serve-static.md

@@ -0,0 +1,132 @@
+---
+name: mvc-serve-static
+description: MVC template rendering and serving static files/SPA
+---
+
+# MVC and Serve Static
+
+## MVC (Template Rendering)
+
+### Express Setup
+
+```bash
+npm install hbs
+```
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { join } from 'node:path';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
+  app.useStaticAssets(join(__dirname, '..', 'public'));
+  app.setBaseViewsDir(join(__dirname, '..', 'views'));
+  app.setViewEngine('hbs');
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+### Controller with @Render
+
+```typescript
+import { Get, Controller, Render } from '@nestjs/common';
+
+@Controller()
+export class AppController {
+  @Get()
+  @Render('index')
+  root() {
+    return { message: 'Hello world!' };
+  }
+}
+```
+
+### Dynamic Template Selection
+
+```typescript
+import { Get, Controller, Res } from '@nestjs/common';
+import { Response } from 'express';
+
+@Controller()
+export class AppController {
+  @Get()
+  root(@Res() res: Response) {
+    return res.render('dynamic-view', { message: 'Hello!' });
+  }
+}
+```
+
+### Fastify
+
+```bash
+npm install @fastify/static @fastify/view handlebars
+```
+
+```typescript
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter(),
+);
+app.useStaticAssets({
+  root: join(__dirname, '..', 'public'),
+  prefix: '/public/',
+});
+app.setViewEngine({
+  engine: { handlebars: require('handlebars') },
+  templates: join(__dirname, '..', 'views'),
+});
+```
+
+With Fastify, include file extension in `@Render()`: `@Render('index.hbs')`
+
+## Serve Static (SPA)
+
+Serve static content like Single Page Applications.
+
+```bash
+npm install @nestjs/serve-static
+```
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ServeStaticModule } from '@nestjs/serve-static';
+import { join } from 'path';
+
+@Module({
+  imports: [
+    ServeStaticModule.forRoot({
+      rootPath: join(__dirname, '..', 'client'),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### SPA Client-Side Routing
+
+Default `renderPath` is `*` (all paths). The module sends `index.html` for non-matching routes, enabling client-side routing. Controller paths take precedence.
+
+### Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `rootPath` | Path to static files |
+| `serveRoot` | URL path prefix |
+| `renderPath` | Paths to serve index.html |
+| `exclude` | Excluded paths |
+
+## Key Points
+
+- Use `NestExpressApplication` or `NestFastifyApplication` for MVC
+- `@Render()` passes return object to template as variables
+- ServeStatic fallback enables SPA routing
+- Fastify: set `serveStaticOptions.fallthrough: true` for SPA fallback
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/mvc
+- https://docs.nestjs.com/recipes/serve-static
+-->

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

@@ -0,0 +1,162 @@
+---
+name: queues
+description: Background job processing with BullMQ and Bull
+---
+
+# Queues
+
+Queues help with task scheduling, load balancing, and background processing using Redis-backed job queues.
+
+## Installation (BullMQ - Recommended)
+
+```bash
+npm install @nestjs/bullmq bullmq
+```
+
+## Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { BullModule } from '@nestjs/bullmq';
+
+@Module({
+  imports: [
+    BullModule.forRoot({
+      connection: {
+        host: 'localhost',
+        port: 6379,
+      },
+    }),
+    BullModule.registerQueue({ name: 'audio' }),
+  ],
+})
+export class AppModule {}
+```
+
+## Producer (Adding Jobs)
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectQueue } from '@nestjs/bullmq';
+import { Queue } from 'bullmq';
+
+@Injectable()
+export class AudioService {
+  constructor(@InjectQueue('audio') private audioQueue: Queue) {}
+
+  async addTranscodeJob(file: string) {
+    await this.audioQueue.add('transcode', { file });
+  }
+
+  // With options
+  async addDelayedJob(data: any) {
+    await this.audioQueue.add('process', data, {
+      delay: 5000,           // 5 second delay
+      attempts: 3,           // Retry 3 times
+      removeOnComplete: true,
+      priority: 1,           // Higher priority
+    });
+  }
+}
+```
+
+## Consumer (Processing Jobs)
+
+```typescript
+import { Processor, WorkerHost, OnWorkerEvent } from '@nestjs/bullmq';
+import { Job } from 'bullmq';
+
+@Processor('audio')
+export class AudioConsumer extends WorkerHost {
+  async process(job: Job<any, any, string>): Promise<any> {
+    switch (job.name) {
+      case 'transcode':
+        return this.transcode(job.data);
+      case 'compress':
+        return this.compress(job.data);
+    }
+  }
+
+  private async transcode(data: any) {
+    // Processing logic
+    await job.updateProgress(50);
+    return { processed: true };
+  }
+
+  @OnWorkerEvent('completed')
+  onCompleted(job: Job) {
+    console.log(`Job ${job.id} completed`);
+  }
+
+  @OnWorkerEvent('failed')
+  onFailed(job: Job, error: Error) {
+    console.error(`Job ${job.id} failed:`, error.message);
+  }
+}
+```
+
+Register consumer as provider:
+
+```typescript
+@Module({
+  providers: [AudioConsumer],
+})
+export class AudioModule {}
+```
+
+## Queue Events Listener
+
+```typescript
+import { QueueEventsHost, QueueEventsListener, OnQueueEvent } from '@nestjs/bullmq';
+
+@QueueEventsListener('audio')
+export class AudioEventsListener extends QueueEventsHost {
+  @OnQueueEvent('active')
+  onActive(job: { jobId: string }) {
+    console.log(`Processing job ${job.jobId}...`);
+  }
+}
+```
+
+## Job Options
+
+| Option | Description |
+|--------|-------------|
+| `delay` | Milliseconds to wait before processing |
+| `attempts` | Number of retry attempts |
+| `backoff` | Retry delay strategy |
+| `priority` | Job priority (1 = highest) |
+| `lifo` | Process as LIFO instead of FIFO |
+| `removeOnComplete` | Remove job data after completion |
+| `removeOnFail` | Remove job data after failure |
+| `repeat` | Cron-like repeat configuration |
+
+## Queue Management
+
+```typescript
+await this.audioQueue.pause();
+await this.audioQueue.resume();
+await this.audioQueue.clean(1000); // Remove completed jobs older than 1s
+```
+
+## Request-Scoped Consumers
+
+```typescript
+@Processor({ name: 'audio', scope: Scope.REQUEST })
+export class AudioConsumer extends WorkerHost {
+  constructor(@Inject(JOB_REF) private jobRef: Job) {}
+}
+```
+
+## Key Points
+
+- Consumers must be registered as providers
+- BullMQ is recommended over Bull (actively developed)
+- Use `switch` statement in `process()` for different job names
+- Requires Redis for job persistence
+- Jobs persist across restarts
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/queues
+-->

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

@@ -0,0 +1,158 @@
+---
+name: serialization
+description: Response serialization with class-transformer
+---
+
+# Serialization
+
+Serialization transforms objects before sending responses, using `class-transformer` decorators.
+
+## Basic Usage
+
+Use `ClassSerializerInterceptor` to automatically transform responses:
+
+```typescript
+import { Controller, Get, UseInterceptors } from '@nestjs/common';
+import { ClassSerializerInterceptor } from '@nestjs/common';
+
+@Controller('users')
+@UseInterceptors(ClassSerializerInterceptor)
+export class UsersController {
+  @Get(':id')
+  findOne() {
+    return new UserEntity({
+      id: 1,
+      firstName: 'John',
+      lastName: 'Doe',
+      password: 'secret123',
+    });
+  }
+}
+```
+
+## Exclude Properties
+
+```typescript
+import { Exclude } from 'class-transformer';
+
+export class UserEntity {
+  id: number;
+  firstName: string;
+  lastName: string;
+
+  @Exclude()
+  password: string;
+
+  constructor(partial: Partial<UserEntity>) {
+    Object.assign(this, partial);
+  }
+}
+```
+
+Response excludes `password`:
+
+```json
+{ "id": 1, "firstName": "John", "lastName": "Doe" }
+```
+
+## Expose Computed Properties
+
+```typescript
+import { Expose } from 'class-transformer';
+
+export class UserEntity {
+  firstName: string;
+  lastName: string;
+
+  @Expose()
+  get fullName(): string {
+    return `${this.firstName} ${this.lastName}`;
+  }
+}
+```
+
+## Transform Properties
+
+```typescript
+import { Transform } from 'class-transformer';
+
+export class UserEntity {
+  @Transform(({ value }) => value.name)
+  role: RoleEntity;  // Outputs role.name instead of full object
+}
+```
+
+## Serialization Options
+
+Per-route options:
+
+```typescript
+import { SerializeOptions } from '@nestjs/common';
+
+@Get()
+@SerializeOptions({ excludePrefixes: ['_'] })
+findAll() {
+  return this.usersService.findAll();
+}
+```
+
+## Transform Plain Objects
+
+Force transformation of plain objects:
+
+```typescript
+@Get()
+@UseInterceptors(ClassSerializerInterceptor)
+@SerializeOptions({ type: UserEntity })
+findOne() {
+  return {
+    id: 1,
+    firstName: 'John',
+    password: 'secret',  // Will be excluded
+  };
+}
+```
+
+## Global Interceptor
+
+Apply globally:
+
+```typescript
+@Module({
+  providers: [
+    { provide: APP_INTERCEPTOR, useClass: ClassSerializerInterceptor },
+  ],
+})
+export class AppModule {}
+```
+
+## Groups
+
+Expose different fields based on groups:
+
+```typescript
+export class UserEntity {
+  @Expose({ groups: ['admin'] })
+  email: string;
+
+  @Expose({ groups: ['admin', 'user'] })
+  firstName: string;
+}
+
+// Controller
+@SerializeOptions({ groups: ['admin'] })
+@Get('admin')
+findForAdmin() {}
+```
+
+## Key Points
+
+- Must return class instances, not plain objects
+- Works with WebSockets and Microservices
+- `@Exclude()` and `@Expose()` from `class-transformer`
+- Use `excludeExtraneousValues: true` to only include `@Expose()` fields
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/serialization
+-->