🗺️ @heritsilavo/Mapper

TypeScript object mapper library with fluent API, inspired by AutoMapper (.NET) and MapStruct (Java).

✨ Features

• 🎯 Fluent API - Chain configurations with .forMember()
• 🔄 Auto-mapping - Automatically maps properties with identical names
• 🎨 Custom transformations - Define complex mapping rules
• 📦 Reverse mapping - Create bidirectional mappings with .reverseMap()
• 🧩 Mapping profiles - Organize mappings by domain
• 🚀 Type-safe - Full TypeScript support with generics
• 📝 Array mapping - Map collections with .mapArray()

📦 Installation

npm install @heritsilavo/mapper

🚀 Quick Start

import { Mapper } from '@heritsilavo/mapper';

// Define your classes
class User {
  id!: number;
  firstName!: string;
  lastName!: string;
  age!: number;
}

class UserDto {
  id!: number;
  fullName!: string;
  ageCategory!: string;
}

// Create mapper instance
const mapper = new Mapper();

// Configure mapping
mapper.createMap(User, UserDto)
  .forMember('fullName', s => `${s.firstName} ${s.lastName}`)
  .forMember('ageCategory', s => s.age >= 18 ? 'Adult' : 'Minor');

// Use the mapper
const user = Object.assign(new User(), {
  id: 1,
  firstName: 'Heritsilavo',
  lastName: 'Andriantsilavina',
  age: 22
});

const dto = mapper.map(user, UserDto);
console.log(dto);
// Output: { id: 1, fullName: 'Heritsilavo Andriantsilavina', ageCategory: 'Adult' }

📚 Documentation

Basic Mapping

// Auto-mapping (properties with same name)
mapper.createMap(Product, ProductDto);

const dto = mapper.map(product, ProductDto);

Custom Transformations

mapper.createMap(User, UserDto)
  .forMember('fullName', s => `${s.firstName} ${s.lastName}`)
  .forMember('displayAge', s => `${s.age} years old`);

Array Mapping

const users: User[] = [...];
const dtos = mapper.mapArray(users, UserDto);

Reverse Mapping

mapper.createMap(User, UserDto)
  .forMember('fullName', s => `${s.firstName} ${s.lastName}`)
  .reverseMap()
  .forMember('firstName', s => s.fullName.split(' ')[0])
  .forMember('lastName', s => s.fullName.split(' ')[1]);

Mapping Profiles

import { MappingProfile } from '@heritsilavo/mapper';

class UserMappingProfile extends MappingProfile {
  configure(mapper: Mapper): void {
    mapper.createMap(User, UserDto)
      .forMember('fullName', s => `${s.firstName} ${s.lastName}`);
    
    mapper.createMap(User, UserSummaryDto)
      .forMember('name', s => s.firstName);
  }
}

mapper.addProfile(new UserMappingProfile());

Custom Mapper

mapper.createCustomMap(User, UserDto, (source) => ({
  id: source.id,
  fullName: `${source.firstName} ${source.lastName}`,
  ageCategory: source.age >= 18 ? 'Adult' : 'Minor'
}));

Disable Auto-mapping

mapper.createMap(User, UserDto)
  .disableAutoMap()
  .forMember('id', s => s.id)
  .forMember('fullName', s => `${s.firstName} ${s.lastName}`);

🔧 API Reference

Mapper

| Method | Description | |--------|-------------| | createMap(Source, Destination) | Create a mapping configuration | | .forMember(key, transform) | Define custom transformation | | .reverseMap() | Create reverse mapping | | .map(source, Destination) | Map single object | | .mapArray(sources, Destination) | Map array of objects | | .addProfile(profile) | Add mapping profile | | .createCustomMap(Source, Destination, fn) | Create fully custom mapper | | .clear() | Clear all configurations |

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Heritsilavo Andriantsilavina

Made with ❤️ by Heritsilavo