entity_mapper

Quick Start • Documentation • Example • API Docs • GitHub

Clean Architecture entity mapping made simple.

A lightweight code generator that creates type-safe Entity ↔ Model mapping methods using dart_mappable-style patterns. Perfect for Clean Architecture and Domain-Driven Design applications.

---

Features

• 🎯 Clean Architecture ready: Perfect separation between domain and data layers
• 🔄 dart_mappable Pattern: Familiar API and generated code
• ⚡ Zero runtime overhead: All mapping code generated at build time
• Fully type-safe: Generated code maintains complete type safety
• 🧪 Nullability & Collections: Handles nullable fields and nested lists automatically
• 🧩 Simple & focused: Just specify the entity type - that's it!

---

Quick Start

Requirements: Dart SDK ≥ 3.8.0, Flutter ≥ 3.32.0

Add dependencies:

dependencies:
  entity_mapper: ^latest
dev_dependencies:
  build_runner: ^latest

Or use:

flutter pub add entity_mapper
flutter pub add build_runner --dev

Annotate your model classes:

// Domain Entities
class User {
  const User({
    required this.id,
    this.name,
    this.age,
    required this.addresses,
  });

  final String id;
  final String? name;
  final int? age;
  final List<Address> addresses;
}

class Address {
  const Address({
    required this.street,
    required this.city,
  });

  final String street;
  final String city;
}

// Data Models
import 'package:entity_mapper/entity_mapper.dart';

part 'user_model.entity_mapper.dart';

@MapToEntity(User)
class UserModel with UserEntityMappable {
  const UserModel({
    required this.id,
    this.name,
    this.age,
    required this.addresses,
  });

  final String id;
  final String? name;
  final int? age;
  final List<AddressModel> addresses;
}

@MapToEntity(Address)
class AddressModel with AddressEntityMappable {
  const AddressModel({
    required this.street,
    required this.city,
  });

  final String street;
  final String city;
}

Generate code and use:

dart run build_runner build

// Convert model ↔ entity
const addressModel = AddressModel(street: 'Main St', city: 'Metropolis');
const userModel = UserModel(
  id: 'u1',
  name: 'Alice',
  age: 30,
  addresses: [addressModel],
);

// Model to Entity
final userEntity = userModel.toEntity();

// Entity to Model
final userModel2 = UserEntityMapper.toModel(userEntity);

// Nullability example
const userModelNull = UserModel(id: 'u2', addresses: []);
final userEntityNull = userModelNull.toEntity();
print('Null fields: name={userEntityNull.name}, age={userEntityNull.age}');

---

Overview

Annotations

Use @MapToEntity() on model classes to specify the target entity:

@MapToEntity(User) // Target entity type
class UserModel with UserEntityMappable {
  const UserModel({
    required this.id,
    required this.name,
    required this.email,
  });
  final String id;
  final String name;
  final String email;
}

Generated API

Static Mapper Classes:

• {Model}EntityMapper.toModel(entity) - Convert entity to model
• {Model}EntityMapper.toEntity(model) - Convert model to entity

Mixin Methods:

• toEntity() - Convert this model instance to entity

---

Advanced Usage

Nested Models

@MapToEntity(Car)
class CarModel with CarEntityMappable {
  final String brand;
  final EngineModel engine;  // Automatically handles nested mapping
}

@MapToEntity(Engine)
class EngineModel with EngineEntityMappable {
  final String type;
  final int horsepower;
}

Lists

@MapToEntity(User)
class UserModel with UserEntityMappable {
  final String id;
  final List<AddressModel> addresses; // Nested model lists supported
  // ...
}

---

API Reference

Full API documentation is available at pub.dev documentation.

@MapToEntity(Type entityType)

Parameters:

• entityType - The entity type to map to/from

Example:

@MapToEntity(User)
class UserModel with UserEntityMappable {
  // Model implementation
}

---

Examples

Check out the example directory for complete examples including nested models and real-world Clean Architecture scenarios.

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

To run tests:

flutter test

License

This project is licensed under the terms of the MIT License.

Support & Contact

For issues, feature requests, or questions, please use GitHub Issues.

Changelog

See CHANGELOG.md for release notes and version history.

Keywords

#clean-architecture #entity-mapping #code-generation #domain-driven-design #dart-mappable #build-runner #source-gen