@aging/property v5.0.0
property
Function: Property
This library provides a powerful and convenient utility function called Property
, which wraps functionality from popular libraries such as class-validator
, class-transformer
, and swagger
's ApiProperty
decorator. The goal of this utility is to streamline the configuration of Data Transfer Object (DTO) properties by combining validation, transformation, and API documentation into a single, easy-to-use decorator.
Features:
- Simplified Property Configuration: By using the
Property
utility, you can configure class properties with validation, transformation, and API documentation in one step. - Integration with Popular Libraries:
- class-validator: Supports declarative validation of DTO fields using well-known validators (e.g.,
IsString()
,IsInt()
, etc.). - class-transformer: Allows automatic transformation of class properties (e.g., plain-to-class, class-to-plain transformations).
- Swagger
@ApiProperty
Decorator: Automatically generates API documentation for properties, reducing the need for repetitive Swagger decorators.
- class-validator: Supports declarative validation of DTO fields using well-known validators (e.g.,
- Customizability: Supports passing options to configure each library's functionality, offering flexibility while maintaining convenience.
Usage:
import { Property } from '@agng/property';
class CreateUserDto {
@Property({ type: 'string', required: true })
name: string;
@Property({ type: 'number', description: 'User age' })
age: number;
}
How It Works:
- class-validator Integration: Any validation decorators provided by
class-validator
(such as@IsString()
,@IsInt()
, etc.) can be applied as usual. TheProperty
function will simply handle the@ApiProperty
andclass-transformer
configurations, letting you focus on validation logic. class-transformer Integration: This utility automatically supports transformation of properties when DTOs are passed through the
plainToClass
orclassToPlain
methods fromclass-transformer
. You can pass additional transformer options via theProperty
decorator.Swagger API Documentation: The
@ApiProperty
decorator from Swagger is automatically applied when usingProperty
, allowing for consistent and clear API documentation without the need for separate@ApiProperty()
annotations.
Parameters:
The Property
utility accepts an object that combines the following options:
type
(required): Specifies the type of the property (e.g., "string", "number", "boolean", "date", "object"). Used byclass-transformer
and Swagger to correctly transform and document the property.required
(optional): Indicates whether the property is required or optional in the Swagger documentation. Defaults tofalse
.description
(optional): A description of the property for Swagger documentation.default
(optional): A default value for the property in both validation and Swagger documentation.enum
(optional): If the property is an enum, theenum
option can be passed to specify the enum values for Swagger.example
(optional): Provides an example value for Swagger documentation.isArray
(optional): Indicated whether the proeprty is an array or not.
Example:
import { Property } from '@aging/property';
export class UserDto {
@Property({ type: String, description: 'Unique identifier for the user', example: '123e4567-e89b-12d3-a456-426614174000' })
id: string;
@Property({ type: String, required: true, description: 'User email address' })
email: string;
@Property({ type: String, description: 'User first name', example: 'John', default: 'Anonymous' })
firstName: string;
@Property({ type: String, description: 'User last name', required: false })
lastName?: string;
}
Benefits:
- Reduced Boilerplate: The
Property
utility reduces the need for repetitive decorators (such as@ApiProperty()
on every field) by consolidating validation, transformation, and API documentation. - Centralized Configuration: Manage validation, transformation, and API documentation for a property in one place, making DTOs easier to read and maintain.
- Consistency: Ensures that both validation rules and API documentation are kept consistent across the application, minimizing the chance of errors.
Conclusion:
The Property
utility provides a clean, efficient, and powerful way to manage DTO properties in TypeScript applications. By combining validation, transformation, and API documentation, it simplifies the development process and promotes consistency across your application. Use the Property
utility to streamline your DTO creation and maintainability while ensuring robust validation and comprehensive API documentation.