explaingit

typestack/class-validator

11,776TypeScriptAudience · developerComplexity · 2/5Setup · easy

TLDR

A TypeScript library that lets you attach validation rules as small decorators on class properties, then check any object against those rules with a single function call and receive a detailed error list.

Mindmap

mindmap
  root((class-validator))
    What it does
      Property validation
      Decorator rules
      Error reporting
    Validation types
      Email and URL
      String length
      Numeric ranges
      Custom validators
    Use cases
      API request checks
      Form input guards
    Audience
      Backend developers
      Node.js users
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Validate incoming API request bodies before trusting or saving them to a database

USE CASE 2

Add email, URL, or string-length checks to a form submission handler with a single decorator per field

USE CASE 3

Reject objects that contain unexpected extra properties using whitelist mode

USE CASE 4

Apply stricter validation rules during object creation than during updates by using validation groups

Tech stack

TypeScriptNode.js

Getting it running

Difficulty · easy Time to first run · 5min
License terms are not stated in the explanation.

In plain English

class-validator is a TypeScript library that lets you declare rules for what values are acceptable on the properties of a class, then automatically check whether a given object follows those rules. The typical use case is validating data that arrives at a server, like a form submission or API request body, before trusting it or saving it to a database. You attach small annotations called decorators directly to the properties of your class. For example, adding @IsEmail() to an email property means the library will confirm the value looks like a valid email address when you run validation. There are built-in decorators for common checks: minimum and maximum length for strings, numeric ranges, date formats, URL formats, whether a value is present at all, and many others. You can also write your own custom validators if the built-in ones do not cover your case. Running validation is one function call: validate(instance) returns a list of errors. Each error identifies which property failed, what value was provided, and which rule was violated. Error messages can be customized with static strings or with functions that receive the actual value and constraint details, so you can return different messages depending on what went wrong. The library supports more than flat objects. You can validate arrays of values, nested objects, maps, and sets. Validation can be grouped so that different rules apply in different contexts, such as stricter checks during creation versus updates. There is also a whitelisting mode that rejects any properties not explicitly declared in the class, which protects against unexpected extra data. class-validator works in both Node.js and browser environments and can be used with or without decorators depending on your setup. The full README is longer than what was shown.

Copy-paste prompts

Prompt 1
Using class-validator, write a UserDto class with decorators that enforce: email is a valid email address, username is 3 to 20 characters, and age is a number between 18 and 120.
Prompt 2
Show me how to return custom error messages from class-validator that include the actual bad value in the message string, using a function instead of a static string.
Prompt 3
Using class-validator, validate a nested object, a CreateOrderDto that contains a ShippingAddressDto, and surface validation errors from both levels in the result.
Prompt 4
Set up class-validator in whitelist mode so that any properties not explicitly declared on the class are automatically stripped and cause a validation failure.
Prompt 5
Write a custom class-validator decorator that checks whether a string is a valid UUID v4, and apply it to a property on a class.
Open on GitHub → Explain another repo

← typestack on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.