omgkit 2.1.1 → 2.2.0

package/plugin/skills/frameworks/nestjs/SKILL.md

@@ -1,67 +1,1046 @@
 ---
 name: nestjs
-description: NestJS development. Use for NestJS projects, modules, dependency injection.
+description: Enterprise NestJS development with TypeScript, dependency injection, and microservices patterns
+category: frameworks
+triggers:
+  - nestjs
+  - nest.js
+  - nest
+  - node typescript
+  - typescript backend
+  - nodejs framework
+  - nestjs api
+  - nestjs microservices
 ---
 
-# NestJS Skill
+# NestJS
 
-## Patterns
+Enterprise-grade **NestJS development** following industry best practices. This skill covers modular architecture, dependency injection, TypeORM integration, authentication with Passport, testing patterns, and microservices configurations used by top engineering teams.
+
+## Purpose
+
+Build scalable Node.js applications with confidence:
+
+- Design modular, maintainable architectures
+- Implement robust dependency injection
+- Handle authentication and authorization
+- Validate requests with class-validator
+- Write comprehensive tests with Jest
+- Deploy production-ready applications
+- Build microservices and message queues
+
+## Features
+
+### 1. Module Architecture
 
-### Module
 ```typescript
+// src/app.module.ts
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ThrottlerModule } from '@nestjs/throttler';
+import { APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
+
+import { AuthModule } from './auth/auth.module';
+import { UsersModule } from './users/users.module';
+import { OrganizationsModule } from './organizations/organizations.module';
+import { ProjectsModule } from './projects/projects.module';
+import { LoggingInterceptor } from './common/interceptors/logging.interceptor';
+import { RequestIdMiddleware } from './common/middleware/request-id.middleware';
+import configuration from './config/configuration';
+
 @Module({
-  imports: [DatabaseModule],
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      load: [configuration],
+    }),
+    TypeOrmModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        type: 'postgres',
+        host: config.get('database.host'),
+        port: config.get('database.port'),
+        username: config.get('database.username'),
+        password: config.get('database.password'),
+        database: config.get('database.name'),
+        entities: [__dirname + '/**/*.entity{.ts,.js}'],
+        synchronize: config.get('database.synchronize'),
+        logging: config.get('database.logging'),
+      }),
+    }),
+    ThrottlerModule.forRoot([{
+      ttl: 60000,
+      limit: 100,
+    }]),
+    AuthModule,
+    UsersModule,
+    OrganizationsModule,
+    ProjectsModule,
+  ],
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: LoggingInterceptor,
+    },
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(RequestIdMiddleware).forRoutes('*');
+  }
+}
+
+
+// src/users/users.module.ts
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+import { User } from './entities/user.entity';
+import { UsersRepository } from './users.repository';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
   controllers: [UsersController],
-  providers: [UsersService],
+  providers: [UsersService, UsersRepository],
   exports: [UsersService],
 })
 export class UsersModule {}
+
+
+// src/config/configuration.ts
+export default () => ({
+  port: parseInt(process.env.PORT, 10) || 3000,
+  database: {
+    host: process.env.DB_HOST || 'localhost',
+    port: parseInt(process.env.DB_PORT, 10) || 5432,
+    username: process.env.DB_USERNAME || 'postgres',
+    password: process.env.DB_PASSWORD,
+    name: process.env.DB_NAME || 'app',
+    synchronize: process.env.NODE_ENV !== 'production',
+    logging: process.env.NODE_ENV === 'development',
+  },
+  jwt: {
+    secret: process.env.JWT_SECRET,
+    expiresIn: process.env.JWT_EXPIRES_IN || '1h',
+  },
+  redis: {
+    host: process.env.REDIS_HOST || 'localhost',
+    port: parseInt(process.env.REDIS_PORT, 10) || 6379,
+  },
+});
+```
+
+### 2. Entities and Repositories
+
+```typescript
+// src/users/entities/user.entity.ts
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  UpdateDateColumn,
+  DeleteDateColumn,
+  ManyToMany,
+  OneToMany,
+  BeforeInsert,
+} from 'typeorm';
+import * as bcrypt from 'bcrypt';
+import { Organization } from '../../organizations/entities/organization.entity';
+import { Exclude } from 'class-transformer';
+
+export enum UserRole {
+  ADMIN = 'admin',
+  USER = 'user',
+  GUEST = 'guest',
+}
+
+@Entity('users')
+export class User {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ unique: true })
+  email: string;
+
+  @Column()
+  name: string;
+
+  @Column()
+  @Exclude()
+  password: string;
+
+  @Column({
+    type: 'enum',
+    enum: UserRole,
+    default: UserRole.USER,
+  })
+  role: UserRole;
+
+  @Column({ default: true })
+  isActive: boolean;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @DeleteDateColumn()
+  deletedAt?: Date;
+
+  @ManyToMany(() => Organization, (org) => org.members)
+  organizations: Organization[];
+
+  @OneToMany(() => Organization, (org) => org.owner)
+  ownedOrganizations: Organization[];
+
+  @BeforeInsert()
+  async hashPassword() {
+    if (this.password) {
+      this.password = await bcrypt.hash(this.password, 10);
+    }
+  }
+
+  async validatePassword(password: string): Promise<boolean> {
+    return bcrypt.compare(password, this.password);
+  }
+}
+
+
+// src/users/users.repository.ts
+import { Injectable } from '@nestjs/common';
+import { DataSource, Repository } from 'typeorm';
+import { User, UserRole } from './entities/user.entity';
+
+interface FindAllOptions {
+  search?: string;
+  role?: UserRole;
+  isActive?: boolean;
+  skip?: number;
+  take?: number;
+}
+
+@Injectable()
+export class UsersRepository extends Repository<User> {
+  constructor(private dataSource: DataSource) {
+    super(User, dataSource.createEntityManager());
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.findOne({
+      where: { email },
+    });
+  }
+
+  async findAllWithCount(options: FindAllOptions): Promise<[User[], number]> {
+    const query = this.createQueryBuilder('user')
+      .where('user.deletedAt IS NULL');
+
+    if (options.search) {
+      query.andWhere(
+        '(user.name ILIKE :search OR user.email ILIKE :search)',
+        { search: `%${options.search}%` },
+      );
+    }
+
+    if (options.role) {
+      query.andWhere('user.role = :role', { role: options.role });
+    }
+
+    if (options.isActive !== undefined) {
+      query.andWhere('user.isActive = :isActive', { isActive: options.isActive });
+    }
+
+    return query
+      .orderBy('user.createdAt', 'DESC')
+      .skip(options.skip || 0)
+      .take(options.take || 20)
+      .getManyAndCount();
+  }
+
+  async findWithOrganizations(id: string): Promise<User | null> {
+    return this.findOne({
+      where: { id },
+      relations: ['organizations'],
+    });
+  }
+}
 ```
 
-### Controller
+### 3. DTOs and Validation
+
 ```typescript
+// src/users/dto/create-user.dto.ts
+import {
+  IsEmail,
+  IsString,
+  IsEnum,
+  IsOptional,
+  MinLength,
+  MaxLength,
+  Matches,
+} from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { UserRole } from '../entities/user.entity';
+
+export class CreateUserDto {
+  @ApiProperty({ example: 'user@example.com' })
+  @IsEmail()
+  email: string;
+
+  @ApiProperty({ example: 'John Doe' })
+  @IsString()
+  @MinLength(2)
+  @MaxLength(100)
+  name: string;
+
+  @ApiProperty({ example: 'SecurePass123!' })
+  @IsString()
+  @MinLength(8)
+  @MaxLength(128)
+  @Matches(
+    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]/,
+    { message: 'Password must contain uppercase, lowercase, number and special character' },
+  )
+  password: string;
+
+  @ApiPropertyOptional({ enum: UserRole })
+  @IsOptional()
+  @IsEnum(UserRole)
+  role?: UserRole;
+}
+
+
+// src/users/dto/update-user.dto.ts
+import { PartialType, OmitType } from '@nestjs/swagger';
+import { CreateUserDto } from './create-user.dto';
+import { IsBoolean, IsOptional } from 'class-validator';
+
+export class UpdateUserDto extends PartialType(
+  OmitType(CreateUserDto, ['password'] as const),
+) {
+  @IsOptional()
+  @IsBoolean()
+  isActive?: boolean;
+}
+
+
+// src/users/dto/user-response.dto.ts
+import { ApiProperty } from '@nestjs/swagger';
+import { Expose, Type } from 'class-transformer';
+import { UserRole } from '../entities/user.entity';
+
+export class UserResponseDto {
+  @ApiProperty()
+  @Expose()
+  id: string;
+
+  @ApiProperty()
+  @Expose()
+  email: string;
+
+  @ApiProperty()
+  @Expose()
+  name: string;
+
+  @ApiProperty({ enum: UserRole })
+  @Expose()
+  role: UserRole;
+
+  @ApiProperty()
+  @Expose()
+  isActive: boolean;
+
+  @ApiProperty()
+  @Expose()
+  createdAt: Date;
+
+  @ApiProperty()
+  @Expose()
+  updatedAt: Date;
+}
+
+
+// src/common/dto/pagination.dto.ts
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsOptional, IsInt, Min, Max } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class PaginationDto {
+  @ApiPropertyOptional({ default: 1 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({ default: 20 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+
+  get skip(): number {
+    return (this.page - 1) * this.limit;
+  }
+}
+
+export class PaginatedResponseDto<T> {
+  @ApiProperty()
+  data: T[];
+
+  @ApiProperty()
+  total: number;
+
+  @ApiProperty()
+  page: number;
+
+  @ApiProperty()
+  limit: number;
+
+  @ApiProperty()
+  totalPages: number;
+
+  @ApiProperty()
+  hasMore: boolean;
+
+  static create<T>(
+    data: T[],
+    total: number,
+    page: number,
+    limit: number,
+  ): PaginatedResponseDto<T> {
+    const totalPages = Math.ceil(total / limit);
+    return {
+      data,
+      total,
+      page,
+      limit,
+      totalPages,
+      hasMore: page < totalPages,
+    };
+  }
+}
+```
+
+### 4. Controllers
+
+```typescript
+// src/users/users.controller.ts
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  Delete,
+  Body,
+  Param,
+  Query,
+  UseGuards,
+  ParseUUIDPipe,
+  HttpCode,
+  HttpStatus,
+} from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBearerAuth,
+} from '@nestjs/swagger';
+import { UsersService } from './users.service';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { UserResponseDto } from './dto/user-response.dto';
+import { PaginationDto, PaginatedResponseDto } from '../common/dto/pagination.dto';
+import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
+import { RolesGuard } from '../auth/guards/roles.guard';
+import { Roles } from '../auth/decorators/roles.decorator';
+import { CurrentUser } from '../auth/decorators/current-user.decorator';
+import { User, UserRole } from './entities/user.entity';
+
+@ApiTags('users')
 @Controller('users')
+@UseGuards(JwtAuthGuard, RolesGuard)
+@ApiBearerAuth()
 export class UsersController {
-  constructor(private usersService: UsersService) {}
+  constructor(private readonly usersService: UsersService) {}
 
   @Get()
-  findAll() {
-    return this.usersService.findAll();
+  @Roles(UserRole.ADMIN)
+  @ApiOperation({ summary: 'List all users' })
+  @ApiResponse({ status: 200, type: PaginatedResponseDto })
+  async findAll(
+    @Query() pagination: PaginationDto,
+    @Query('search') search?: string,
+    @Query('role') role?: UserRole,
+  ): Promise<PaginatedResponseDto<UserResponseDto>> {
+    return this.usersService.findAll(pagination, { search, role });
+  }
+
+  @Get('me')
+  @ApiOperation({ summary: 'Get current user profile' })
+  @ApiResponse({ status: 200, type: UserResponseDto })
+  async getProfile(@CurrentUser() user: User): Promise<UserResponseDto> {
+    return this.usersService.findOne(user.id);
+  }
+
+  @Patch('me')
+  @ApiOperation({ summary: 'Update current user profile' })
+  @ApiResponse({ status: 200, type: UserResponseDto })
+  async updateProfile(
+    @CurrentUser() user: User,
+    @Body() updateUserDto: UpdateUserDto,
+  ): Promise<UserResponseDto> {
+    return this.usersService.update(user.id, updateUserDto);
+  }
+
+  @Get(':id')
+  @Roles(UserRole.ADMIN)
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiResponse({ status: 200, type: UserResponseDto })
+  async findOne(
+    @Param('id', ParseUUIDPipe) id: string,
+  ): Promise<UserResponseDto> {
+    return this.usersService.findOne(id);
   }
 
   @Post()
-  create(@Body() dto: CreateUserDto) {
-    return this.usersService.create(dto);
+  @Roles(UserRole.ADMIN)
+  @ApiOperation({ summary: 'Create new user' })
+  @ApiResponse({ status: 201, type: UserResponseDto })
+  async create(@Body() createUserDto: CreateUserDto): Promise<UserResponseDto> {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Patch(':id')
+  @Roles(UserRole.ADMIN)
+  @ApiOperation({ summary: 'Update user' })
+  @ApiResponse({ status: 200, type: UserResponseDto })
+  async update(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() updateUserDto: UpdateUserDto,
+  ): Promise<UserResponseDto> {
+    return this.usersService.update(id, updateUserDto);
+  }
+
+  @Delete(':id')
+  @Roles(UserRole.ADMIN)
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: 'Delete user' })
+  @ApiResponse({ status: 204 })
+  async remove(@Param('id', ParseUUIDPipe) id: string): Promise<void> {
+    await this.usersService.remove(id);
   }
 }
 ```
 
-### Service
+### 5. Services
+
 ```typescript
+// src/users/users.service.ts
+import {
+  Injectable,
+  NotFoundException,
+  ConflictException,
+} from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { UsersRepository } from './users.repository';
+import { CreateUserDto } from './dto/create-user.dto';
+import { UpdateUserDto } from './dto/update-user.dto';
+import { UserResponseDto } from './dto/user-response.dto';
+import { PaginationDto, PaginatedResponseDto } from '../common/dto/pagination.dto';
+import { User, UserRole } from './entities/user.entity';
+
+interface FindAllFilters {
+  search?: string;
+  role?: UserRole;
+  isActive?: boolean;
+}
+
 @Injectable()
 export class UsersService {
-  constructor(private db: DatabaseService) {}
+  constructor(private readonly usersRepository: UsersRepository) {}
+
+  async findAll(
+    pagination: PaginationDto,
+    filters: FindAllFilters = {},
+  ): Promise<PaginatedResponseDto<UserResponseDto>> {
+    const [users, total] = await this.usersRepository.findAllWithCount({
+      ...filters,
+      skip: pagination.skip,
+      take: pagination.limit,
+    });
+
+    const data = users.map((user) =>
+      plainToInstance(UserResponseDto, user, { excludeExtraneousValues: true }),
+    );
+
+    return PaginatedResponseDto.create(
+      data,
+      total,
+      pagination.page,
+      pagination.limit,
+    );
+  }
+
+  async findOne(id: string): Promise<UserResponseDto> {
+    const user = await this.usersRepository.findOne({ where: { id } });
+
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    return plainToInstance(UserResponseDto, user, {
+      excludeExtraneousValues: true,
+    });
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.usersRepository.findByEmail(email);
+  }
+
+  async create(createUserDto: CreateUserDto): Promise<UserResponseDto> {
+    const existing = await this.usersRepository.findByEmail(createUserDto.email);
+
+    if (existing) {
+      throw new ConflictException('Email already in use');
+    }
+
+    const user = this.usersRepository.create(createUserDto);
+    await this.usersRepository.save(user);
 
-  async findAll() {
-    return this.db.users.findMany();
+    return plainToInstance(UserResponseDto, user, {
+      excludeExtraneousValues: true,
+    });
+  }
+
+  async update(id: string, updateUserDto: UpdateUserDto): Promise<UserResponseDto> {
+    const user = await this.usersRepository.findOne({ where: { id } });
+
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    if (updateUserDto.email && updateUserDto.email !== user.email) {
+      const existing = await this.usersRepository.findByEmail(updateUserDto.email);
+      if (existing) {
+        throw new ConflictException('Email already in use');
+      }
+    }
+
+    Object.assign(user, updateUserDto);
+    await this.usersRepository.save(user);
+
+    return plainToInstance(UserResponseDto, user, {
+      excludeExtraneousValues: true,
+    });
+  }
+
+  async remove(id: string): Promise<void> {
+    const user = await this.usersRepository.findOne({ where: { id } });
+
+    if (!user) {
+      throw new NotFoundException(`User with ID ${id} not found`);
+    }
+
+    await this.usersRepository.softRemove(user);
+  }
+
+  async validateUser(email: string, password: string): Promise<User | null> {
+    const user = await this.usersRepository.findByEmail(email);
+
+    if (!user || !user.isActive) {
+      return null;
+    }
+
+    const isValid = await user.validatePassword(password);
+    return isValid ? user : null;
   }
 }
 ```
 
-### DTO
+### 6. Authentication
+
 ```typescript
-export class CreateUserDto {
-  @IsEmail()
+// src/auth/auth.module.ts
+import { Module } from '@nestjs/common';
+import { JwtModule } from '@nestjs/jwt';
+import { PassportModule } from '@nestjs/passport';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { AuthController } from './auth.controller';
+import { AuthService } from './auth.service';
+import { JwtStrategy } from './strategies/jwt.strategy';
+import { LocalStrategy } from './strategies/local.strategy';
+import { UsersModule } from '../users/users.module';
+
+@Module({
+  imports: [
+    UsersModule,
+    PassportModule,
+    JwtModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.get('jwt.secret'),
+        signOptions: { expiresIn: config.get('jwt.expiresIn') },
+      }),
+    }),
+  ],
+  controllers: [AuthController],
+  providers: [AuthService, JwtStrategy, LocalStrategy],
+  exports: [AuthService],
+})
+export class AuthModule {}
+
+
+// src/auth/strategies/jwt.strategy.ts
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+import { ConfigService } from '@nestjs/config';
+import { UsersService } from '../../users/users.service';
+
+interface JwtPayload {
+  sub: string;
   email: string;
+  role: string;
+}
 
-  @IsString()
-  @MinLength(8)
-  password: string;
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly usersService: UsersService,
+  ) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: configService.get('jwt.secret'),
+    });
+  }
+
+  async validate(payload: JwtPayload) {
+    const user = await this.usersService.findByEmail(payload.email);
+
+    if (!user || !user.isActive) {
+      throw new UnauthorizedException();
+    }
+
+    return user;
+  }
+}
+
+
+// src/auth/guards/roles.guard.ts
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { UserRole } from '../../users/entities/user.entity';
+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<UserRole[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!requiredRoles) {
+      return true;
+    }
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.includes(user.role);
+  }
+}
+
+
+// src/auth/decorators/roles.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+import { UserRole } from '../../users/entities/user.entity';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: UserRole[]) => SetMetadata(ROLES_KEY, roles);
+
+
+// src/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;
+  },
+);
+```
+
+### 7. Testing
+
+```typescript
+// src/users/users.service.spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { NotFoundException, ConflictException } from '@nestjs/common';
+import { UsersService } from './users.service';
+import { UsersRepository } from './users.repository';
+import { User, UserRole } from './entities/user.entity';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repository: jest.Mocked<UsersRepository>;
+
+  const mockUser: Partial<User> = {
+    id: 'test-id',
+    email: 'test@example.com',
+    name: 'Test User',
+    role: UserRole.USER,
+    isActive: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: UsersRepository,
+          useValue: {
+            findOne: jest.fn(),
+            findByEmail: jest.fn(),
+            findAllWithCount: jest.fn(),
+            create: jest.fn(),
+            save: jest.fn(),
+            softRemove: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+    repository = module.get(UsersRepository);
+  });
+
+  describe('findOne', () => {
+    it('should return a user', async () => {
+      repository.findOne.mockResolvedValue(mockUser as User);
+
+      const result = await service.findOne('test-id');
+
+      expect(result.email).toBe(mockUser.email);
+      expect(repository.findOne).toHaveBeenCalledWith({
+        where: { id: 'test-id' },
+      });
+    });
+
+    it('should throw NotFoundException if user not found', async () => {
+      repository.findOne.mockResolvedValue(null);
+
+      await expect(service.findOne('test-id')).rejects.toThrow(NotFoundException);
+    });
+  });
+
+  describe('create', () => {
+    it('should create a new user', async () => {
+      repository.findByEmail.mockResolvedValue(null);
+      repository.create.mockReturnValue(mockUser as User);
+      repository.save.mockResolvedValue(mockUser as User);
+
+      const result = await service.create({
+        email: 'test@example.com',
+        name: 'Test User',
+        password: 'Password123!',
+      });
+
+      expect(result.email).toBe(mockUser.email);
+      expect(repository.save).toHaveBeenCalled();
+    });
+
+    it('should throw ConflictException for duplicate email', async () => {
+      repository.findByEmail.mockResolvedValue(mockUser as User);
+
+      await expect(
+        service.create({
+          email: 'test@example.com',
+          name: 'Test',
+          password: 'Password123!',
+        }),
+      ).rejects.toThrow(ConflictException);
+    });
+  });
+});
+
+
+// src/users/users.controller.spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: jest.Mocked<UsersService>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            findAll: jest.fn(),
+            findOne: jest.fn(),
+            create: jest.fn(),
+            update: jest.fn(),
+            remove: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<UsersController>(UsersController);
+    service = module.get(UsersService);
+  });
+
+  it('should be defined', () => {
+    expect(controller).toBeDefined();
+  });
+});
+
+
+// test/users.e2e-spec.ts
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import * as request from 'supertest';
+import { AppModule } from '../src/app.module';
+
+describe('Users (e2e)', () => {
+  let app: INestApplication;
+  let authToken: string;
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
+    await app.init();
+
+    // Get auth token
+    const loginResponse = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ email: 'admin@test.com', password: 'Admin123!' });
+
+    authToken = loginResponse.body.access_token;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  describe('/users (GET)', () => {
+    it('should return paginated users', () => {
+      return request(app.getHttpServer())
+        .get('/users')
+        .set('Authorization', `Bearer ${authToken}`)
+        .expect(200)
+        .expect((res) => {
+          expect(res.body).toHaveProperty('data');
+          expect(res.body).toHaveProperty('pagination');
+        });
+    });
+
+    it('should return 401 without auth token', () => {
+      return request(app.getHttpServer())
+        .get('/users')
+        .expect(401);
+    });
+  });
+});
+```
+
+## Use Cases
+
+### Microservices with Message Queue
+
+```typescript
+// src/app.module.ts (Microservice)
+import { Module } from '@nestjs/common';
+import { ClientsModule, Transport } from '@nestjs/microservices';
+
+@Module({
+  imports: [
+    ClientsModule.register([
+      {
+        name: 'NOTIFICATION_SERVICE',
+        transport: Transport.RMQ,
+        options: {
+          urls: [process.env.RABBITMQ_URL],
+          queue: 'notifications_queue',
+          queueOptions: { durable: false },
+        },
+      },
+    ]),
+  ],
+})
+export class AppModule {}
+
+
+// src/notifications/notifications.service.ts
+import { Injectable, Inject } from '@nestjs/common';
+import { ClientProxy } from '@nestjs/microservices';
+
+@Injectable()
+export class NotificationsService {
+  constructor(
+    @Inject('NOTIFICATION_SERVICE') private client: ClientProxy,
+  ) {}
+
+  async sendWelcomeEmail(userId: string, email: string) {
+    return this.client.emit('user_welcome', { userId, email });
+  }
 }
 ```
 
 ## Best Practices
-- Use modules for organization
-- Use DTOs for validation
-- Use dependency injection
-- Use guards for auth
+
+### Do's
+
+- Use modules to organize features
+- Use dependency injection throughout
+- Use DTOs for validation and transformation
+- Use interceptors for cross-cutting concerns
+- Use guards for authentication/authorization
+- Use custom decorators for cleaner code
+- Write unit and e2e tests
+- Use class-transformer for responses
+- Use environment configuration
+- Document APIs with Swagger
+
+### Don'ts
+
+- Don't put business logic in controllers
+- Don't skip input validation
+- Don't expose internal errors
+- Don't use any type unnecessarily
+- Don't skip authentication guards
+- Don't ignore database transactions
+- Don't hardcode configuration
+- Don't forget error handling
+- Don't skip testing
+- Don't use circular dependencies
+
+## References
+
+- [NestJS Documentation](https://docs.nestjs.com/)
+- [NestJS Best Practices](https://github.com/nestjs/awesome-nestjs)
+- [TypeORM Documentation](https://typeorm.io/)
+- [Passport.js Documentation](http://www.passportjs.org/)
+- [class-validator](https://github.com/typestack/class-validator)