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-handle-async-errors.md

View on GitHub
---
title: Handle Async Errors Properly
impact: HIGH
impactDescription: Prevents process crashes from unhandled rejections
tags: error-handling, async, promises
---

## Handle Async Errors Properly

NestJS automatically catches errors from async route handlers, but errors from background tasks, event handlers, and manually created promises can crash your application. Always handle async errors explicitly and use global handlers as a safety net.

**Incorrect (fire-and-forget without error handling):**

```typescript
// Fire-and-forget without error handling
@Injectable()
export class UsersService {
  async createUser(dto: CreateUserDto): Promise<User> {
    const user = await this.repo.save(dto);

    // Fire and forget - if this fails, error is unhandled!
    this.emailService.sendWelcome(user.email);

    return user;
  }
}

// Unhandled promise in event handler
@Injectable()
export class OrdersService {
  @OnEvent('order.created')
  handleOrderCreated(event: OrderCreatedEvent) {
    // This returns a promise but it's not awaited!
    this.processOrder(event);
    // Errors will crash the process
  }

  private async processOrder(event: OrderCreatedEvent): Promise<void> {
    await this.inventoryService.reserve(event.items);
    await this.notificationService.send(event.userId);
  }
}

// Missing try-catch in scheduled tasks
@Cron('0 0 * * *')
async dailyCleanup(): Promise<void> {
  await this.cleanupService.run();
  // If this throws, no error handling
}
```

**Correct (explicit async error handling):**

```typescript
// Handle fire-and-forget with explicit catch
@Injectable()
export class UsersService {
  private readonly logger = new Logger(UsersService.name);

  async createUser(dto: CreateUserDto): Promise<User> {
    const user = await this.repo.save(dto);

    // Explicitly catch and log errors
    this.emailService.sendWelcome(user.email).catch((error) => {
      this.logger.error('Failed to send welcome email', error.stack);
      // Optionally queue for retry
    });

    return user;
  }
}

// Properly handle async event handlers
@Injectable()
export class OrdersService {
  private readonly logger = new Logger(OrdersService.name);

  @OnEvent('order.created')
  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
    try {
      await this.processOrder(event);
    } catch (error) {
      this.logger.error('Failed to process order', { event, error });
      // Don't rethrow - would crash the process
      await this.deadLetterQueue.add('order.created', event);
    }
  }
}

// Safe scheduled tasks
@Injectable()
export class CleanupService {
  private readonly logger = new Logger(CleanupService.name);

  @Cron('0 0 * * *')
  async dailyCleanup(): Promise<void> {
    try {
      await this.cleanupService.run();
      this.logger.log('Daily cleanup completed');
    } catch (error) {
      this.logger.error('Daily cleanup failed', error.stack);
      // Alert or retry logic
    }
  }
}

// Global unhandled rejection handler in main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const logger = new Logger('Bootstrap');

  process.on('unhandledRejection', (reason, promise) => {
    logger.error('Unhandled Rejection at:', promise, 'reason:', reason);
  });

  process.on('uncaughtException', (error) => {
    logger.error('Uncaught Exception:', error);
    process.exit(1);
  });

  await app.listen(3000);
}
```

Reference: [Node.js Unhandled Rejections](https://nodejs.org/api/process.html#event-unhandledrejection)
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