Pipes & Validation

import {
  Controller,
  DefaultValuePipe,
  Get,
  HttpStatus,
  Param,
  ParseArrayPipe,
  ParseBoolPipe,
  ParseDatePipe,
  ParseEnumPipe,
  ParseFloatPipe,
  ParseIntPipe,
  ParseUUIDPipe,
  Query,
} from '@nestjs/common';

export enum BookFormat {
  Hardcover = 'hardcover',
  Paperback = 'paperback',
  Ebook = 'ebook',
}

@Controller('parse')
export class ParseController {
  // Class reference: Nest instantiates the pipe (DI works).
  @Get('int/:id')
  int(@Param('id', ParseIntPipe) id: number) {
    return { id, type: typeof id };
  }

  // Instance: lets you pass options.
  @Get('int-406/:id')
  int406(
    @Param(
      'id',
      new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE }),
    )
    id: number,
  ) {
    return { id };
  }

  @Get('float/:price')
  float(@Param('price', ParseFloatPipe) price: number) {
    return { price };
  }

  @Get('uuid/:id')
  uuid(@Param('id', new ParseUUIDPipe({ version: '4' })) id: string) {
    return { id };
  }

  @Get('format/:format')
  format(@Param('format', new ParseEnumPipe(BookFormat)) format: BookFormat) {
    return { format };
  }

  @Get('date')
  date(@Query('since', new ParseDatePipe({ optional: true })) since?: Date) {
    return { since: since?.toISOString() ?? null };
  }

  @Get('list')
  list(
    @Query('activeOnly', new DefaultValuePipe(false), ParseBoolPipe)
    activeOnly: boolean,
    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
  ) {
    return { activeOnly, page };
  }

  @Get('ids')
  ids(
    @Query('ids', new ParseArrayPipe({ items: Number, separator: ',' }))
    ids: number[],
  ) {
    return { ids };
  }
}

curl -i localhost:3000/parse/int/42
curl -i localhost:3000/parse/int/abc
curl -i localhost:3000/parse/int-406/abc
curl -i localhost:3000/parse/uuid/123
curl -i 'localhost:3000/parse/ids?ids=1,x'

// 200
{ "id": 42, "type": "number" }

// 400
{ "message": "Validation failed (numeric string is expected)", "error": "Bad Request", "statusCode": 400 }

// 406 (errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE)
{ "message": "Validation failed (numeric string is expected)", "error": "Not Acceptable", "statusCode": 406 }

// 400 (uuid with version: '4')
{ "message": "Validation failed (uuid v 4 is expected)", "error": "Bad Request", "statusCode": 400 }

// 400 (ParseArrayPipe, second item)
{ "message": "[1] item must be a number", "error": "Bad Request", "statusCode": 400 }

@Post('bulk')
createBulk(
  @Body(new ParseArrayPipe({ items: CreateBookDto, whitelist: true }))
  dtos: CreateBookDto[],
) {
  return { count: dtos.length };
}

import type {} from 'multer'; // loads the Express.Multer.File typings
import {
  Controller,
  FileTypeValidator,
  HttpStatus,
  MaxFileSizeValidator,
  ParseFilePipe,
  ParseFilePipeBuilder,
  Post,
  UploadedFile,
  UseInterceptors,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';

@Controller('covers')
export class UploadController {
  @Post()
  @UseInterceptors(FileInterceptor('cover'))
  upload(
    @UploadedFile(
      new ParseFilePipe({
        validators: [
          new MaxFileSizeValidator({ maxSize: 1024 }),
          new FileTypeValidator({ fileType: 'image/png' }),
        ],
      }),
    )
    cover: Express.Multer.File,
  ) {
    return { name: cover.originalname, size: cover.size };
  }

  @Post('builder')
  @UseInterceptors(FileInterceptor('cover'))
  uploadWithBuilder(
    @UploadedFile(
      new ParseFilePipeBuilder()
        .addMaxSizeValidator({ maxSize: 1024 })
        .build({
          errorHttpStatusCode: HttpStatus.UNPROCESSABLE_ENTITY,
          fileIsRequired: false,
        }),
    )
    cover?: Express.Multer.File,
  ) {
    return { uploaded: cover !== undefined };
  }
}

// POST /covers with no file: 400
{ "message": "File is required", "error": "Bad Request", "statusCode": 400 }

// POST /covers with a text/plain file: 400
{ "message": "Validation failed (current file type is text/plain, expected type is image/png)", "error": "Bad Request", "statusCode": 400 }

// POST /covers with a 2048-byte file: 400
{ "message": "Validation failed (current file size is 2048, expected size is less than 1024)", "error": "Bad Request", "statusCode": 400 }

// POST /covers/builder with a 2048-byte file: 422 (errorHttpStatusCode)
{ "message": "Validation failed (current file size is 2048, expected size is less than 1024)", "error": "Unprocessable Entity", "statusCode": 422 }

// POST /covers/builder with no file: 201 (fileIsRequired: false)
{ "uploaded": false }

import { Module, ValidationPipe } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useFactory: () => new ValidationPipe({ whitelist: true, transform: true }),
    },
  ],
})
export class AppModule {}

export interface ArgumentMetadata<Metatype = any> {
  type: 'body' | 'query' | 'param' | 'custom';
  metatype?: Type<Metatype> | undefined;
  data?: string | undefined;
  schema?: StandardSchemaV1;
}

import {
  ArgumentMetadata,
  BadRequestException,
  Injectable,
  NotFoundException,
  PipeTransform,
} from '@nestjs/common';
import { Book, BooksRepository } from './books.repository.js';

// Transformation: trims every string it receives. Generic over input/output.
@Injectable()
export class TrimPipe implements PipeTransform<string, string> {
  transform(value: string, metadata: ArgumentMetadata): string {
    if (typeof value !== 'string') {
      throw new BadRequestException(
        `${metadata.type} "${metadata.data ?? ''}" must be a string`,
      );
    }
    return value.trim();
  }
}

// Transformation with DI: resolves an id into an entity.
@Injectable()
export class BookByIdPipe implements PipeTransform<string, Book> {
  constructor(private readonly books: BooksRepository) {}

  transform(value: string): Book {
    const id = Number.parseInt(value, 10);
    if (Number.isNaN(id)) {
      throw new BadRequestException('id must be an integer');
    }
    const book = this.books.findOne(id);
    if (!book) {
      throw new NotFoundException(`Book ${id} not found`);
    }
    return book;
  }
}

// Reading ArgumentMetadata: report what Nest tells the pipe about the parameter.
@Injectable()
export class DescribeMetadataPipe implements PipeTransform {
  transform(value: unknown, metadata: ArgumentMetadata) {
    return {
      value,
      type: metadata.type,
      data: metadata.data ?? null,
      metatype: metadata.metatype?.name ?? null,
    };
  }
}

@Get('by-id/:id')
byId(@Param('id', BookByIdPipe) book: Book) {
  return book;
}

@Get('slug/:slug')
slug(@Param('slug', TrimPipe) slug: string) {
  return { slug };
}

@Get('meta')
meta(@Query('q', DescribeMetadataPipe) q: unknown) {
  return q;
}

curl localhost:3000/books/by-id/1
curl localhost:3000/books/by-id/9
curl 'localhost:3000/books/slug/%20dune%20'
curl 'localhost:3000/tools/meta?q=hi'

{ "id": 1, "title": "Dune", "isbn": "9780441172719" }
{ "message": "Book 9 not found", "error": "Not Found", "statusCode": 404 }
{ "slug": "dune" }
{ "value": "hi", "type": "query", "data": "q", "metatype": "Object" }

import {
  ArgumentMetadata,
  BadRequestException,
  PipeTransform,
} from '@nestjs/common';
import type { ZodType } from 'zod';

// A hand-written, schema-based pipe: the pattern the built-in
// StandardSchemaValidationPipe generalises.
export class ZodValidationPipe implements PipeTransform {
  constructor(private readonly schema: ZodType) {}

  transform(value: unknown, _metadata: ArgumentMetadata): unknown {
    const result = this.schema.safeParse(value);
    if (!result.success) {
      throw new BadRequestException({
        message: 'Validation failed',
        issues: result.error.issues.map((i) => ({
          path: i.path.join('.'),
          message: i.message,
        })),
      });
    }
    return result.data;
  }
}

{
  "message": "Validation failed",
  "issues": [
    { "path": "bookId", "message": "Invalid input: expected number, received NaN" },
    { "path": "rating", "message": "Too big: expected number to be <=5" }
  ]
}

import { Type } from 'class-transformer';
import {
  ArrayMinSize,
  IsInt,
  IsISBN,
  IsOptional,
  IsString,
  Length,
  Max,
  Min,
  ValidateNested,
} from 'class-validator';

export class AuthorDto {
  @IsString()
  @Length(1, 80)
  name!: string;

  @IsOptional()
  @IsInt()
  @Min(1000)
  @Max(2100)
  birthYear?: number;
}

export class CreateBookDto {
  @IsString()
  @Length(1, 120)
  title!: string;

  @IsISBN()
  isbn!: string;

  @IsInt()
  @Min(1)
  pages!: number;

  @ValidateNested({ each: true })
  @Type(() => AuthorDto)
  @ArrayMinSize(1)
  authors!: AuthorDto[];
}

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

curl -i -X POST localhost:3000/books -H 'content-type: application/json' \
  -d '{"title":"","isbn":"x","pages":"a","authors":[{"name":5,"birthYear":5}]}'

{
  "message": [
    "title must be longer than or equal to 1 characters",
    "isbn must be an ISBN",
    "pages must not be less than 1",
    "pages must be an integer number",
    "authors.0.name must be longer than or equal to 1 and shorter than or equal to 80 characters",
    "authors.0.name must be a string",
    "authors.0.birthYear must not be less than 1000"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
// or, rejecting instead of stripping:
app.useGlobalPipes(
  new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }),
);

// whitelist: true, body { ..., "admin": true, "authors": [{ "name": "F", "evil": 1 }] }
{ "created": { "title": "Dune", "isbn": "9780441172719", "pages": 412, "authors": [{ "name": "F" }] }, "isInstance": false }

// whitelist + forbidNonWhitelisted, body { ..., "admin": true }
{ "message": ["property admin should not exist"], "error": "Bad Request", "statusCode": 400 }

import { Type } from 'class-transformer';
import { IsInt, IsOptional, Max, Min } from 'class-validator';

export class PageQueryDto {
  // Without @Type(), query strings stay strings unless implicit conversion is on.
  @Type(() => Number)
  @IsInt()
  @Min(1)
  page: number = 1;

  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(100)
  @IsOptional()
  limit?: number;
}

app.useGlobalPipes(new ValidationPipe({ transform: true }));

// Alternative to per-property @Type(): convert by declared type everywhere.
app.useGlobalPipes(
  new ValidationPipe({
    transform: true,
    transformOptions: { enableImplicitConversion: true },
  }),
);

app.useGlobalPipes(new ValidationPipe({ errorFormat: 'grouped' }));

{
  "message": {
    "title": ["title must be longer than or equal to 1 characters"],
    "isbn": ["isbn must be an ISBN"],
    "pages": ["pages must not be less than 1", "pages must be an integer number"],
    "authors.0.name": [
      "name must be longer than or equal to 1 and shorter than or equal to 80 characters",
      "name must be a string"
    ]
  },
  "error": "Bad Request",
  "statusCode": 400
}

// Hide details in production.
app.useGlobalPipes(new ValidationPipe({ disableErrorMessages: true }));

// 422 instead of 400, and one message per property.
app.useGlobalPipes(
  new ValidationPipe({ errorHttpStatusCode: 422, stopAtFirstError: true }),
);

import {
  UnprocessableEntityException,
  ValidationPipe,
} from '@nestjs/common';
import type { ValidationError } from 'class-validator';

export const unprocessable = new ValidationPipe({
  exceptionFactory: (errors: ValidationError[]) =>
    new UnprocessableEntityException({
      message: 'Validation failed',
      fields: errors.map((e) => ({
        field: e.property,
        problems: Object.values(e.constraints ?? {}),
      })),
    }),
});

export class AccountDto {
  @IsString({ groups: ['create'] })
  @IsOptional({ groups: ['update'] })
  name?: string;
}

@Post('create-group')
@UsePipes(new ValidationPipe({ groups: ['create'] }))
createGroup(@Body() dto: AccountDto) { return dto; }

@Post('update-group')
@UsePipes(new ValidationPipe({ groups: ['update'] }))
updateGroup(@Body() dto: AccountDto) { return dto; }

import { Injectable } from '@nestjs/common';
import {
  registerDecorator,
  ValidationArguments,
  ValidationOptions,
  ValidatorConstraint,
  ValidatorConstraintInterface,
} from 'class-validator';
import { BooksRepository } from './books.repository.js';

@ValidatorConstraint({ name: 'isbnAvailable', async: true })
@Injectable()
export class IsbnAvailableConstraint implements ValidatorConstraintInterface {
  constructor(private readonly books: BooksRepository) {}

  async validate(isbn: string): Promise<boolean> {
    return !(await this.books.existsByIsbn(isbn));
  }

  defaultMessage(args: ValidationArguments): string {
    return `${args.property} ${args.value} is already registered`;
  }
}

export function IsbnAvailable(options?: ValidationOptions): PropertyDecorator {
  return (object: object, propertyName: string | symbol) => {
    registerDecorator({
      target: object.constructor,
      propertyName: propertyName as string,
      options,
      constraints: [],
      validator: IsbnAvailableConstraint,
    });
  };
}

import { IsString } from 'class-validator';
import { useContainer } from 'class-validator';

export class RegisterIsbnDto {
  @IsString()
  @IsbnAvailable({ message: 'isbn is already taken' })
  isbn!: string;
}

// main.ts, before app.listen():
useContainer(app.select(AppModule), { fallbackOnErrors: true });

import {
  IntersectionType,
  OmitType,
  PartialType,
  PickType,
} from '@nestjs/mapped-types';

// All properties optional, validation rules kept.
export class UpdateBookDto extends PartialType(CreateBookDto) {}
// Only isbn.
export class BookIdentityDto extends PickType(CreateBookDto, ['isbn'] as const) {}
// Everything except authors.
export class BookWithoutAuthorsDto extends OmitType(CreateBookDto, [
  'authors',
] as const) {}

export class AuditInfo {
  @IsString()
  requestedBy!: string;
}
// Union of the properties of two classes.
export class CreateBookAuditedDto extends IntersectionType(
  CreateBookDto,
  AuditInfo,
) {}

import { z } from 'zod';

export const createReviewSchema = z.object({
  bookId: z.coerce.number().int().positive(),
  rating: z.number().int().min(1).max(5),
  comment: z.string().trim().max(500).optional(),
});
export type CreateReviewDto = z.infer<typeof createReviewSchema>;

export const listReviewsQuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  search: z.string().trim().optional(),
});
export type ListReviewsQuery = z.infer<typeof listReviewsQuerySchema>;

export const updateReviewSchema = createReviewSchema.partial();
export const strictReviewSchema = z.strictObject({
  rating: z.number().int().min(1).max(5),
});

import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
import { z } from 'zod';
import {
  createReviewSchema,
  listReviewsQuerySchema,
  strictReviewSchema,
  updateReviewSchema,
  type CreateReviewDto,
  type ListReviewsQuery,
} from './schemas.js';

@Controller('reviews')
export class ReviewsController {
  @Post()
  create(@Body({ schema: createReviewSchema }) dto: CreateReviewDto) {
    return dto;
  }

  @Post('strict')
  strict(@Body({ schema: strictReviewSchema }) dto: { rating: number }) {
    return dto;
  }

  @Post('partial')
  partial(@Body({ schema: updateReviewSchema }) dto: Partial<CreateReviewDto>) {
    return dto;
  }

  @Post('bulk')
  bulk(@Body({ schema: z.array(createReviewSchema) }) dtos: CreateReviewDto[]) {
    return { count: dtos.length };
  }

  @Post('email')
  email(@Body('email', { schema: z.email() }) email: string) {
    return { email };
  }

  @Get()
  list(@Query({ schema: listReviewsQuerySchema }) query: ListReviewsQuery) {
    return query;
  }

  @Get(':id')
  findOne(
    @Param('id', { schema: z.coerce.number().int().positive() }) id: number,
  ) {
    return { id, type: typeof id };
  }
}

import { StandardSchemaValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new StandardSchemaValidationPipe());
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

// POST /reviews { "bookId": "x", "rating": 9 }
{
  "message": [
    "bookId: Invalid input: expected number, received NaN",
    "rating: Too big: expected number to be <=5"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

// POST /reviews/bulk, second element invalid: the message is prefixed by its index
{ "message": ["1.rating: Too small: expected number to be >=1"], "error": "Bad Request", "statusCode": 400 }

// GET /reviews/-1
{ "message": ["Too small: expected number to be >0"], "error": "Bad Request", "statusCode": 400 }

export const updateUserSchema = createUserSchema.partial();           // PartialType()
export const changeEmailSchema = createUserSchema.pick({ email: true }); // PickType()
export const publicProfileSchema = createUserSchema.omit({ password: true }); // OmitType()
export const createAdminSchema = createUserSchema.extend({            // IntersectionType()
  role: z.enum(['admin', 'editor']),
});

import * as v from 'valibot';
import { type } from 'arktype';

const valibotSchema = v.object({
  email: v.pipe(v.string(), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});
const arkSchema = type({ email: 'string.email', password: 'string >= 8' });

@Post('valibot')
valibot(@Body({ schema: valibotSchema }) dto: v.InferOutput<typeof valibotSchema>) {
  return dto;
}

@Post('arktype')
arktype(@Body({ schema: arkSchema }) dto: typeof arkSchema.infer) {
  return dto;
}

// Valibot
{ "message": ["email: Invalid email: Received \"x\"", "password: Invalid length: Expected >=8 but received 5"], "error": "Bad Request", "statusCode": 400 }

// ArkType
{ "message": ["email: email must be an email address (was \"x\")", "password: password must be at least length 8 (was 5)"], "error": "Bad Request", "statusCode": 400 }

app.useGlobalPipes(
  new StandardSchemaValidationPipe({
    exceptionFactory: (issues) =>
      new UnprocessableEntityException({
        message: 'Validation failed',
        errors: issues.map((issue) => ({
          path: issue.path
            ?.map((segment) => (typeof segment === 'object' ? segment.key : segment))
            .join('.'),
          message: issue.message,
        })),
      }),
  }),
);

export const TenantId = createParamDecorator(
  (_data: unknown, ctx: ExecutionContext): string =>
    ctx.switchToHttp().getRequest().headers['x-tenant-id'],
);

@Get('tenant-schema')
tenantSchema(@TenantId({ schema: z.uuid() }) tenant: string) {
  return { tenant };
}

app.useGlobalPipes(
  new StandardSchemaValidationPipe({ validateCustomDecorators: true }),
);

app.useGlobalPipes(
  new ValidationPipe({ transform: true }),
  new StandardSchemaValidationPipe(),
);