giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-typescript/skills/nestjs
nestjs
VerifiedProvides comprehensive NestJS framework patterns with Drizzle ORM integration for building scalable server-side applications. Generates REST/GraphQL APIs, implements authentication guards, creates database schemas, and sets up microservices. Use when building NestJS applications, setting up APIs, implementing authentication, working with databases, or integrating Drizzle ORM.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.6 KB |
| references/best-practices.md | markdown | 1.4 KB |
| references/drizzle-reference.md | markdown | 51.2 KB |
| references/migrations.md | markdown | 1.1 KB |
| references/patterns.md | markdown | 11.2 KB |
| references/reference.md | markdown | 32.9 KB |
| references/testing.md | markdown | 3.4 KB |
| references/workflow-optimization.md | markdown | 6.0 KB |
references/reference.md
View on GitHub# NestJS Framework Documentation
NestJS is a progressive Node.js framework for building efficient, reliable and scalable server-side applications. Built with TypeScript and fully supporting both TypeScript and JavaScript, it combines elements of Object Oriented Programming (OOP), Functional Programming (FP), and Functional Reactive Programming (FRP). Under the hood, NestJS uses robust HTTP server frameworks like Express (default) or Fastify, providing a level of abstraction while exposing their APIs directly to developers.
The framework provides an out-of-the-box application architecture inspired by Angular, enabling developers to create highly testable, scalable, loosely coupled, and maintainable applications. NestJS leverages dependency injection, decorators, modules, guards, interceptors, and pipes to organize code effectively. It supports multiple transport layers for microservices, integrates seamlessly with databases through TypeORM and Sequelize, and provides first-class support for GraphQL and OpenAPI documentation.
## Core Building Blocks
### Creating a Basic Application
```typescript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```
### Controllers - HTTP Request Handling
```typescript
import { Controller, Get, Post, Put, Delete, Body, Param, Query } from '@nestjs/common';
import { CreateCatDto, UpdateCatDto } from './dto';
import { CatsService } from './cats.service';
@Controller('cats')
export class CatsController {
constructor(private catsService: CatsService) {}
@Post()
async create(@Body() createCatDto: CreateCatDto) {
this.catsService.create(createCatDto);
return { message: 'Cat created successfully' };
}
@Get()
async findAll(@Query('age') age?: number, @Query('breed') breed?: string) {
return this.catsService.findAll({ age, breed });
}
@Get(':id')
async findOne(@Param('id') id: string) {
return this.catsService.findOne(id);
}
@Put(':id')
async update(@Param('id') id: string, @Body() updateCatDto: UpdateCatDto) {
return this.catsService.update(id, updateCatDto);
}
@Delete(':id')
async remove(@Param('id') id: string) {
await this.catsService.remove(id);
return { message: 'Cat removed successfully' };
}
}
```
### Providers - Business Logic and Services
```typescript
import { Injectable } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';
@Injectable()
export class CatsService {
private readonly cats: Cat[] = [];
create(cat: Cat): void {
this.cats.push(cat);
}
findAll(filter?: { age?: number; breed?: string }): Cat[] {
if (!filter) return this.cats;
return this.cats.filter(cat => {
if (filter.age && cat.age !== filter.age) return false;
if (filter.breed && cat.breed !== filter.breed) return false;
return true;
});
}
findOne(id: string): Cat | undefined {
return this.cats.find(cat => cat.id === id);
}
update(id: string, updateData: Partial): Cat {
const catIndex = this.cats.findIndex(cat => cat.id === id);
if (catIndex === -1) throw new Error('Cat not found');
this.cats[catIndex] = { ...this.cats[catIndex], ...updateData };
return this.cats[catIndex];
}
remove(id: string): void {
const catIndex = this.cats.findIndex(cat => cat.id === id);
if (catIndex === -1) throw new Error('Cat not found');
this.cats.splice(catIndex, 1);
}
}
```
### Modules - Application Organization
```typescript
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';
@Module({
controllers: [CatsController],
providers: [CatsService],
exports: [CatsService], // Make service available to other modules
})
export class CatsModule {}
// Root module
import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';
import { DogsModule } from './dogs/dogs.module';
@Module({
imports: [CatsModule, DogsModule],
})
export class AppModule {}
```
## Middleware
### Class-Based Middleware
```typescript
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
console.log(`[${new Date().toISOString()}] ${req.method} ${req.path}`);
next();
}
}
// Apply in module
import { Module, NestModule, MiddlewareConsumer, RequestMethod } from '@nestjs/common';
@Module({
imports: [CatsModule],
})
export class AppModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
consumer
.apply(LoggerMiddleware)
.exclude(
{ path: 'cats', method: RequestMethod.GET },
'cats/{*splat}',
)
.forRoutes(CatsController);
}
}
```
### Functional Middleware
```typescript
import { Request, Response, NextFunction } from 'express';
export function logger(req: Request, res: Response, next: NextFunction) {
console.log(`Request...`);
next();
}
// Apply in module
consumer.apply(logger).forRoutes(CatsController);
// Global middleware
const app = await NestFactory.create(AppModule);
app.use(logger);
await app.listen(3000);
```
## Exception Filters
### Built-in Exception Handling
```typescript
import { Controller, Get, Post, Body, HttpException, HttpStatus } from '@nestjs/common';
@Controller('cats')
export class CatsController {
@Get()
async findAll() {
throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
}
@Post()
async create(@Body() createCatDto: CreateCatDto) {
throw new HttpException({
status: HttpStatus.FORBIDDEN,
error: 'This is a custom message',
}, HttpStatus.FORBIDDEN);
}
}
```
### Custom Exception Filter
```typescript
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse();
const request = ctx.getRequest();
const status = exception.getStatus();
response.status(status).json({
statusCode: status,
timestamp: new Date().toISOString(),
path: request.url,
message: exception.message,
});
}
}
// Apply to controller or method
import { UseFilters } from '@nestjs/common';
@Post()
@UseFilters(new HttpExceptionFilter())
async create(@Body() createCatDto: CreateCatDto) {
throw new ForbiddenException();
}
// Global exception filter
const app = await NestFactory.create(AppModule);
app.useGlobalFilters(new HttpExceptionFilter());
// Global with dependency injection
@Module({
providers: [
{
provide: APP_FILTER,
useClass: HttpExceptionFilter,
},
],
})
export class AppModule {}
```
### Catch-All Exception Filter
```typescript
import { Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
constructor(private readonly httpAdapterHost: HttpAdapterHost) {}
catch(exception: unknown, host: ArgumentsHost): void {
const { httpAdapter } = this.httpAdapterHost;
const ctx = host.switchToHttp();
const httpStatus = exception instanceof HttpException
? exception.getStatus()
: HttpStatus.INTERNAL_SERVER_ERROR;
const responseBody = {
statusCode: httpStatus,
timestamp: new Date().toISOString(),
path: httpAdapter.getRequestUrl(ctx.getRequest()),
message: exception instanceof Error ? exception.message : 'Internal server error',
};
httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
}
}
```
## Pipes
### Built-in Transformation Pipes
```typescript
import { Controller, Get, Param, Query, ParseIntPipe, ParseUUIDPipe } from '@nestjs/common';
@Controller('cats')
export class CatsController {
@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
return this.catsService.findOne(id);
}
@Get('user/:uuid')
async findByUser(@Param('uuid', ParseUUIDPipe) uuid: string) {
return this.catsService.findByUser(uuid);
}
@Get()
async findAll(@Query('page', ParseIntPipe) page: number) {
return this.catsService.findAll(page);
}
}
```
### Validation Pipe with class-validator
```typescript
import { IsString, IsInt, Min, Max } from 'class-validator';
export class CreateCatDto {
@IsString()
name: string;
@IsInt()
@Min(0)
@Max(30)
age: number;
@IsString()
breed: string;
}
// Apply validation pipe
import { Controller, Post, Body, UsePipes, ValidationPipe } from '@nestjs/common';
@Controller('cats')
export class CatsController {
@Post()
@UsePipes(new ValidationPipe())
async create(@Body() createCatDto: CreateCatDto) {
return this.catsService.create(createCatDto);
}
}
// Global validation pipe
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true,
transform: true,
}));
await app.listen(3000);
}
// With dependency injection
@Module({
providers: [
{
provide: APP_PIPE,
useClass: ValidationPipe,
},
],
})
export class AppModule {}
```
### Custom Transformation Pipe
```typescript
import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';
@Injectable()
export class ParseIntPipe implements PipeTransform {
transform(value: string, metadata: ArgumentMetadata): number {
const val = parseInt(value, 10);
if (isNaN(val)) {
throw new BadRequestException('Validation failed (numeric string is expected)');
}
return val;
}
}
@Get(':id')
async findOne(@Param('id', new ParseIntPipe()) id: number) {
return this.catsService.findOne(id);
}
```
### Schema Validation with Zod
```typescript
import { PipeTransform, ArgumentMetadata, BadRequestException } from '@nestjs/common';
import { ZodSchema } from 'zod';
export class ZodValidationPipe implements PipeTransform {
constructor(private schema: ZodSchema) {}
transform(value: unknown, metadata: ArgumentMetadata) {
try {
const parsedValue = this.schema.parse(value);
return parsedValue;
} catch (error) {
throw new BadRequestException('Validation failed');
}
}
}
// Define schema
import { z } from 'zod';
export const createCatSchema = z.object({
name: z.string(),
age: z.number().min(0).max(30),
breed: z.string(),
}).required();
export type CreateCatDto = z.infer;
// Use in controller
@Post()
@UsePipes(new ZodValidationPipe(createCatSchema))
async create(@Body() createCatDto: CreateCatDto) {
return this.catsService.create(createCatDto);
}
```
## Guards
### Authentication Guard
```typescript
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';
import { Observable } from 'rxjs';
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean | Promise | Observable {
const request = context.switchToHttp().getRequest();
const token = request.headers.authorization;
if (!token) {
throw new UnauthorizedException('No token provided');
}
try {
// Validate token logic here
const user = this.validateToken(token);
request.user = user;
return true;
} catch (error) {
throw new UnauthorizedException('Invalid token');
}
}
private validateToken(token: string) {
// Token validation logic
return { id: '123', username: 'john' };
}
}
// Apply guard
import { Controller, Get, UseGuards } from '@nestjs/common';
@Controller('cats')
@UseGuards(AuthGuard)
export class CatsController {
@Get()
findAll() {
return this.catsService.findAll();
}
}
```
### Role-Based Authorization Guard
```typescript
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
// Custom decorator
export const Roles = Reflector.createDecorator();
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const roles = this.reflector.get(Roles, context.getHandler());
if (!roles) {
return true;
}
const request = context.switchToHttp().getRequest();
const user = request.user;
return this.matchRoles(roles, user.roles);
}
private matchRoles(requiredRoles: string[], userRoles: string[]): boolean {
return requiredRoles.some(role => userRoles.includes(role));
}
}
// Use in controller
@Post()
@Roles(['admin'])
@UseGuards(RolesGuard)
async create(@Body() createCatDto: CreateCatDto) {
return this.catsService.create(createCatDto);
}
// Global guard with DI
@Module({
providers: [
{
provide: APP_GUARD,
useClass: RolesGuard,
},
],
})
export class AppModule {}
```
## Interceptors
### Logging Interceptor
```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable {
const request = context.switchToHttp().getRequest();
const { method, url } = request;
const now = Date.now();
console.log(`[${method}] ${url} - Start`);
return next.handle().pipe(
tap(() => {
console.log(`[${method}] ${url} - Completed in ${Date.now() - now}ms`);
}),
);
}
}
@UseInterceptors(LoggingInterceptor)
@Controller('cats')
export class CatsController {}
```
### Response Transformation Interceptor
```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
export interface Response {
data: T;
timestamp: string;
path: string;
}
@Injectable()
export class TransformInterceptor implements NestInterceptor> {
intercept(context: ExecutionContext, next: CallHandler): Observable> {
const request = context.switchToHttp().getRequest();
return next.handle().pipe(
map(data => ({
data,
timestamp: new Date().toISOString(),
path: request.url,
})),
);
}
}
// Result: GET /cats returns { data: [...], timestamp: "...", path: "/cats" }
```
### Cache Interceptor
```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable, of } from 'rxjs';
@Injectable()
export class CacheInterceptor implements NestInterceptor {
private cache = new Map();
intercept(context: ExecutionContext, next: CallHandler): Observable {
const request = context.switchToHttp().getRequest();
const cacheKey = `${request.method}:${request.url}`;
if (this.cache.has(cacheKey)) {
console.log('Returning cached response');
return of(this.cache.get(cacheKey));
}
return next.handle().pipe(
tap(response => {
this.cache.set(cacheKey, response);
}),
);
}
}
```
### Timeout Interceptor
```typescript
import { Injectable, NestInterceptor, ExecutionContext, CallHandler, RequestTimeoutException } from '@nestjs/common';
import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';
@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable {
return next.handle().pipe(
timeout(5000),
catchError(err => {
if (err instanceof TimeoutError) {
return throwError(() => new RequestTimeoutException('Request timeout'));
}
return throwError(() => err);
}),
);
}
}
```
## Dependency Injection
### Constructor Injection
```typescript
@Injectable()
export class CatsService {
constructor(
private readonly dogsService: DogsService,
private readonly configService: ConfigService,
) {}
async findAll() {
const config = this.configService.get('database');
return this.catsRepository.find();
}
}
```
### Custom Provider with Token
```typescript
const CONNECTION = 'DATABASE_CONNECTION';
@Module({
providers: [
{
provide: CONNECTION,
useValue: {
host: 'localhost',
port: 5432,
database: 'test',
},
},
],
})
export class DatabaseModule {}
// Inject custom provider
@Injectable()
export class CatsRepository {
constructor(@Inject(CONNECTION) private connection: any) {}
}
```
### Factory Provider
```typescript
@Module({
providers: [
{
provide: 'DATABASE_CONNECTION',
useFactory: async (configService: ConfigService) => {
const config = configService.get('database');
const connection = await createConnection(config);
return connection;
},
inject: [ConfigService],
},
],
})
export class DatabaseModule {}
```
### Async Provider
```typescript
@Module({
providers: [
{
provide: 'ASYNC_CONNECTION',
useFactory: async () => {
const connection = await createAsyncConnection();
return connection;
},
},
],
})
export class AppModule {}
```
### Class Provider with Conditional Logic
```typescript
const configServiceProvider = {
provide: ConfigService,
useClass: process.env.NODE_ENV === 'development'
? DevelopmentConfigService
: ProductionConfigService,
};
@Module({
providers: [configServiceProvider],
})
export class AppModule {}
```
## Database Integration
### TypeORM Setup
```typescript
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
@Module({
imports: [
TypeOrmModule.forRoot({
type: 'postgres',
host: 'localhost',
port: 5432,
username: 'postgres',
password: 'password',
database: 'nest_db',
entities: [__dirname + '/**/*.entity{.ts,.js}'],
synchronize: true, // Don't use in production
logging: true,
}),
],
})
export class AppModule {}
```
### Entity Definition
```typescript
import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn, OneToMany } from 'typeorm';
import { Photo } from '../photos/photo.entity';
@Entity('users')
export class User {
@PrimaryGeneratedColumn('uuid')
id: string;
@Column({ unique: true })
email: string;
@Column()
firstName: string;
@Column()
lastName: string;
@Column({ default: true })
isActive: boolean;
@CreateDateColumn()
createdAt: Date;
@UpdateDateColumn()
updatedAt: Date;
@OneToMany(() => Photo, photo => photo.user)
photos: Photo[];
}
```
### Repository Pattern
```typescript
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './user.entity';
@Injectable()
export class UsersService {
constructor(
@InjectRepository(User)
private usersRepository: Repository,
) {}
async findAll(): Promise {
return this.usersRepository.find({ relations: ['photos'] });
}
async findOne(id: string): Promise {
const user = await this.usersRepository.findOne({
where: { id },
relations: ['photos'],
});
if (!user) throw new NotFoundException('User not found');
return user;
}
async create(userData: CreateUserDto): Promise {
const user = this.usersRepository.create(userData);
return this.usersRepository.save(user);
}
async update(id: string, updateData: UpdateUserDto): Promise {
await this.usersRepository.update(id, updateData);
return this.findOne(id);
}
async remove(id: string): Promise {
const result = await this.usersRepository.delete(id);
if (result.affected === 0) {
throw new NotFoundException('User not found');
}
}
}
@Module({
imports: [TypeOrmModule.forFeature([User])],
providers: [UsersService],
controllers: [UsersController],
exports: [UsersService],
})
export class UsersModule {}
```
### Database Transactions
```typescript
import { DataSource } from 'typeorm';
@Injectable()
export class UsersService {
constructor(
@InjectRepository(User) private usersRepository: Repository,
private dataSource: DataSource,
) {}
async createUserWithPhotos(userData: CreateUserDto, photos: CreatePhotoDto[]) {
const queryRunner = this.dataSource.createQueryRunner();
await queryRunner.connect();
await queryRunner.startTransaction();
try {
const user = await queryRunner.manager.save(User, userData);
for (const photoData of photos) {
await queryRunner.manager.save(Photo, { ...photoData, user });
}
await queryRunner.commitTransaction();
return user;
} catch (err) {
await queryRunner.rollbackTransaction();
throw err;
} finally {
await queryRunner.release();
}
}
}
```
### Async Configuration
```typescript
TypeOrmModule.forRootAsync({
imports: [ConfigModule],
useFactory: (configService: ConfigService) => ({
type: 'postgres',
host: configService.get('DB_HOST'),
port: configService.get('DB_PORT'),
username: configService.get('DB_USERNAME'),
password: configService.get('DB_PASSWORD'),
database: configService.get('DB_NAME'),
entities: [__dirname + '/**/*.entity{.ts,.js}'],
synchronize: configService.get('DB_SYNC') === 'true',
}),
inject: [ConfigService],
})
```
## Testing
### Unit Testing with Mocks
```typescript
import { Test, TestingModule } from '@nestjs/testing';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';
describe('CatsController', () => {
let catsController: CatsController;
let catsService: CatsService;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
controllers: [CatsController],
providers: [CatsService],
}).compile();
catsService = module.get(CatsService);
catsController = module.get(CatsController);
});
describe('findAll', () => {
it('should return an array of cats', async () => {
const result = [{ name: 'Test Cat', age: 2, breed: 'Persian' }];
jest.spyOn(catsService, 'findAll').mockImplementation(() => Promise.resolve(result));
expect(await catsController.findAll()).toBe(result);
});
});
describe('create', () => {
it('should create a cat', async () => {
const catDto = { name: 'New Cat', age: 1, breed: 'Siamese' };
jest.spyOn(catsService, 'create').mockImplementation(() => Promise.resolve(catDto));
expect(await catsController.create(catDto)).toEqual(catDto);
});
});
});
```
### Testing with Provider Override
```typescript
describe('CatsController', () => {
let controller: CatsController;
const mockCatsService = {
findAll: jest.fn(() => [{ name: 'Test', age: 2, breed: 'Persian' }]),
findOne: jest.fn((id) => ({ id, name: 'Test', age: 2, breed: 'Persian' })),
create: jest.fn((dto) => ({ id: '123', ...dto })),
};
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
controllers: [CatsController],
providers: [CatsService],
})
.overrideProvider(CatsService)
.useValue(mockCatsService)
.compile();
controller = module.get(CatsController);
});
it('should be defined', () => {
expect(controller).toBeDefined();
});
});
```
### End-to-End Testing
```typescript
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from './../src/app.module';
describe('CatsController (e2e)', () => {
let app: INestApplication;
beforeAll(async () => {
const moduleFixture: TestingModule = await Test.createTestingModule({
imports: [AppModule],
}).compile();
app = moduleFixture.createNestApplication();
await app.init();
});
afterAll(async () => {
await app.close();
});
it('/cats (GET)', () => {
return request(app.getHttpServer())
.get('/cats')
.expect(200)
.expect((res) => {
expect(Array.isArray(res.body)).toBe(true);
});
});
it('/cats (POST)', () => {
return request(app.getHttpServer())
.post('/cats')
.send({ name: 'Test Cat', age: 2, breed: 'Persian' })
.expect(201)
.expect((res) => {
expect(res.body).toHaveProperty('id');
expect(res.body.name).toBe('Test Cat');
});
});
it('/cats/:id (GET)', () => {
return request(app.getHttpServer())
.get('/cats/123')
.expect(200)
.expect((res) => {
expect(res.body).toHaveProperty('id', '123');
});
});
});
```
### Testing with Repository Mocks
```typescript
describe('UsersService', () => {
let service: UsersService;
let repository: Repository;
const mockRepository = {
find: jest.fn(),
findOne: jest.fn(),
create: jest.fn(),
save: jest.fn(),
update: jest.fn(),
delete: jest.fn(),
};
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
UsersService,
{
provide: getRepositoryToken(User),
useValue: mockRepository,
},
],
}).compile();
service = module.get(UsersService);
repository = module.get>(getRepositoryToken(User));
});
it('should find all users', async () => {
const users = [{ id: '1', email: 'test@example.com' }];
mockRepository.find.mockResolvedValue(users);
expect(await service.findAll()).toEqual(users);
expect(repository.find).toHaveBeenCalled();
});
});
```
## Microservices
### TCP Microservice Setup
```typescript
import { NestFactory } from '@nestjs/core';
import { Transport, MicroserviceOptions } from '@nestjs/microservices';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.createMicroservice(
AppModule,
{
transport: Transport.TCP,
options: {
host: '127.0.0.1',
port: 8877,
},
},
);
await app.listen();
}
bootstrap();
```
### Message Pattern Handler
```typescript
import { Controller } from '@nestjs/common';
import { MessagePattern, Payload, Ctx, NatsContext } from '@nestjs/microservices';
@Controller()
export class MathController {
@MessagePattern({ cmd: 'sum' })
accumulate(@Payload() data: number[]): number {
return (data || []).reduce((a, b) => a + b, 0);
}
@MessagePattern({ cmd: 'multiply' })
multiply(@Payload() data: { a: number; b: number }): number {
return data.a * data.b;
}
}
```
### Event Pattern Handler
```typescript
@Controller()
export class NotificationsController {
@EventPattern('user_created')
async handleUserCreated(@Payload() data: CreateUserEvent) {
console.log('New user created:', data);
// Send welcome email
await this.emailService.sendWelcome(data.email);
}
@EventPattern('order_placed')
async handleOrderPlaced(@Payload() data: OrderPlacedEvent) {
console.log('Order placed:', data);
// Process order
await this.orderService.process(data);
}
}
```
### Microservice Client
```typescript
import { Module } from '@nestjs/common';
import { ClientsModule, Transport } from '@nestjs/microservices';
@Module({
imports: [
ClientsModule.register([
{
name: 'MATH_SERVICE',
transport: Transport.TCP,
options: {
host: '127.0.0.1',
port: 8877,
},
},
]),
],
controllers: [AppController],
})
export class AppModule {}
// Use in controller
import { Controller, Get, Inject } from '@nestjs/common';
import { ClientProxy } from '@nestjs/microservices';
import { Observable } from 'rxjs';
@Controller()
export class AppController {
constructor(@Inject('MATH_SERVICE') private client: ClientProxy) {}
@Get('sum')
accumulate(): Observable {
const pattern = { cmd: 'sum' };
const payload = [1, 2, 3, 4, 5];
return this.client.send(pattern, payload);
}
@Get('notify')
async notify() {
this.client.emit('user_created', { id: '123', email: 'user@example.com' });
return { message: 'Notification sent' };
}
}
```
### Redis Transport
```typescript
// Microservice
const app = await NestFactory.createMicroservice(
AppModule,
{
transport: Transport.REDIS,
options: {
host: 'localhost',
port: 6379,
},
},
);
// Client
ClientsModule.register([
{
name: 'REDIS_SERVICE',
transport: Transport.REDIS,
options: {
host: 'localhost',
port: 6379,
},
},
])
```
## GraphQL
### Apollo GraphQL Setup
```typescript
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { join } from 'path';
@Module({
imports: [
GraphQLModule.forRoot({
driver: ApolloDriver,
autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
sortSchema: true,
playground: true,
}),
],
})
export class AppModule {}
```
### GraphQL Resolvers (Code First)
```typescript
import { Resolver, Query, Mutation, Args, ID } from '@nestjs/graphql';
import { ObjectType, Field, Int } from '@nestjs/graphql';
@ObjectType()
export class Cat {
@Field(() => ID)
id: string;
@Field()
name: string;
@Field(() => Int)
age: number;
@Field()
breed: string;
}
@Resolver(() => Cat)
export class CatsResolver {
constructor(private catsService: CatsService) {}
@Query(() => [Cat], { name: 'cats' })
async findAll() {
return this.catsService.findAll();
}
@Query(() => Cat, { name: 'cat' })
async findOne(@Args('id', { type: () => ID }) id: string) {
return this.catsService.findOne(id);
}
@Mutation(() => Cat)
async createCat(
@Args('name') name: string,
@Args('age', { type: () => Int }) age: number,
@Args('breed') breed: string,
) {
return this.catsService.create({ name, age, breed });
}
@Mutation(() => Boolean)
async removeCat(@Args('id', { type: () => ID }) id: string) {
await this.catsService.remove(id);
return true;
}
}
```
### GraphQL Input Types
```typescript
import { InputType, Field, Int } from '@nestjs/graphql';
@InputType()
export class CreateCatInput {
@Field()
name: string;
@Field(() => Int)
age: number;
@Field()
breed: string;
}
@Mutation(() => Cat)
async createCat(@Args('input') input: CreateCatInput) {
return this.catsService.create(input);
}
```
## OpenAPI/Swagger Documentation
### Basic Swagger Setup
```typescript
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('Cats API')
.setDescription('The cats API documentation')
.setVersion('1.0')
.addTag('cats')
.addBearerAuth()
.build();
const documentFactory = () => SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, documentFactory);
await app.listen(3000);
}
bootstrap();
// Access at http://localhost:3000/api
```
### API Decorators
```typescript
import { ApiTags, ApiOperation, ApiResponse, ApiProperty, ApiBearerAuth } from '@nestjs/swagger';
export class CreateCatDto {
@ApiProperty({ example: 'Fluffy', description: 'The name of the cat' })
name: string;
@ApiProperty({ example: 3, description: 'The age of the cat' })
age: number;
@ApiProperty({ example: 'Persian', description: 'The breed of the cat' })
breed: string;
}
@ApiTags('cats')
@Controller('cats')
export class CatsController {
@Post()
@ApiOperation({ summary: 'Create a new cat' })
@ApiResponse({ status: 201, description: 'The cat has been successfully created.', type: Cat })
@ApiResponse({ status: 400, description: 'Bad Request.' })
@ApiBearerAuth()
async create(@Body() createCatDto: CreateCatDto) {
return this.catsService.create(createCatDto);
}
@Get()
@ApiOperation({ summary: 'Get all cats' })
@ApiResponse({ status: 200, description: 'Return all cats.', type: [Cat] })
async findAll() {
return this.catsService.findAll();
}
}
```
## Configuration
### Environment Configuration
```typescript
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
envFilePath: ['.env.local', '.env'],
ignoreEnvFile: process.env.NODE_ENV === 'production',
}),
],
})
export class AppModule {}
// Use in service
@Injectable()
export class AppService {
constructor(private configService: ConfigService) {}
getDatabaseConfig() {
return {
host: this.configService.get('DB_HOST'),
port: this.configService.get('DB_PORT'),
};
}
}
```
### Custom Configuration Files
```typescript
export default () => ({
port: parseInt(process.env.PORT, 10) || 3000,
database: {
host: process.env.DATABASE_HOST || 'localhost',
port: parseInt(process.env.DATABASE_PORT, 10) || 5432,
username: process.env.DATABASE_USERNAME,
password: process.env.DATABASE_PASSWORD,
},
jwt: {
secret: process.env.JWT_SECRET,
expiresIn: '7d',
},
});
// Import in module
import configuration from './config/configuration';
@Module({
imports: [
ConfigModule.forRoot({
load: [configuration],
}),
],
})
export class AppModule {}
// Access nested config
const dbHost = this.configService.get('database.host');
```
## Summary
NestJS provides a comprehensive framework for building scalable server-side applications with a focus on maintainability and testability. The framework's modular architecture, combined with dependency injection and decorators, enables developers to structure applications effectively. Core building blocks include controllers for handling HTTP requests, providers for business logic, modules for organization, and middleware for request processing. Advanced features like guards, interceptors, and pipes enable cross-cutting concerns such as authentication, logging, validation, and transformation.
The framework excels in enterprise applications through its support for microservices architecture with multiple transport layers, database integration via TypeORM and Sequelize, GraphQL API development, and comprehensive testing utilities. NestJS's decorator-based approach and TypeScript support provide excellent developer experience with type safety and IDE integration. The framework's extensibility allows integration with various libraries and tools while maintaining clean architecture principles. Whether building REST APIs, GraphQL servers, microservices, or WebSocket applications, NestJS provides the tools and patterns needed for production-ready applications with proper error handling, validation, logging, and documentation through OpenAPI/Swagger integration.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |