Skip to content

HigorAlves/orc / codex/orc/content/skills/nestjs-best-practices

nestjs-best-practices

Verified

NestJS best practices and architecture patterns for production apps

FileKindSize
.github/workflows/branch-protection.ymlconfig760 B
.github/workflows/deploy.ymlconfig1.2 KB
.gitignoreother237 B
AGENTS.mdmarkdown159.2 KB
README.mdmarkdown4.4 KB
SKILL.mdskill md4.5 KB
rules/_sections.mdmarkdown2.1 KB
rules/_template.mdmarkdown631 B
rules/api-use-dto-serialization.mdmarkdown4.3 KB
rules/api-use-interceptors.mdmarkdown5.4 KB
rules/api-use-pipes.mdmarkdown5.3 KB
rules/api-versioning.mdmarkdown4.9 KB
rules/arch-avoid-circular-deps.mdmarkdown2.0 KB
rules/arch-feature-modules.mdmarkdown2.3 KB
rules/arch-module-sharing.mdmarkdown3.8 KB
rules/arch-single-responsibility.mdmarkdown2.9 KB
rules/arch-use-events.mdmarkdown3.0 KB
rules/arch-use-repository-pattern.mdmarkdown2.8 KB
rules/db-avoid-n-plus-one.mdmarkdown3.8 KB
rules/db-use-migrations.mdmarkdown3.7 KB
rules/db-use-transactions.mdmarkdown3.9 KB
rules/devops-graceful-shutdown.mdmarkdown5.8 KB
rules/devops-use-config-module.mdmarkdown4.3 KB
rules/devops-use-logging.mdmarkdown5.6 KB
rules/di-avoid-service-locator.mdmarkdown2.9 KB
rules/di-interface-segregation.mdmarkdown5.1 KB
rules/di-liskov-substitution.mdmarkdown7.1 KB
rules/di-prefer-constructor-injection.mdmarkdown2.3 KB
rules/di-scope-awareness.mdmarkdown2.6 KB
rules/di-use-interfaces-tokens.mdmarkdown2.5 KB
rules/error-handle-async-errors.mdmarkdown3.4 KB
rules/error-throw-http-exceptions.mdmarkdown3.1 KB
rules/error-use-exception-filters.mdmarkdown3.6 KB
rules/micro-use-health-checks.mdmarkdown5.8 KB
rules/micro-use-patterns.mdmarkdown5.0 KB
rules/micro-use-queues.mdmarkdown6.1 KB
rules/perf-async-hooks.mdmarkdown2.8 KB
rules/perf-lazy-loading.mdmarkdown3.7 KB
rules/perf-optimize-database.mdmarkdown3.2 KB
rules/perf-use-caching.mdmarkdown3.4 KB
rules/security-auth-jwt.mdmarkdown4.0 KB
rules/security-rate-limiting.mdmarkdown3.2 KB
rules/security-sanitize-output.mdmarkdown3.7 KB
rules/security-use-guards.mdmarkdown3.6 KB
rules/security-validate-all-input.mdmarkdown3.3 KB
rules/test-e2e-supertest.mdmarkdown4.7 KB
rules/test-mock-external-services.mdmarkdown4.5 KB
rules/test-use-testing-module.mdmarkdown4.3 KB
scripts/build-agents.tsscript8.5 KB
scripts/build.shexecutablescript369 B
scripts/package-lock.jsonmanifest8.5 KB
scripts/package.jsonmanifest428 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)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall