@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.
• 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. The Property function will simply handle the @ApiProperty and class-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 or classToPlain methods from class-transformer. You can pass additional transformer options via the Property decorator.

• Swagger API Documentation: The @ApiProperty decorator from Swagger is automatically applied when using Property, 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 by class-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 to false.
• 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, the enum 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:

1. Reduced Boilerplate: The Property utility reduces the need for repetitive decorators (such as @ApiProperty() on every field) by consolidating validation, transformation, and API documentation.
2. Centralized Configuration: Manage validation, transformation, and API documentation for a property in one place, making DTOs easier to read and maintain.
3. 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.