devhub-nestjs-automapper

A lightweight, zero-dependency automapper for NestJS applications. This package provides a simple way to map between different object types in your NestJS applications.

Installation

npm install devhub-nestjs-automapper

Features

• Zero dependencies (other than NestJS core)
• TypeScript support
• Property mapping
• Property ignoring
• Custom value converters
• Array mapping support
• Flexible mapping configuration (can be defined on either source or target class)

Usage

1. Import the AutoMapperModule in your application module:

import { AutoMapperModule } from 'devhub-nestjs-automapper';

@Module({
  imports: [AutoMapperModule],
  // ...
})
export class AppModule {}

2. Define your source and target classes with mapping configuration. You can add the @AutoMap decorator to either the source or target class:

import { AutoMap } from 'devhub-nestjs-automapper';

// Option 1: Configure mapping on the DTO (target) class
@AutoMap({
  target: UserEntity,
  properties: {
    fullName: 'name',  // maps UserEntity.name to UserDto.fullName
  }
})
class UserDto {
  id: number;
  fullName: string;
  email: string;
}

// Option 2: Configure mapping on the Entity (source) class
@AutoMap({
  target: UserDto,
  properties: {
    name: 'fullName',  // maps UserEntity.name to UserDto.fullName
  },
  ignore: ['password'], // fields to exclude from mapping
  convert: {
    email: (value: string) => value.toLowerCase(), // transform values during mapping
  },
})
class UserEntity {
  id: number;
  name: string;
  email: string;
  password: string;
}

3. Use the mapper service in your application:

import { MapperService } from 'devhub-nestjs-automapper';

@Injectable()
export class UserService {
  constructor(private readonly mapperService: MapperService) {}

  async getUser(id: number): Promise<UserDto> {
    const userEntity = await this.findUser(id);
    return this.mapperService.map(userEntity, UserDto);
  }

  async getUsers(): Promise<UserDto[]> {
    const userEntities = await this.findUsers();
    return this.mapperService.mapArray(userEntities, UserDto);
  }
}

API Reference

Decorators

@AutoMap(options: MappingOptions)

Configuration options:

• target: The target class type (required)
• properties: (optional) Object mapping source properties to target properties
• ignore: (optional) Array of property names to ignore during mapping
• convert: (optional) Object containing conversion functions for specific properties

The @AutoMap decorator can be placed on either:

1. The source class (the object you're mapping from)
2. The target class (the object you're mapping to)

Services

MapperService

• map<T>(source: any, targetType: new () => T): T

  • Maps a single object to the target type
  • Throws detailed error messages if mapping configuration is missing or invalid

• mapArray<T>(sources: any[], targetType: new () => T): T[]

  • Maps an array of objects to the target type
  • Each object is mapped using the same configuration as map()

Common Issues

No mapping configuration found

If you see this error, make sure you have added the @AutoMap decorator to either:

1. The source class (the object you're mapping from), or
2. The target class (the object you're mapping to)

Example:

// On the source class
@AutoMap({ target: UserDto })
class UserEntity { ... }

// OR on the target class
@AutoMap({ target: UserEntity })
class UserDto { ... }

License

MIT