Entity Mapper #

Clean Architecture entity mapping made simple.

Description #

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

Features #

• 🎯 Focused Scope: Only Entity ↔ Model mapping (not full class generation)
• 🔄 "dart_mappable" Pattern: Industry-standard approach
• 🏗️ Clean Architecture: Specifically designed for DDD patterns
• ⚡ Light Weight: No unnecessary class generation
• 🛠️ Customizable: Support for custom field mappings and transformations

Installation 💻 #

❗ In order to start using Entity Mapper you must have the Flutter SDK installed on your machine.

Add to your pubspec.yaml:

dependencies:
  entity_mapper: ^0.1.0

dev_dependencies:
  build_runner: ^2.6.0

Install it:

flutter pub get

Usage 🚀 #

1. Define Your Entity and Model #

// Domain Entity (Pure)
class User {
  const User({
    required this.id,
    required this.name,
    required this.email,
    required this.createdAt,
  });

  final String id;
  final String name;
  final String email;
  final DateTime createdAt;
}

// Data Model (w/ Data manipulation methods)
part 'user_model.entity_mapper.dart';

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

  final String id;
  final String name;
  final String email;
  final DateTime createdAt;
}

2. Run Code Generation #

flutter packages pub run build_runner build

3. Use Generated Methods/Mappers #

// Create entity
final user = User(
  id: '1',
  name: 'John Doe',
  email: 'john@example.com',
  createdAt: DateTime.now(),
);

// Convert entity to model
final userModel = UserEntityMapper.toModel(user);

// Convert model to entity
final userEntity1 = userModel.toEntity();
final userEntity2 = UserEntityMapper.toEntity(userModel);

Advanced Usage #

Custom Field Mappings #

@MapToEntity(
  User,
  fieldMappings: {
    'fullName': 'name',  // Map 'fullName' field to 'name' in entity
  },
)
class UserModel with UserEntityMappable {
  final String id;
  final String fullName;  // Different field name
  final String email;
  
  // ...
}

Ignoring Fields #

class UserModel with UserEntityMappable {
  final String id;
  final String name;
  
  @EntityField(ignore: true)
  final String internalField;  // This field will be ignored during mapping
  
  // ...
}

Custom Field Names #

class UserModel with UserEntityMappable {
  final String id;
  
  @EntityField(name: 'user_name')
  final String name;  // Maps to 'user_name' field in entity
  
  // ...
}

Nested Models #

// Domain Entities (Pure)
class Car {
  const Car({
    required this.brand,
    required this.model,
    required this.engine,
  });
  
  final String brand;
  final String model;
  final Engine engine;
}

class Engine {
  const Engine({
    required this.type,
    required this.horsepower,
  });
  
  final String type;
  final int horsepower;
}

// Data Models (w/ Data manipulation methods)
@MapToEntity(Car)
class CarModel with CarEntityMappable {
  const CarModel({
    required this.brand,
    required this.model,
    required this.engine,
  });
  
  final String brand;
  final String model;
  final EngineModel engine;
}

@MapToEntity(Engine)
class EngineModel with EngineEntityMappable {
  const EngineModel({
    required this.type,
    required this.horsepower,
  });
  
  final String type;
  final int horsepower;
}

API Reference #

Annotations #

@MapToEntity(Type entityType)

Marks a class for automatic entity mapping generation.

Parameters:

• entityType: The entity type to map to/from
• generateToModel: Whether to generate the toModel method (default: true)
• generateToEntity: Whether to generate the toEntity method (default: true)
• fieldMappings: Custom field mappings for complex transformations

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

Provides additional metadata for entity field mapping.

Parameters:

• name: Custom name for the field in the entity
• ignore: Whether to ignore this field during mapping (default: false)
• customTransform: Custom transformation expression

Examples #

Check out the example directory for more detailed examples.

Continuous Integration 🤖 #

Entity Mapper comes with a built-in GitHub Actions workflow powered by Very Good Workflows but you can also add your preferred CI/CD solution.

Out of the box, on each pull request and push, the CI formats, lints, and tests the code. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses Very Good Analysis for a strict set of analysis options used by our team. Code coverage is enforced using the Very Good Workflows.

Running Tests 🧪 #

For first time users, install the very_good_cli:

dart pub global activate very_good_cli

To run all unit tests:

very_good test --coverage

To view the generated coverage report you can use lcov.

# Generate Coverage Report
genhtml coverage/lcov.info -o coverage/

# Open Coverage Report
open coverage/index.html

Keywords #

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