npm package: @heritsilavo/mapper
Description: TypeScript object mapper library with fluent API
Author: Tsilavo Andriantsilavina
Latest version: 1.1.0

# 🗺️ @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

```bash
npm install @heritsilavo/mapper
```

## 🚀 Quick Start

```typescript
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

```typescript
// Auto-mapping (properties with same name)
mapper.createMap(Product, ProductDto);

const dto = mapper.map(product, ProductDto);
```

### Custom Transformations

```typescript
mapper.createMap(User, UserDto)
  .forMember('fullName', s => `${s.firstName} ${s.lastName}`)
  .forMember('displayAge', s => `${s.age} years old`);
```

### Array Mapping

```typescript
const users: User[] = [...];
const dtos = mapper.mapArray(users, UserDto);
```

### Reverse Mapping

```typescript
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

```typescript
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

```typescript
mapper.createCustomMap(User, UserDto, (source) => ({
  id: source.id,
  fullName: `${source.firstName} ${source.lastName}`,
  ageCategory: source.age >= 18 ? 'Adult' : 'Minor'
}));
```

### Disable Auto-mapping

```typescript
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