Skip to content

ever-co/ever-works / .agents/skills/nestjs-best-practices

nestjs-best-practices

Verified

NestJS best practices and architecture patterns for building production-ready applications. This skill should be used when writing, reviewing, or refactoring NestJS code to ensure proper patterns for modules, dependency injection, security, and performance.

FileKindSize
AGENTS.mdmarkdown154.2 KB
README.mdmarkdown4.7 KB
SKILL.mdskill md4.8 KB
rules/_sections.mdmarkdown2.1 KB
rules/_template.mdmarkdown633 B
rules/api-use-dto-serialization.mdmarkdown4.2 KB
rules/api-use-interceptors.mdmarkdown5.4 KB
rules/api-use-pipes.mdmarkdown5.3 KB
rules/api-versioning.mdmarkdown4.7 KB
rules/arch-avoid-circular-deps.mdmarkdown1.9 KB
rules/arch-feature-modules.mdmarkdown2.3 KB
rules/arch-module-sharing.mdmarkdown3.7 KB
rules/arch-single-responsibility.mdmarkdown2.8 KB
rules/arch-use-events.mdmarkdown2.9 KB
rules/arch-use-repository-pattern.mdmarkdown2.7 KB
rules/db-avoid-n-plus-one.mdmarkdown3.8 KB
rules/db-use-migrations.mdmarkdown3.7 KB
rules/db-use-transactions.mdmarkdown3.6 KB
rules/devops-graceful-shutdown.mdmarkdown5.5 KB
rules/devops-use-config-module.mdmarkdown4.2 KB
rules/devops-use-logging.mdmarkdown5.1 KB
rules/di-avoid-service-locator.mdmarkdown2.8 KB
rules/di-interface-segregation.mdmarkdown5.0 KB
rules/di-liskov-substitution.mdmarkdown6.8 KB
rules/di-prefer-constructor-injection.mdmarkdown2.2 KB
rules/di-scope-awareness.mdmarkdown2.5 KB
rules/di-use-interfaces-tokens.mdmarkdown2.5 KB
rules/error-handle-async-errors.mdmarkdown3.4 KB
rules/error-throw-http-exceptions.mdmarkdown3.0 KB
rules/error-use-exception-filters.mdmarkdown3.4 KB
rules/micro-use-health-checks.mdmarkdown6.1 KB
rules/micro-use-patterns.mdmarkdown5.0 KB
rules/micro-use-queues.mdmarkdown5.7 KB
rules/perf-async-hooks.mdmarkdown2.8 KB
rules/perf-lazy-loading.mdmarkdown3.6 KB
rules/perf-optimize-database.mdmarkdown3.0 KB
rules/perf-use-caching.mdmarkdown3.3 KB
rules/security-auth-jwt.mdmarkdown3.8 KB
rules/security-rate-limiting.mdmarkdown3.1 KB
rules/security-sanitize-output.mdmarkdown3.7 KB
rules/security-use-guards.mdmarkdown3.4 KB
rules/security-validate-all-input.mdmarkdown3.2 KB
rules/test-e2e-supertest.mdmarkdown4.4 KB
rules/test-mock-external-services.mdmarkdown4.2 KB
rules/test-use-testing-module.mdmarkdown4.1 KB
scripts/build-agents.tsscript8.1 KB
scripts/build.shscript369 B
scripts/package-lock.jsonmanifest7.7 KB
scripts/package.jsonmanifest410 B

rules/api-use-dto-serialization.md

View on GitHub
---
title: Use DTOs and Serialization for API Responses
impact: MEDIUM
impactDescription: Response DTOs prevent accidental data exposure and ensure consistency
tags: api, dto, serialization, class-transformer
---

## Use DTOs and Serialization for API Responses

Never return entity objects directly from controllers. Use response DTOs with class-transformer's `@Exclude()` and `@Expose()` decorators to control exactly what data is sent to clients. This prevents accidental exposure of sensitive fields and provides a stable API contract.

**Incorrect (returning entities directly or manual spreading):**

```typescript
// Return entities directly
@Controller('users')
export class UsersController {
  @Get(':id')
  async findOne(@Param('id') id: string): Promise<User> {
    return this.usersService.findById(id);
    // Returns: { id, email, passwordHash, ssn, internalNotes, ... }
    // Exposes sensitive data!
  }
}

// Manual object spreading (error-prone)
@Get(':id')
async findOne(@Param('id') id: string) {
  const user = await this.usersService.findById(id);
  return {
    id: user.id,
    email: user.email,
    name: user.name,
    // Easy to forget to exclude sensitive fields
    // Hard to maintain across endpoints
  };
}
```

**Correct (use class-transformer with @Exclude and response DTOs):**

```typescript
// Enable class-transformer globally
async function bootstrap() {
	const app = await NestFactory.create(AppModule);
	app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
	await app.listen(3000);
}

// Entity with serialization control
@Entity()
export class User {
	@PrimaryGeneratedColumn('uuid')
	id: string;

	@Column()
	email: string;

	@Column()
	name: string;

	@Column()
	@Exclude() // Never include in responses
	passwordHash: string;

	@Column({ nullable: true })
	@Exclude()
	ssn: string;

	@Column({ default: false })
	@Exclude({ toPlainOnly: true }) // Exclude from response, allow in requests
	isAdmin: boolean;

	@CreateDateColumn()
	createdAt: Date;

	@Column()
	@Exclude()
	internalNotes: string;
}

// Now returning entity is safe
@Controller('users')
export class UsersController {
	@Get(':id')
	async findOne(@Param('id') id: string): Promise<User> {
		return this.usersService.findById(id);
		// Returns: { id, email, name, createdAt }
		// Sensitive fields excluded automatically
	}
}

// For different response shapes, use explicit DTOs
export class UserResponseDto {
	@Expose()
	id: string;

	@Expose()
	email: string;

	@Expose()
	name: string;

	@Expose()
	@Transform(({ obj }) => obj.posts?.length || 0)
	postCount: number;

	constructor(partial: Partial<User>) {
		Object.assign(this, partial);
	}
}

export class UserDetailResponseDto extends UserResponseDto {
	@Expose()
	createdAt: Date;

	@Expose()
	@Type(() => PostResponseDto)
	posts: PostResponseDto[];
}

// Controller with explicit DTOs
@Controller('users')
export class UsersController {
	@Get()
	@SerializeOptions({ type: UserResponseDto })
	async findAll(): Promise<UserResponseDto[]> {
		const users = await this.usersService.findAll();
		return users.map((u) => plainToInstance(UserResponseDto, u));
	}

	@Get(':id')
	async findOne(@Param('id') id: string): Promise<UserDetailResponseDto> {
		const user = await this.usersService.findByIdWithPosts(id);
		return plainToInstance(UserDetailResponseDto, user, {
			excludeExtraneousValues: true
		});
	}
}

// Groups for conditional serialization
export class UserDto {
	@Expose()
	id: string;

	@Expose()
	name: string;

	@Expose({ groups: ['admin'] })
	email: string;

	@Expose({ groups: ['admin'] })
	createdAt: Date;

	@Expose({ groups: ['admin', 'owner'] })
	settings: UserSettings;
}

@Controller('users')
export class UsersController {
	@Get()
	@SerializeOptions({ groups: ['public'] })
	async findAllPublic(): Promise<UserDto[]> {
		// Returns: { id, name }
	}

	@Get('admin')
	@UseGuards(AdminGuard)
	@SerializeOptions({ groups: ['admin'] })
	async findAllAdmin(): Promise<UserDto[]> {
		// Returns: { id, name, email, createdAt }
	}

	@Get('me')
	@SerializeOptions({ groups: ['owner'] })
	async getProfile(@CurrentUser() user: User): Promise<UserDto> {
		// Returns: { id, name, settings }
	}
}
```

Reference: [NestJS Serialization](https://docs.nestjs.com/techniques/serialization)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall