class-validator
v0.15.1 MITDecorator-based property validation for classes.
class-validator Download Trends
About class-validator
Class-validator is a powerful npm package designed to simplify data validation within JavaScript and TypeScript applications, particularly those leveraging ES Decorators. It addresses the common challenge of ensuring data integrity and correctness at various points in an application's lifecycle, from API request handling to internal object state management. By abstracting the validation logic, it promotes cleaner, more maintainable code.
The core philosophy of class-validator revolves around declarative validation using decorators. This approach aligns well with modern TypeScript projects and allows developers to define validation rules directly on their class properties. This makes the validation rules co-located with the data structures they apply to, enhancing readability and reducing the cognitive load associated with managing separate validation schemas.
Key API patterns include the use of decorators like `@IsString()`, `@IsInt()`, `@MinLength()`, and `@MaxLength()` to annotate class properties. The package exposes a primary function, `validate()`, which takes an instance of a class decorated with these validation rules and returns an array of `ValidationError` objects if any rules are violated. It also supports custom validators and complex nested object validation, providing flexibility for diverse data structures.
Class-validator integrates seamlessly into many popular backend frameworks and workflows. It is commonly used within Node.js environments, especially with frameworks like NestJS, which has first-class support for this package. It can also be employed in standalone scripts or other frameworks where class-based data modeling is prevalent, fitting into build pipelines that process TypeScript code.
With a substantial weekly download count of 4.8 million and 11.7K GitHub stars, class-validator is a mature and widely adopted solution. Its unpacked size is 5.3 MB, with a gzipped bundle size of 105.8 kB, representing a moderate dependency. The package is actively maintained, as indicated by its last update on 2026-03-19, although the open issue count of 307 suggests ongoing development and community engagement.
While class-validator offers extensive validation capabilities, developers should be aware that its reliance on ES Decorators means it typically targets environments that support this feature, primarily TypeScript. For projects not using decorators or requiring extremely minimal dependencies, alternative validation strategies might be more suitable. The package's feature set is comprehensive, but mastering all its advanced customization options may require an investment in learning.
When to use
- When defining strict validation rules for API request payloads in TypeScript applications.
- When leveraging NestJS or other frameworks with built-in support for decorator-based validation.
- When ensuring data integrity for complex nested object structures using `@ValidateNested()`.
- When creating reusable validation logic via custom decorators derived from `@ValidatorConstraint()`.
- When validating enum values with the `@IsEnum()` decorator to enforce domain constraints.
- When generating dynamic validation rules based on runtime conditions or external configurations.
When NOT to use
- If your project exclusively uses plain JavaScript without decorators and you prefer a less opinionated validation approach.
- If you only require simple type checks and have minimal validation requirements, a lighter, non-decorator-based library might suffice.
- When running in a strict CommonJS environment that does not transpile or support ES Decorators effectively.
- If maximum performance is critical and the overhead of decorator processing is a measured concern, consider simpler validation methods.
- When dealing with extremely simple data structures where defining full classes and decorators introduces unnecessary complexity.