@andrash/dto-utils

繁體中文

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

# Using npm
npm install @andrash/dto-utils

# Using yarn
yarn add @andrash/dto-utils

# Using pnpm
pnpm add @andrash/dto-utils

Features

toDto() Function

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:

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);
}

Custom Transformers

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:

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

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

Conditional Validation Helpers

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:

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;
}

PlainObject<T> Helper Type

The PlainObject<T> 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<T> helps you type these source objects correctly.

Usage Example:

// 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<string, ItemDto>;

  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<T> solves this by typing the plain object structure.
import { PlainObject } from "@andrash/dto-utils";

const dto: PlainObject<UserDto> = {
  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