entity_mapper #

Quick Start • Documentation • Example • 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: Industry-standard approach and familiar API
• ⚡ Zero runtime overhead: All mapping code generated at build time
• 🛠️ Lightweight & focused: Only Entity ↔ Model mapping (no unnecessary bloat)
• 🔒 Fully type-safe: Generated code maintains complete type safety
• 🎛️ Highly customizable: Custom field mappings, transformations, and more

Quick Start #

Requirements: Dart SDK ≥ 3.8.0, Flutter ≥ 3.32.0

Add dependencies:

flutter pub add entity_mapper
flutter pub add build_runner --dev

Annotate your model classes:

// domain/entities/user.dart
class User {
  const User({required this.id, required this.name, required this.email});
  final String id;
  final String name;
  final String email;
}

// data/models/user_model.dart
import 'package:entity_mapper/entity_mapper.dart';

part 'user_model.entity_mapper.dart';

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

Generate code and use:

dart run build_runner build

// Convert entity ↔ model
final user = User(id: '1', name: 'John', email: 'john@example.com');
final userModel = UserEntityMapper.toModel(user);
final backToEntity = userModel.toEntity();

Overview #

Annotations #

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

@MapToEntity(
  User,                        // Target entity type
  generateToModel: true,       // Generate entity → model (default: true)
  generateToEntity: true,      // Generate model → entity (default: true)
  fieldMappings: {            // Custom field name mappings
    'fullName': 'name',
  },
)
class UserModel with UserEntityMappable { ... }

Use @EntityField() on individual fields for customization:

class UserModel with UserEntityMappable {
  @EntityField(name: 'user_name')                    // Custom entity field name
  final String name;
  
  @EntityField(ignore: true)                         // Skip during mapping
  final String internalId;
  
  @EntityField(customTransform: 'value.toUpperCase()') // Custom transformation
  final String code;
}

Generated API #

Static Mapper Classes:

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

Mixin Methods:

• toEntity() - Convert this model instance to entity

Advanced Usage #

Custom Field Mappings #

@MapToEntity(
  User,
  fieldMappings: {
    'fullName': 'name',        // fullName in model → name in entity
    'emailAddress': 'email',   // emailAddress in model → email in entity
  },
)
class UserModel with UserEntityMappable {
  final String fullName;      // Maps to 'name'
  final String emailAddress;  // Maps to 'email'
}

Selective Generation #

@MapToEntity(User, generateToEntity: false)  // Only entity → model
class ReadOnlyUserModel with UserEntityMappable { ... }

@MapToEntity(User, generateToModel: false)   // Only model → entity  
class WriteOnlyUserModel with UserEntityMappable { ... }

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;
}

API Reference #

@MapToEntity(Type entityType, {bool generateToModel, bool generateToEntity, Map<String, String> fieldMappings}) #

Parameters:

• entityType - The entity type to map to/from
• generateToModel - Generate entity → model method (default: true)
• generateToEntity - Generate model → entity method (default: true)
• fieldMappings - Custom field name mappings

@EntityField({String? name, bool ignore, String? customTransform}) #

Parameters:

• name - Custom field name in the entity
• ignore - Skip this field during mapping (default: false)
• customTransform - Custom transformation expression

Examples #

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

Contributing #

Contributions welcome! Submit issues and pull requests on GitHub.

License #

MIT License

Keywords #

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