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

1npm 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:

1import { AutoMapperModule } from 'devhub-nestjs-automapper';
2
3@Module({
4  imports: [AutoMapperModule],
5  // ...
6})
7export 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:

1import { AutoMap } from 'devhub-nestjs-automapper';
2
3// Option 1: Configure mapping on the DTO (target) class
4@AutoMap({
5  target: UserEntity,
6  properties: {
7    fullName: 'name',  // maps UserEntity.name to UserDto.fullName
8  }
9})
10class UserDto {
11  id: number;
12  fullName: string;
13  email: string;
14}
15
16// Option 2: Configure mapping on the Entity (source) class
17@AutoMap({
18  target: UserDto,
19  properties: {
20    name: 'fullName',  // maps UserEntity.name to UserDto.fullName
21  },
22  ignore: ['password'], // fields to exclude from mapping
23  convert: {
24    email: (value: string) => value.toLowerCase(), // transform values during mapping
25  },
26})
27class UserEntity {
28  id: number;
29  name: string;
30  email: string;
31  password: string;
32}

3. Use the mapper service in your application:

1import { MapperService } from 'devhub-nestjs-automapper';
2
3@Injectable()
4export class UserService {
5  constructor(private readonly mapperService: MapperService) {}
6
7  async getUser(id: number): Promise<UserDto> {
8    const userEntity = await this.findUser(id);
9    return this.mapperService.map(userEntity, UserDto);
10  }
11
12  async getUsers(): Promise<UserDto[]> {
13    const userEntities = await this.findUsers();
14    return this.mapperService.mapArray(userEntities, UserDto);
15  }
16}

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:

1// On the source class
2@AutoMap({ target: UserDto })
3class UserEntity { ... }
4
5// OR on the target class
6@AutoMap({ target: UserEntity })
7class UserDto { ... }

License

MIT