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/error-throw-http-exceptions.md

View on GitHub
---
title: Throw HTTP Exceptions from Services
impact: HIGH
impactDescription: Keeps controllers thin and simplifies error handling
tags: error-handling, exceptions, services
---

## Throw HTTP Exceptions from Services

It's acceptable (and often preferable) to throw `HttpException` subclasses from services in HTTP applications. This keeps controllers thin and allows services to communicate appropriate error states. For truly layer-agnostic services, use domain exceptions that map to HTTP status codes.

**Incorrect (return error objects instead of throwing):**

```typescript
// Return error objects instead of throwing
@Injectable()
export class UsersService {
  async findById(id: string): Promise<{ user?: User; error?: string }> {
    const user = await this.repo.findOne({ where: { id } });
    if (!user) {
      return { error: 'User not found' }; // Controller must check this
    }
    return { user };
  }
}

@Controller('users')
export class UsersController {
  @Get(':id')
  async findOne(@Param('id') id: string) {
    const result = await this.usersService.findById(id);
    if (result.error) {
      throw new NotFoundException(result.error);
    }
    return result.user;
  }
}
```

**Correct (throw exceptions directly from service):**

```typescript
// Throw exceptions directly from service
@Injectable()
export class UsersService {
  constructor(private readonly repo: UserRepository) {}

  async findById(id: string): Promise<User> {
    const user = await this.repo.findOne({ where: { id } });
    if (!user) {
      throw new NotFoundException(`User #${id} not found`);
    }
    return user;
  }

  async create(dto: CreateUserDto): Promise<User> {
    const existing = await this.repo.findOne({
      where: { email: dto.email },
    });
    if (existing) {
      throw new ConflictException('Email already registered');
    }
    return this.repo.save(dto);
  }

  async update(id: string, dto: UpdateUserDto): Promise<User> {
    const user = await this.findById(id); // Throws if not found
    Object.assign(user, dto);
    return this.repo.save(user);
  }
}

// Controller stays thin
@Controller('users')
export class UsersController {
  @Get(':id')
  findOne(@Param('id') id: string): Promise<User> {
    return this.usersService.findById(id);
  }

  @Post()
  create(@Body() dto: CreateUserDto): Promise<User> {
    return this.usersService.create(dto);
  }
}

// For layer-agnostic services, use domain exceptions
export class EntityNotFoundException extends Error {
  constructor(
    public readonly entity: string,
    public readonly id: string,
  ) {
    super(`${entity} with ID "${id}" not found`);
  }
}

// Map to HTTP in exception filter
@Catch(EntityNotFoundException)
export class EntityNotFoundFilter implements ExceptionFilter {
  catch(exception: EntityNotFoundException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();

    response.status(404).json({
      statusCode: 404,
      message: exception.message,
      entity: exception.entity,
      id: exception.id,
    });
  }
}
```

Reference: [NestJS Exception Filters](https://docs.nestjs.com/exception-filters)
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