繁體中文

DTO Utilities

This package provides a set of utilities to enhance the creation, transformation, and validation of Data Transfer Objects (DTOs) in TypeScript applications, especially when using class-transformer and class-validator.

Installation

``bash


Using npm

npm install @andrash/dto-utils

Using yarn

yarn add @andrash/dto-utils

Using pnpm

pnpm add @andrash/dto-utils
`

Features

$3

The toDto() function transforms a plain JavaScript object into a DTO class instance and validates it in a single step. It uses class-transformer's plainToInstance() for transformation and class-validator's validateSync() for validation, throwing a formatted error message on failure.

Usage Example:

`ts
import { toDto } from "@andrash/dto-utils";
import { UserDto } from "./dtos/user.dto";

try {
const userDto = toDto(
UserDto,
plainObject,
{ excludeExtraneousValues: true }, // class-transformer options
true // enable validation
);
// Use the validated userDto instance
} catch (error) {
console.error("Validation failed:", error.message);
}
`

$3

A collection of pre-built functions for class-transformer's @Transform() decorator. For example, stringToArray() can convert a comma-separated string into an array of strings or numbers.

Usage Example:

`ts
import { Transform } from "class-transformer";
import { stringToArray } from "@andrash/dto-utils";

class ExampleDto {
@Expose()
@Transform(stringToArray({ elementType: "number" }))
numbers: number[];
}
`

$3

Provides helper functions like isNotNull() and isNotUndefined() for class-validator's @ValidateIf() decorator. These are useful for scenarios where @IsOptional() (which skips validation for both null and undefined) is too broad. For instance, you can require validation for undefined values but skip it for null values.

Usage Example:

`ts
import { ValidateIf, IsString } from "class-validator";
import { isNotNull } from "@andrash/dto-utils";

class ExampleDto {
@Expose()
@ValidateIf(isNotNull) // Validates only if the value is not null
@IsString()
optionalString: string;
}
`

$3

The PlainObject type represents the plain JavaScript object structure of a DTO class T. This is useful when creating object literals for DTOs that have methods or use complex types like Map, which are not directly assignable to the class type.

class-transformer often requires plain objects for transformation, especially for nested objects that will be converted into Map instances. PlainObject helps you type these source objects correctly.

Usage Example:

`ts
// DTO classes
class ItemDto {
@Expose()
@IsNumber()
itemId: number;

@Expose()
@IsNumber()
quantity: number;
}

class UserDto {
@Expose()
@IsNumber()
id: number;

@Expose()
@IsString()
name: string;

@Expose()
@Type(() => ItemDto)
@ValidateNested({ each: true })
inventory: Map;

getItemCount(): number {
return this.inventory.size;
}
}

// This would cause a TypeScript error because the literal object
// doesn't match the UserDto class structure (e.g., methods, Map type).
const dto: UserDto = {
/ ... /
};

// Using PlainObject solves this by typing the plain object structure.
import { PlainObject } from "@andrash/dto-utils";

const dto: PlainObject = {
id: 1,
name: "John Doe",
inventory: {
banana: { itemId: 101, quantity: 10 },
apple: { itemId: 102, quantity: 5 },
},
}; // No error
``

Explore More

This package includes many other utilities. Explore the source code and inline documentation to discover all available features.

Happy DTO-ing!

---

Developed by Andrash
2025.11