@biggora/claude-plugins 1.2.2 → 1.3.1

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

@@ -0,0 +1,167 @@
+---
+name: sessions-cookies
+description: HTTP sessions and cookies for stateful applications
+---
+
+# Sessions and Cookies
+
+## Sessions
+
+### Express (Default)
+
+```bash
+npm install express-session
+npm install -D @types/express-session
+```
+
+```typescript
+import * as session from 'express-session';
+
+// main.ts
+app.use(
+  session({
+    secret: 'my-secret',
+    resave: false,
+    saveUninitialized: false,
+  }),
+);
+```
+
+Usage in controllers:
+
+```typescript
+@Get()
+findAll(@Req() request: Request) {
+  request.session.visits = (request.session.visits ?? 0) + 1;
+}
+
+// Or using @Session decorator
+@Get()
+findAll(@Session() session: Record<string, any>) {
+  session.visits = (session.visits ?? 0) + 1;
+}
+```
+
+### Fastify
+
+```bash
+npm install @fastify/secure-session
+```
+
+```typescript
+import secureSession from '@fastify/secure-session';
+
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter(),
+);
+
+await app.register(secureSession, {
+  secret: 'averylogphrasebiggerthanthirtytwochars',
+  salt: 'mq9hDxBVDbspDR6n',
+});
+```
+
+```typescript
+@Get()
+findAll(@Req() request: FastifyRequest) {
+  const visits = request.session.get('visits') ?? 0;
+  request.session.set('visits', visits + 1);
+}
+```
+
+## Cookies
+
+### Express (Default)
+
+```bash
+npm install cookie-parser
+npm install -D @types/cookie-parser
+```
+
+```typescript
+import * as cookieParser from 'cookie-parser';
+
+app.use(cookieParser());
+```
+
+Reading and setting cookies:
+
+```typescript
+@Get()
+getCookies(@Req() request: Request) {
+  console.log(request.cookies);
+  console.log(request.signedCookies);
+}
+
+@Get()
+setCookie(@Res({ passthrough: true }) response: Response) {
+  response.cookie('key', 'value', {
+    httpOnly: true,
+    secure: true,
+    maxAge: 1000 * 60 * 60 * 24, // 1 day
+  });
+}
+```
+
+### Fastify
+
+```bash
+npm install @fastify/cookie
+```
+
+```typescript
+import fastifyCookie from '@fastify/cookie';
+
+await app.register(fastifyCookie, {
+  secret: 'my-secret',
+});
+```
+
+```typescript
+@Get()
+setCookie(@Res({ passthrough: true }) response: FastifyReply) {
+  response.setCookie('key', 'value');
+}
+```
+
+## Custom Cookie Decorator
+
+```typescript
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const Cookies = createParamDecorator(
+  (data: string, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return data ? request.cookies?.[data] : request.cookies;
+  },
+);
+
+// Usage
+@Get()
+findAll(@Cookies('name') name: string) {}
+```
+
+## Session Configuration Options
+
+| Option | Description |
+|--------|-------------|
+| `secret` | Used to sign session ID cookie |
+| `resave` | Force save even if unmodified (set to `false`) |
+| `saveUninitialized` | Save uninitialized sessions (set to `false` for login flows) |
+| `cookie.secure` | Require HTTPS (recommended for production) |
+| `cookie.httpOnly` | Prevent client-side access |
+
+## Key Points
+
+- Default session storage is not for production (leaks memory)
+- Use Redis or database-backed session store in production
+- Set `secure: true` for production cookies
+- Use `passthrough: true` with `@Res()` to keep NestJS response handling
+- Session decorator is `@Session()` from `@nestjs/common`
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/session
+- https://docs.nestjs.com/techniques/cookies
+-->

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