FileTypeValidator

Kind: Class

Source: packages/common/pipes/file/file-type.validator.ts

Part of: Common

Defines the built-in FileTypeValidator. It validates incoming files by examining their magic numbers using the file-type package, providing more reliable file type validation than just checking the mimetype string.

FileTypeValidator is a built-in file validation class used with NestJS file upload pipes. It inspects the uploaded file buffer for magic numbers via the file-type package, making validation more reliable than trusting the client-provided MIME type alone.

Extends: FileValidator

Methods

Where it refuses work

• FileTypeValidator stops the work with an early return when this.validationOptions.fallbackToMimetype, in 4 places.
• FileTypeValidator stops the work with an early return when errorMessage.
• FileTypeValidator stops the work with an early return when file?.mimetype && !file.buffer && !this.validationOptions?.fallbackToMimetype && !this.va….
• FileTypeValidator stops the work with an early return when !this.validationOptions.
• FileTypeValidator stops the work with an early return when this.validationOptions.skipMagicNumbersValidation.
• FileTypeValidator stops the work with an early return when !isFileValid.

When something fails

• FileTypeValidator handles failure in 2 places: it logs it and continues in 1, and turns it into a return value in 1.

Diagram

mermaid
graph LR
  A[Uploaded file] --> B[ParseFilePipe]
  B --> C[FileTypeValidator]
  C --> D[Inspect file buffer magic numbers]
  D --> E[file-type detects MIME type]
  E --> F{Matches configured fileType?}
  F -->|Yes| G[Accept file]
  F -->|No| H[Return validation error]

Usage

ts
import {
  Controller,
  HttpStatus,
  ParseFilePipe,
  Post,
  UploadedFile,
  UseInterceptors,
  FileTypeValidator,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';

@Controller('uploads')
export class UploadController {
  @Post('image')
  @UseInterceptors(FileInterceptor('file'))
  uploadImage(
    @UploadedFile(
      new ParseFilePipe({
        validators: [
          new FileTypeValidator({
            fileType: /image\/(jpeg|png)/,
          }),
        ],
        errorHttpStatusCode: HttpStatus.UNPROCESSABLE_ENTITY,
      }),
    )
    file: Express.Multer.File,
  ) {
    return {
      filename: file.originalname,
      detectedType: file.mimetype,
    };
  }
}

AI Coding Instructions

• Use FileTypeValidator inside ParseFilePipe validator lists for uploaded files handled by Multer interceptors.
• Configure fileType with either an exact MIME type string, such as image/jpeg, or a regular expression for multiple allowed types.
• Do not rely only on file.mimetype; this validator checks the file buffer contents and is intended to prevent spoofed MIME types.
• Ensure the upload adapter provides a buffer on the uploaded file, since magic-number detection requires access to file contents.
• Combine this validator with MaxFileSizeValidator when endpoints need both type and size restrictions.