@biggora/claude-plugins 1.2.2 → 1.3.0

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

@@ -0,0 +1,166 @@
+---
+name: task-scheduling
+description: Cron jobs, intervals, and timeouts with @nestjs/schedule
+---
+
+# Task Scheduling
+
+Schedule tasks to run at fixed times, recurring intervals, or after delays.
+
+## Installation
+
+```bash
+npm install @nestjs/schedule
+```
+
+## Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ScheduleModule } from '@nestjs/schedule';
+
+@Module({
+  imports: [ScheduleModule.forRoot()],
+})
+export class AppModule {}
+```
+
+## Cron Jobs
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+
+@Injectable()
+export class TasksService {
+  private readonly logger = new Logger(TasksService.name);
+
+  // Using cron pattern
+  @Cron('45 * * * * *')
+  handleCron() {
+    this.logger.log('Called at second 45 of every minute');
+  }
+
+  // Using CronExpression enum
+  @Cron(CronExpression.EVERY_30_SECONDS)
+  handleEvery30Seconds() {
+    this.logger.log('Called every 30 seconds');
+  }
+
+  // With options
+  @Cron('0 0 8 * * *', {
+    name: 'dailyReport',
+    timeZone: 'America/New_York',
+  })
+  generateDailyReport() {
+    this.logger.log('Generating daily report');
+  }
+}
+```
+
+### Cron Pattern
+
+```
+* * * * * *
+| | | | | |
+| | | | | day of week (0-7)
+| | | | month (1-12)
+| | | day of month (1-31)
+| | hours (0-23)
+| minutes (0-59)
+seconds (0-59, optional)
+```
+
+## Intervals
+
+```typescript
+@Interval(10000)
+handleInterval() {
+  this.logger.log('Called every 10 seconds');
+}
+
+// Named interval
+@Interval('notifications', 2500)
+handleNotifications() {}
+```
+
+## Timeouts
+
+```typescript
+@Timeout(5000)
+handleTimeout() {
+  this.logger.log('Called once after 5 seconds');
+}
+
+// Named timeout
+@Timeout('welcome', 3000)
+sendWelcome() {}
+```
+
+## Dynamic API
+
+Manage scheduled tasks programmatically:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { SchedulerRegistry } from '@nestjs/schedule';
+import { CronJob } from 'cron';
+
+@Injectable()
+export class TaskService {
+  constructor(private schedulerRegistry: SchedulerRegistry) {}
+
+  // Access existing cron job
+  stopCronJob() {
+    const job = this.schedulerRegistry.getCronJob('dailyReport');
+    job.stop();
+  }
+
+  // Create dynamic cron job
+  addCronJob(name: string, cronTime: string) {
+    const job = new CronJob(cronTime, () => {
+      console.log(`Dynamic job ${name} running`);
+    });
+    this.schedulerRegistry.addCronJob(name, job);
+    job.start();
+  }
+
+  // Delete cron job
+  deleteCronJob(name: string) {
+    this.schedulerRegistry.deleteCronJob(name);
+  }
+
+  // List all cron jobs
+  getCronJobs() {
+    const jobs = this.schedulerRegistry.getCronJobs();
+    jobs.forEach((job, key) => {
+      console.log(`Job: ${key}, Next: ${job.nextDate().toJSDate()}`);
+    });
+  }
+}
+```
+
+## CronJob Methods
+
+| Method | Description |
+|--------|-------------|
+| `stop()` | Stop the job |
+| `start()` | Restart a stopped job |
+| `setTime(time)` | Set new time and restart |
+| `lastDate()` | Last execution date |
+| `nextDate()` | Next scheduled execution |
+
+## Cron Options
+
+| Option | Description |
+|--------|-------------|
+| `name` | Name for dynamic access |
+| `timeZone` | Timezone for execution |
+| `utcOffset` | UTC offset alternative |
+| `disabled` | Disable job execution |
+| `waitForCompletion` | Wait for current run before next |
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/task-scheduling
+-->

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

@@ -0,0 +1,126 @@
+---
+name: techniques-validation
+description: Data validation using ValidationPipe and class-validator in NestJS
+---
+
+# Validation
+
+NestJS provides `ValidationPipe` for automatic validation of incoming requests using `class-validator` decorators.
+
+## Installation
+
+```bash
+npm i --save class-validator class-transformer
+```
+
+## Global ValidationPipe
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalPipes(new ValidationPipe());
+  await app.listen(3000);
+}
+```
+
+## DTO with Validation
+
+```typescript
+import { IsString, IsInt, Min, Max } from 'class-validator';
+
+export class CreateCatDto {
+  @IsString()
+  name: string;
+
+  @IsInt()
+  @Min(0)
+  @Max(20)
+  age: number;
+
+  @IsString()
+  breed: string;
+}
+```
+
+## ValidationPipe Options
+
+```typescript
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true,
+    forbidNonWhitelisted: true,
+    transform: true,
+    transformOptions: {
+      enableImplicitConversion: true,
+    },
+  }),
+);
+```
+
+## Common Options
+
+- `whitelist` - Strip non-whitelisted properties
+- `forbidNonWhitelisted` - Throw error on non-whitelisted properties
+- `transform` - Automatically transform payloads to DTO instances
+- `disableErrorMessages` - Disable error messages
+- `validationError.target` - Expose target in ValidationError
+- `stopAtFirstError` - Stop validation on first error
+
+## Custom Validators
+
+```typescript
+import { registerDecorator, ValidationOptions } from 'class-validator';
+
+export function IsLongerThan(property: string, validationOptions?: ValidationOptions) {
+  return function (object: Object, propertyName: string) {
+    registerDecorator({
+      name: 'isLongerThan',
+      target: object.constructor,
+      propertyName: propertyName,
+      constraints: [property],
+      options: validationOptions,
+      validator: {
+        validate(value: any, args: ValidationArguments) {
+          const [relatedPropertyName] = args.constraints;
+          const relatedValue = (args.object as any)[relatedPropertyName];
+          return typeof value === 'string' && typeof relatedValue === 'string' && value.length > relatedValue.length;
+        },
+      },
+    });
+  };
+}
+```
+
+## Validation Groups
+
+```typescript
+export class CreateUserDto {
+  @IsString({ groups: ['registration'] })
+  email: string;
+
+  @IsString({ groups: ['update'] })
+  password: string;
+}
+```
+
+## Conditional Validation
+
+```typescript
+@ValidateIf((o) => o.type === 'email')
+@IsEmail()
+email: string;
+```
+
+## Key Points
+
+- Use `ValidationPipe` globally for automatic validation
+- Decorate DTO properties with `class-validator` decorators
+- Enable `transform` to auto-transform payloads
+- Use `whitelist` to strip unknown properties
+- Create custom validators for complex validation
+- Use validation groups for different scenarios
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/validation
+-->

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

@@ -0,0 +1,153 @@
+---
+name: versioning
+description: API versioning strategies in NestJS
+---
+
+# API Versioning
+
+NestJS supports four versioning strategies for HTTP applications.
+
+## Versioning Types
+
+| Type | Description |
+|------|-------------|
+| URI | Version in URL path (`/v1/cats`) |
+| Header | Custom header specifies version |
+| Media Type | `Accept` header with version |
+| Custom | Custom extractor function |
+
+## Enable Versioning
+
+### URI Versioning (Default)
+
+```typescript
+// main.ts
+import { VersioningType } from '@nestjs/common';
+
+const app = await NestFactory.create(AppModule);
+app.enableVersioning({
+  type: VersioningType.URI,
+  prefix: 'v',  // Optional, default is 'v'
+});
+```
+
+### Header Versioning
+
+```typescript
+app.enableVersioning({
+  type: VersioningType.HEADER,
+  header: 'X-API-Version',
+});
+```
+
+### Media Type Versioning
+
+```typescript
+app.enableVersioning({
+  type: VersioningType.MEDIA_TYPE,
+  key: 'v=',  // Accept: application/json;v=1
+});
+```
+
+## Controller Versioning
+
+```typescript
+@Controller({ path: 'cats', version: '1' })
+export class CatsControllerV1 {
+  @Get()
+  findAll() {
+    return 'Version 1';
+  }
+}
+
+@Controller({ path: 'cats', version: '2' })
+export class CatsControllerV2 {
+  @Get()
+  findAll() {
+    return 'Version 2';
+  }
+}
+```
+
+## Route Versioning
+
+```typescript
+@Controller('cats')
+export class CatsController {
+  @Version('1')
+  @Get()
+  findAllV1() {
+    return 'Version 1';
+  }
+
+  @Version('2')
+  @Get()
+  findAllV2() {
+    return 'Version 2';
+  }
+}
+```
+
+## Multiple Versions
+
+```typescript
+@Controller({ path: 'cats', version: ['1', '2'] })
+export class CatsController {
+  @Get()
+  findAll() {
+    return 'Handles both v1 and v2';
+  }
+}
+```
+
+## Version Neutral
+
+Routes that work regardless of version:
+
+```typescript
+import { VERSION_NEUTRAL } from '@nestjs/common';
+
+@Controller({ path: 'health', version: VERSION_NEUTRAL })
+export class HealthController {
+  @Get()
+  check() {
+    return { status: 'ok' };
+  }
+}
+```
+
+## Default Version
+
+```typescript
+app.enableVersioning({
+  type: VersioningType.URI,
+  defaultVersion: '1',
+  // Or multiple: defaultVersion: ['1', '2']
+  // Or neutral: defaultVersion: VERSION_NEUTRAL
+});
+```
+
+## Middleware Versioning
+
+```typescript
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(LoggerMiddleware)
+      .forRoutes({ path: 'cats', method: RequestMethod.GET, version: '2' });
+  }
+}
+```
+
+## Key Points
+
+- Unversioned routes return 404 when versioning is enabled
+- URI version appears after global prefix
+- Use `VERSION_NEUTRAL` for version-agnostic endpoints
+- Route-level versions override controller-level versions
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/versioning
+-->

package/src/skills/nest-best-practices/references/websockets-advanced.md

@@ -0,0 +1,96 @@
+---
+name: websockets-advanced
+description: WebSocket guards, interceptors, pipes, exception filters, and adapters
+---
+
+# WebSocket Advanced Features
+
+## Guards
+
+Use `WsException` instead of `HttpException` in WebSocket context:
+
+```typescript
+import { WsException } from '@nestjs/websockets';
+
+@UseGuards(AuthGuard)
+@SubscribeMessage('events')
+handleEvent(client: Socket, data: unknown) {
+  if (!data) {
+    throw new WsException('Invalid data');
+  }
+  return { event: 'events', data };
+}
+```
+
+## Exception Filters
+
+```typescript
+import { Catch, ArgumentsHost } from '@nestjs/common';
+import { BaseWsExceptionFilter, WsException } from '@nestjs/websockets';
+
+@Catch(WsException)
+export class AllExceptionsFilter extends BaseWsExceptionFilter {
+  catch(exception: WsException, host: ArgumentsHost) {
+    const client = host.switchToWs().getClient<Socket>();
+    const error = exception.getError();
+    const details = error instanceof Object ? { ...error } : { message: error };
+    client.emit('exception', details);
+  }
+}
+```
+
+Apply globally:
+
+```typescript
+app.useGlobalFilters(new AllExceptionsFilter());
+```
+
+## Interceptors
+
+Same pattern as HTTP—use `@UseInterceptors()` on gateway or handlers.
+
+## Pipes
+
+Validation pipes work in WebSocket handlers. Use `@Payload()` with validation:
+
+```typescript
+@SubscribeMessage('events')
+handleEvent(
+  @Payload(new ValidationPipe({ whitelist: true })) data: CreateEventDto,
+) {
+  return { event: 'events', data };
+}
+```
+
+## Custom Adapter
+
+Use custom WebSocket adapter (e.g., for Redis pub/sub scaling):
+
+```typescript
+import { IoAdapter } from '@nestjs/platform-socket.io';
+
+export class RedisIoAdapter extends IoAdapter {
+  // Override to use Redis adapter
+}
+```
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.useWebSocketAdapter(new RedisIoAdapter(app));
+```
+
+## Key Points
+
+- `WsException` from `@nestjs/websockets`
+- `BaseWsExceptionFilter` for WebSocket exception handling
+- Guards, interceptors, pipes work same as HTTP
+- Use `@Payload()` for typed message body with validation
+
+<!--
+Source references:
+- https://docs.nestjs.com/websockets/guards
+- https://docs.nestjs.com/websockets/exception-filters
+- https://docs.nestjs.com/websockets/interceptors
+- https://docs.nestjs.com/websockets/pipes
+- https://docs.nestjs.com/websockets/adapter
+-->