NestJS Documentation

NestJS is a framework for building efficient, scalable Node.js server-side applications. It is designed to solve the problem of architecture in Node.js applications by providing an out-of-the-box application architecture that is highly testable, scalable, loosely coupled, and easily maintainable.

Key characteristics:

• Language Support: Built with and fully supports TypeScript, but also enables development in pure JavaScript.
• Programming Paradigms: Combines elements of Object-Oriented Programming (OOP), Functional Programming (FP), and Functional Reactive Programming (FRP).
• Underlying Engines: Uses robust HTTP server frameworks like Express (default) or can be configured to use Fastify.
• Abstraction: Provides a high-level abstraction over Express/Fastify while still exposing their APIs directly for third-party module compatibility.
• Inspiration: The architecture is heavily inspired by Angular.

The NestJS Swagger CLI plugin is an opt-in tool that enhances the TypeScript compilation process to reduce boilerplate code for OpenAPI documentation. It automatically adds @ApiProperty decorators to DTOs and response decorators to endpoints by analyzing the Abstract Syntax Tree (AST).

Key capabilities:

• Automatically annotates DTO properties with @ApiProperty (unless @ApiHideProperty is used).
• Sets required status based on TypeScript optionality (e.g., name?: string becomes required: false).
• Infers type, enum, and default values from TypeScript types and assignments.
• Maps class-validator decorators to OpenAPI validation rules (if classValidatorShim is enabled).
• Adds response decorators to endpoints with appropriate status codes and types.
• Generates descriptions and example values from code comments (if introspectComments is enabled).

Important Requirements:

• File Suffixes: By default, the plugin only analyzes files ending in .dto.ts or .entity.ts. You can customize this via dtoFileNameSuffix.
• Runtime Validation: The plugin only generates documentation. You must still use class-validator decorators (like @IsEmail()) for actual runtime validation.
• Mapped Types: When using utilities like PartialType, import them from @nestjs/swagger instead of @nestjs/mapped-types to ensure the plugin picks up the schema.

export class CreateUserDto {
  email: string;
  password: string;
  roles: RoleEnum[] = [];
  isEnabled?: boolean = true;
}

A Guard is a class annotated with @Injectable() that implements the CanActivate interface. Its single responsibility is to determine whether a request will be handled by a route handler based on runtime conditions like permissions, roles, or ACLs (authorization).

Key differences from Middleware:

• Context Awareness: Unlike middleware, Guards have access to the ExecutionContext, meaning they know exactly which handler will be executed next.
• Execution Order: Guards are executed after all middleware, but before any interceptor or pipe.

Use Guards for authorization logic to keep your code declarative and DRY.

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}

Necord uses decorators to handle Discord events within NestJS providers:

• @Once(eventName): Triggers only the first time the specified event occurs (e.g., 'ready').
• @On(eventName): Triggers every time the specified event occurs (e.g., 'warn').
• @Context(): Injects the event context into the method. The context type can be explicitly typed using ContextOf<'eventName'> to ensure type safety for the arguments.
• @TargetUser() and @TargetMessage(): Used in context menu commands to inject the specific user or message being interacted with.

import { Injectable, Logger } from '@nestjs/common';
import { Context, On, Once, ContextOf } from 'necord';
import { Client } from 'discord.js';

@Injectable()
export class AppService {
  private readonly logger = new Logger(AppService.name);

  @Once('ready')
  public onReady(@Context() [client]: ContextOf<'ready'>) {
    this.logger.log(`Bot logged in as ${client.user.username}`);
  }

  @On('warn')
  public onWarn(@Context() [message]: ContextOf<'warn'>) {
    this.logger.warn(message);
  }
}