@biggora/claude-plugins 1.2.2 → 1.3.0

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

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