class-validator

class-validator lets you attach validation rules directly to class properties using TypeScript decorators such as @IsEmail, @Length, and @Min, then validate instances with a single call. It ships more than a hundred built-in constraint decorators and, internally, delegates string checks to the battle-tested validator.js library.

Beyond simple property checks it supports nested-object validation, conditional rules, validation groups, custom decorators, whitelisting of unknown properties, and both asynchronous and synchronous validation. It works the same way in the browser and in Node.js, and integrates cleanly with frameworks like NestJS and dependency-injection containers.

What You Get

• 100+ ready-made constraint decorators covering strings, numbers, dates, arrays, sets, maps, and common formats (email, URL, UUID, phone, and more)
• Structured ValidationError results that report the target, property, offending value, and per-constraint messages, including nested children
• Advanced validation features: nested objects, validation groups, conditional validation, whitelisting, and custom validators and decorators
• Both async (validate/validateOrReject) and sync (validateSync) APIs that run identically in Node.js and the browser

Common Use Cases

• Validating incoming request DTOs in a NestJS or Express API before they reach business logic
• Enforcing shape and format on user-submitted form data on the client side
• Guarding configuration or message payloads against malformed values in shared browser/Node code

Under The Hood

Architecture

The public surface in src/index.ts exposes thin validate/validateOrReject/validateSync helpers that instantiate a Validator and delegate to a ValidationExecutor (src/validation/ValidationExecutor.ts). Decorators register constraint metadata into a global MetadataStorage (src/metadata/MetadataStorage.ts) at class-definition time; at validation time the executor reads that metadata, resolves each constraint through an IoC container (src/container.ts, overridable via useContainer for DI frameworks), runs the constraints, collects async work into an awaitingPromises list, and builds nested ValidationError trees. This metadata-plus-executor split cleanly separates declaration from execution.

Tech Stack

Written almost entirely in TypeScript (99.8% of the source). Runtime dependencies are minimal: validator.js for the underlying string checks and libphonenumber-js for phone validation. It builds to CommonJS, ESM5, ES2015, and UMD bundles via tsc and Rollup, so it consumes cleanly in bundlers and Node alike. reflect-metadata is used for decorator metadata.

Code Quality

The repo has a substantial test suite: 15 spec files including a large functional test directory (validation-functions-and-decorators, whitelist-validation, custom-decorators, promise-validation, inherited-validation, sync-validation) run under Jest with coverage. Code is consistently typed, ESLint- and Prettier-enforced, and organized by decorator family under src/decorator/. Nine runnable samples document real usage patterns.

API Design The developer experience is a core strength: decorators read almost like documentation on the property they guard, getting started needs only an import and an annotation, and the 100+ decorators follow a consistent Is*/@Min/@Max naming scheme. The README is extensive, covering options, custom decorators, groups, and framework integration, making the learning curve gentle for the common cases.