@qazuor/claude-code-config 0.5.0 → 0.6.0

package/templates/skills/api-frameworks/nestjs-patterns.md

@@ -0,0 +1,497 @@
+# NestJS Framework Patterns
+
+## Overview
+
+NestJS is a progressive Node.js framework for building efficient, scalable server-side applications. This skill provides patterns for implementing APIs with NestJS.
+
+---
+
+## Module Structure
+
+**Pattern**: Feature-based modules with clear boundaries
+
+```typescript
+// items/items.module.ts
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ItemsController } from './items.controller';
+import { ItemsService } from './items.service';
+import { Item } from './entities/item.entity';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([Item])],
+  controllers: [ItemsController],
+  providers: [ItemsService],
+  exports: [ItemsService],
+})
+export class ItemsModule {}
+```
+
+### App Module
+
+```typescript
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ItemsModule } from './items/items.module';
+import { UsersModule } from './users/users.module';
+import { AuthModule } from './auth/auth.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    TypeOrmModule.forRoot({
+      type: 'postgres',
+      url: process.env.DATABASE_URL,
+      autoLoadEntities: true,
+      synchronize: process.env.NODE_ENV === 'development',
+    }),
+    AuthModule,
+    ItemsModule,
+    UsersModule,
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Controller Pattern
+
+```typescript
+// items/items.controller.ts
+import {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  Body,
+  Param,
+  Query,
+  UseGuards,
+  HttpCode,
+  HttpStatus,
+  ParseUUIDPipe,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { CurrentUser } from '../auth/decorators/current-user.decorator';
+import { ItemsService } from './items.service';
+import { CreateItemDto } from './dto/create-item.dto';
+import { UpdateItemDto } from './dto/update-item.dto';
+import { QueryItemDto } from './dto/query-item.dto';
+
+@ApiTags('items')
+@Controller('items')
+export class ItemsController {
+  constructor(private readonly itemsService: ItemsService) {}
+
+  @Get()
+  @ApiOperation({ summary: 'Get all items' })
+  async findAll(@Query() query: QueryItemDto) {
+    return this.itemsService.findAll(query);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get item by ID' })
+  async findOne(@Param('id', ParseUUIDPipe) id: string) {
+    return this.itemsService.findOne(id);
+  }
+
+  @Post()
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Create new item' })
+  async create(
+    @Body() createItemDto: CreateItemDto,
+    @CurrentUser() user: User,
+  ) {
+    return this.itemsService.create(createItemDto, user);
+  }
+
+  @Put(':id')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Update item' })
+  async update(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() updateItemDto: UpdateItemDto,
+    @CurrentUser() user: User,
+  ) {
+    return this.itemsService.update(id, updateItemDto, user);
+  }
+
+  @Delete(':id')
+  @UseGuards(JwtAuthGuard)
+  @ApiBearerAuth()
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: 'Delete item' })
+  async remove(
+    @Param('id', ParseUUIDPipe) id: string,
+    @CurrentUser() user: User,
+  ) {
+    return this.itemsService.remove(id, user);
+  }
+}
+```
+
+---
+
+## Service Pattern
+
+```typescript
+// items/items.service.ts
+import { Injectable, NotFoundException, ForbiddenException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { Item } from './entities/item.entity';
+import { CreateItemDto } from './dto/create-item.dto';
+import { UpdateItemDto } from './dto/update-item.dto';
+import { QueryItemDto } from './dto/query-item.dto';
+
+@Injectable()
+export class ItemsService {
+  constructor(
+    @InjectRepository(Item)
+    private readonly itemRepository: Repository<Item>,
+  ) {}
+
+  async findAll(query: QueryItemDto) {
+    const { page = 1, limit = 10, status } = query;
+
+    const [items, total] = await this.itemRepository.findAndCount({
+      where: status ? { status } : {},
+      take: limit,
+      skip: (page - 1) * limit,
+      order: { createdAt: 'DESC' },
+      relations: ['author'],
+    });
+
+    return {
+      data: items,
+      pagination: {
+        total,
+        page,
+        limit,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+
+  async findOne(id: string) {
+    const item = await this.itemRepository.findOne({
+      where: { id },
+      relations: ['author'],
+    });
+
+    if (!item) {
+      throw new NotFoundException(`Item #${id} not found`);
+    }
+
+    return item;
+  }
+
+  async create(createItemDto: CreateItemDto, user: User) {
+    const item = this.itemRepository.create({
+      ...createItemDto,
+      authorId: user.id,
+    });
+
+    return this.itemRepository.save(item);
+  }
+
+  async update(id: string, updateItemDto: UpdateItemDto, user: User) {
+    const item = await this.findOne(id);
+
+    if (item.authorId !== user.id) {
+      throw new ForbiddenException('You can only update your own items');
+    }
+
+    Object.assign(item, updateItemDto);
+    return this.itemRepository.save(item);
+  }
+
+  async remove(id: string, user: User) {
+    const item = await this.findOne(id);
+
+    if (item.authorId !== user.id) {
+      throw new ForbiddenException('You can only delete your own items');
+    }
+
+    await this.itemRepository.remove(item);
+  }
+}
+```
+
+---
+
+## DTOs with Validation
+
+```typescript
+// items/dto/create-item.dto.ts
+import { IsString, IsNotEmpty, IsOptional, MaxLength } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateItemDto {
+  @ApiProperty({ description: 'Item title', maxLength: 255 })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(255)
+  title: string;
+
+  @ApiPropertyOptional({ description: 'Item description' })
+  @IsString()
+  @IsOptional()
+  description?: string;
+}
+
+// items/dto/update-item.dto.ts
+import { PartialType } from '@nestjs/swagger';
+import { CreateItemDto } from './create-item.dto';
+
+export class UpdateItemDto extends PartialType(CreateItemDto) {}
+
+// items/dto/query-item.dto.ts
+import { IsOptional, IsInt, Min, IsEnum } from 'class-validator';
+import { Type } from 'class-transformer';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class QueryItemDto {
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({ default: 10 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  limit?: number = 10;
+
+  @ApiPropertyOptional({ enum: ['active', 'archived'] })
+  @IsOptional()
+  @IsEnum(['active', 'archived'])
+  status?: string;
+}
+```
+
+---
+
+## Guards and Decorators
+
+### JWT Auth Guard
+
+```typescript
+// auth/guards/jwt-auth.guard.ts
+import { Injectable, ExecutionContext } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  canActivate(context: ExecutionContext) {
+    return super.canActivate(context);
+  }
+}
+```
+
+### Current User Decorator
+
+```typescript
+// auth/decorators/current-user.decorator.ts
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const CurrentUser = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.user;
+  },
+);
+```
+
+### Roles Guard
+
+```typescript
+// auth/guards/roles.guard.ts
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (!requiredRoles) {
+      return true;
+    }
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.some((role) => user.roles?.includes(role));
+  }
+}
+```
+
+---
+
+## Exception Filters
+
+```typescript
+// common/filters/http-exception.filter.ts
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+} from '@nestjs/common';
+import { Response } from 'express';
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : 'Internal server error';
+
+    response.status(status).json({
+      success: false,
+      statusCode: status,
+      error: typeof message === 'string' ? { message } : message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+---
+
+## Testing
+
+```typescript
+// items/items.controller.spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { ItemsController } from './items.controller';
+import { ItemsService } from './items.service';
+
+describe('ItemsController', () => {
+  let controller: ItemsController;
+  let service: ItemsService;
+
+  const mockItemsService = {
+    findAll: jest.fn(),
+    findOne: jest.fn(),
+    create: jest.fn(),
+    update: jest.fn(),
+    remove: jest.fn(),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [ItemsController],
+      providers: [
+        {
+          provide: ItemsService,
+          useValue: mockItemsService,
+        },
+      ],
+    }).compile();
+
+    controller = module.get<ItemsController>(ItemsController);
+    service = module.get<ItemsService>(ItemsService);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+
+  describe('findAll', () => {
+    it('should return array of items', async () => {
+      const result = { data: [], pagination: {} };
+      mockItemsService.findAll.mockResolvedValue(result);
+
+      expect(await controller.findAll({})).toBe(result);
+    });
+  });
+
+  describe('create', () => {
+    it('should create item', async () => {
+      const dto = { title: 'Test' };
+      const user = { id: '1' };
+      const item = { id: '1', ...dto };
+
+      mockItemsService.create.mockResolvedValue(item);
+
+      expect(await controller.create(dto, user as any)).toBe(item);
+      expect(mockItemsService.create).toHaveBeenCalledWith(dto, user);
+    });
+  });
+});
+```
+
+---
+
+## Project Structure
+
+```
+{API_PATH}/
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── common/
+│   │   ├── filters/
+│   │   ├── guards/
+│   │   ├── interceptors/
+│   │   └── pipes/
+│   ├── auth/
+│   │   ├── auth.module.ts
+│   │   ├── auth.service.ts
+│   │   ├── guards/
+│   │   └── decorators/
+│   └── items/
+│       ├── items.module.ts
+│       ├── items.controller.ts
+│       ├── items.service.ts
+│       ├── dto/
+│       └── entities/
+└── test/
+    └── items.e2e-spec.ts
+```
+
+---
+
+## Best Practices
+
+### Good
+
+- Use modules for feature encapsulation
+- Use DTOs for validation with class-validator
+- Use guards for authentication/authorization
+- Use interceptors for response transformation
+- Use dependency injection consistently
+
+### Bad
+
+- Circular dependencies between modules
+- Business logic in controllers
+- Skipping validation
+- Not using pipes for transformation
+- Hardcoded values instead of ConfigService