@ilhamtahir/ts-mapper


Core package for TypeScript object mapping with decorator support. Part of the NestJS Mapper ecosystem.

📦 Installation

``bash


npm

npm install @ilhamtahir/ts-mapper

yarn

yarn add @ilhamtahir/ts-mapper

pnpm

pnpm add @ilhamtahir/ts-mapper
`

🚀 Features

- Compile-time Safety: Fully TypeScript-based with type safety guarantees
- Minimal Intrusion: Decorator-driven approach with minimal impact on existing code
- Automatic Field Mapping: Auto-assignment for same-named fields with type checking
- Nested Path Support: Support for nested field mapping like profile.bio
- Abstract Class Support: Support for abstract classes and empty method body auto-mapping
- Proxy Auto Implementation: Empty method bodies automatically call transform

📖 Quick Start

$3

`typescript
// user.entity.ts
export class UserEntity {
id: number;
fullName: string;
age: number;
email: string;
profile: {
bio: string;
avatar: string;
};
}

// user.dto.ts
export class UserDto {
id: number;
name: string;
age: number;
email: string;
bio: string;
avatar: string;
}
`

$3

`typescript
// user.mapper.ts
import { Mapper, Mapping, transform } from '@ilhamtahir/ts-mapper';

@Mapper()
export class UserMapper {
@Mapping({ source: 'fullName', target: 'name' })
@Mapping({ source: 'profile.bio', target: 'bio' })
@Mapping({ source: 'profile.avatar', target: 'avatar' })
toDto(entity: UserEntity): UserDto {
return transform(this, 'toDto', entity, UserDto);
}
}
`

$3

`typescript
// app.ts
const userMapper = new UserMapper();

const entity = {
id: 1,
fullName: 'John Doe',
age: 30,
email: 'john@example.com',
profile: {
bio: 'Software Developer',
avatar: 'avatar.jpg',
},
};

const dto = userMapper.toDto(entity);
console.log(dto);
// Output:
// {
// id: 1,
// name: 'John Doe',
// age: 30,
// email: 'john@example.com',
// bio: 'Software Developer',
// avatar: 'avatar.jpg'
// }
`

🆕 Abstract Class + Proxy Support

$3

`typescript
// user-abstract.mapper.ts
import { Mapper, Mapping } from '@ilhamtahir/ts-mapper';

@Mapper()
export abstract class UserAbstractMapper {
/**
* Empty method body: system will automatically call transform
*/
@Mapping({ source: 'fullName', target: 'name' })
@Mapping({ source: 'profile.bio', target: 'bio' })
@Mapping({ source: 'profile.avatar', target: 'avatar' })
toDto(entity: UserEntity): UserDto {
// Empty method body, system will automatically call transform
return {} as UserDto;
}

/**
* Batch conversion
*/
toDtoList(entities: UserEntity[]): UserDto[] {
return entities.map(entity => this.toDto(entity));
}
}

// Usage
const userMapper = createMapperProxy(UserAbstractMapper);
const dto = userMapper.toDto(entity);
`

📚 API Documentation

$3

- @Mapper(): Mark class as mapper
- @Mapping({ source, target }): Explicit field mapping definition

$3

- transform(mapper, method, input, OutputType): Execute mapping transformation
- createMapperProxy(MapperClass): Create proxy object supporting auto-mapping

🔧 Troubleshooting

$3

`bash


Make sure you have the correct TypeScript version

npm install typescript@^4.7.0 --save-dev

Enable experimental decorators in tsconfig.json

{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
``

📋 Resources

- Full Documentation
- FAQ
- Performance Guide
- Contributing Guide
- Changelog

🤝 Related Packages

- @ilhamtahir/nest-mapper: NestJS integration for this package

📄 License

MIT License