Enum Mapping
Map between enum types, strings, and integers using @ValueMapping.
Enum Mapping
dart_mapper can map between:
- Two enum types
- An enum type and a
String(using the enum constant.name) - An enum type and an
int(using@ValueMappingto declare the values)
Same-Name Enum to Enum
When source and target enum constants share the same name, mapping just works with no configuration:
enum OrderStatus { pending, confirmed, shipped }
enum DisplayStatus { pending, confirmed, shipped }
@Mapper()
abstract class StatusMapper {
DisplayStatus toDisplay(OrderStatus source);
}
Generated:
@override
DisplayStatus toDisplay(OrderStatus source) {
return switch (source) {
OrderStatus.pending => DisplayStatus.pending,
OrderStatus.confirmed => DisplayStatus.confirmed,
OrderStatus.shipped => DisplayStatus.shipped,
};
}
Renamed Enum Values
Use @ValueMapping to map source constants to differently-named target constants:
enum OrderStatus { pending, confirmed, shipped, cancelled }
enum DisplayStatus { waiting, approved, inTransit, rejected }
@Mapper()
abstract class StatusMapper {
@ValueMapping(source: 'pending', target: 'waiting')
@ValueMapping(source: 'confirmed', target: 'approved')
@ValueMapping(source: 'shipped', target: 'inTransit')
@ValueMapping(source: 'cancelled', target: 'rejected')
DisplayStatus toDisplay(OrderStatus source);
}
Default Fallback with ValueMapping.anyRemaining
Map all unmatched source constants to a single target constant:
enum ExtendedColor { red, green, blue, yellow }
enum PrimaryColor { red, green, blue }
@Mapper()
abstract class ColorMapper {
@ValueMapping(source: ValueMapping.anyRemaining, target: 'blue')
PrimaryColor toPrimary(ExtendedColor source);
}
All ExtendedColor values that don't share a name with a PrimaryColor constant (i.e., yellow) map to PrimaryColor.blue.
Null Fallback with ValueMapping.anyUnmapped
Map unmatched source constants to null (only for nullable return types):
@Mapper()
abstract class ColorMapper {
@ValueMapping(source: ValueMapping.anyUnmapped, target: ValueMapping.nullValue)
PrimaryColor? toPrimaryOrNull(ExtendedColor source);
}
Null Source Handling with ValueMapping.nullValue
Use ValueMapping.nullValue to handle null input values when the source is nullable:
@Mapper()
abstract class ColorMapper {
@ValueMapping(source: ValueMapping.nullValue, target: 'blue')
PrimaryColor toPrimaryFromNullable(ExtendedColor? source);
}
When source is null, the mapper returns PrimaryColor.blue.
Enum to String
Map an enum to its string name automatically — no annotations needed:
@Mapper()
abstract class OrderMapper {
String orderStatusToString(OrderStatus source);
}
Generated: return source.name;
String to Enum
Map a string back to an enum constant by matching on .name:
@Mapper()
abstract class OrderMapper {
OrderStatus stringToOrderStatus(String source);
}
Generated: uses a switch expression matching each string literal to the corresponding OrderStatus constant.
Enum to Int
Use @ValueMapping to specify numeric values for enum-to-int mapping:
@Mapper()
abstract class PriorityMapper {
@ValueMapping(source: 'low', target: '1')
@ValueMapping(source: 'medium', target: '2')
@ValueMapping(source: 'high', target: '3')
int priorityToInt(Priority source);
}
Int to Enum
Use @ValueMapping to map integer values back to enum constants:
@Mapper()
abstract class PriorityMapper {
@ValueMapping(target: 'low', source: '1')
@ValueMapping(target: 'medium', source: '2')
@ValueMapping(target: 'high', source: '3')
Priority intToPriority(int source);
}