Nest Automapper

A wrapper around automapper-nartc to be used with NestJS as a Module.

Documentations

This module is a wrapper around @nartc/automapper so all usage documentations should be referenced at the link below.

Github Pages https://nartc.github.io/mapper/ Github Repo https://github.com/nartc/mapper

Setup

npm i -s nest-automapper

Note 1: Please make sure that you've read @nartc/automapper documentations to familiarize yourself with AutoMapper's terminology and how to setup your Profile and such.

1. Import AutomapperModule in AppModule and call .forRoot() method.

@Module({
  imports: [AutomapperModule.forRoot()]
})
export class AppModule {}

AutomapperModule.forRoot() method expects an AutomapperModuleRootOptions. When you call AutomapperModule.forRoot(), a new instance of AutoMapper will be created with the name option. There are two properties on the options that you can pass in:

• name: Name of this AutoMapper instance. Default to "default".
• config: A configuration function that will get called automatically.

Both options are optional. If you pass in config and configure your AutoMapper there, that is totally fine, but the following approach is recommended. Refer to @nartc/automapper: usage

2. AutoMapper has a concept of Profile. A Profile is a class that will house some specific mappings related to a specific domain model. Eg: User mappings will be housed by UserProfile. Refer to @nartc/automapper: usage for more information regarding Profile.

NestJS recommends you to separate features/domains in your application into Modules, in each module you would import/declare other modules/parts that are related to that Module. AutomapperModule also has a static method forFeature which should be used in such a feature module. forFeature accepts an AutomapperModuleFeatureOptions which has:

• profiles: An array of Profiles related to this module, and this will be added to an AutoMapper instance.
• name: Decide which AutoMapper instance to add these profiles to. Default to "default"

@Module({
  imports: [AutomapperModule.forFeature({profiles: [new UserProfile()]})]
})
export class UserModule {}

Exceptions:

• AutomapperModule will throw an Exception if forFeature receives an empty option
• AutomapperModule will throw an Exception if forFeature is called before any forRoot() calls.

3. Inject an instance of AutoMapper in your Service:

export class UserService {
  constructor(@InjectMapper() private readonly _mapper: AutoMapper) {}
}

Note: AutoMapper is imported from @nartc/automapper. InjectMapper decorator is imported from nest-automapper.

InjectMapper() accepts an optional argument name which will tell the decorator to inject the right instance of AutoMapper. Default to "default".

3. Use AutoMapper on your domain models:

...
const result = await newUser.save();
return this._mapper.map(result.toJSON(), UserVm);
...

Caveats

Due to reflection capabilities that TypeScript has, there are some caveats/opinionated problems about using this wrapper (ultimately, @nartc/automapper).

1. @nartc/automapper only works with Classes. Interfaces won't work because Interfaces will lose its context after transpiled.
2. Please follow @nartc/automapper example to understand how to setup your models.