feat: enhance enum serialization with fallback and name overrides

@EnumProperty can now be used to specify a fallback enum constant for invalid string values. Names can be overridden using @PropertyName or the @EnumProperty name field.

Refs: #15

Author: helightdev

packages/dogs_core/lib/src/converter.dart

@@ -37,26 +37,29 @@ abstract class DogConverter<T> extends TypeCapture<T> {
   /// Contains structure information about the type being serialized and provides
   /// an [OperationMode] mapping for all supported operation modes.
   const DogConverter(
-      {this.struct, this.isAssociated = true, @Deprecated(
+      {this.struct,
+      this.isAssociated = true,
+      @Deprecated(
           "This parameter has been removed in favor of the shift towards tree based converters. "
-          "This value is effectively a no-op, please remove it.") this.keepIterables = false});
+          "This value is effectively a no-op, please remove it.")
+      this.keepIterables = false});
 
   /// Returns the operation mode for the given [opmodeType] or null if the
   /// converter does not support the given operation mode by default.
-  OperationMode<T>? resolveOperationMode(DogEngine engine, Type opmodeType) => null;
+  OperationMode<T>? resolveOperationMode(DogEngine engine, Type opmodeType) =>
+      null;
 
   /// Generates a [SchemaType] describing the output generated by this converter.
   ///
   /// NOTE: Do not return a shared instance of [SchemaType] as it will be modified by the
   /// visitor. For such cases, use [SchemaType.clone] to create a new instance.
-  SchemaType describeOutput(DogEngine engine, SchemaConfig config) => SchemaType.any;
+  SchemaType describeOutput(DogEngine engine, SchemaConfig config) =>
+      SchemaType.any;
 }
 
-
 // TODO: Future replacement for @serializable
 /// Configures the dogs structuration of a class or enum.
 class Structure extends Serializable implements StructureMetadata {
-
   /// If the type is serializable.
   final bool serializable;
 
@@ -66,7 +69,6 @@ class Structure extends Serializable implements StructureMetadata {
 
 /// See @[serializable].
 class Serializable {
-
   /// The name of the type used for serialization.
   final String? serialName;
 
@@ -99,9 +101,7 @@ class SerializableLibrary {
 }
 
 /// Marks a class or enum as serializable.
-const serializable = Structure(
-  serializable: true
-);
+const serializable = Structure(serializable: true);
 
 @internal
 class LinkSerializer {
@@ -158,6 +158,22 @@ class PropertySerializer {
   const PropertySerializer(this.type);
 }
 
+/// Configures how the [GeneratedEnumDogConverter] will serialize this individual
+/// enum value. The name can be overridden by specifying a [name]. This enum
+/// value can also be marked as the fallback value.
+class EnumProperty {
+
+  /// The name of the enum value used as a map key in serialization.
+  final String? name;
+
+  /// If this enum value should be used as a fallback value when an invalid
+  /// value is encountered during deserialization.
+  final bool fallback;
+
+  /// Instantiates a new [EnumProperty] with the given [name] and [fallback].
+  const EnumProperty({this.name, this.fallback = false});
+}
+
 /// Simple converter base that only requires a [serialize] and [deserialize]
 /// method. Automatically adds [NativeSerializerMode] as well as a synthetic
 /// [DogStructure] with the given [SimpleDogConverter.serialName].

packages/dogs_core/lib/src/converters/enum.dart

@@ -25,6 +25,16 @@ typedef EnumToString<T> = String Function(T?);
 /// A [DogConverter] that allows for the conversion of enum values to and from strings.
 abstract class GeneratedEnumDogConverter<T extends Enum> extends DogConverter<T>
     with OperationMapMixin<T>, EnumConverter<T> {
+
+  GeneratedEnumDogConverter();
+
+  GeneratedEnumDogConverter.structured({
+    required String serialName
+  }) : super(
+    isAssociated: true,
+    struct: DogStructure<T>.synthetic(serialName)
+  );
+  
   /// Function that converts a enum value to a string.
   EnumToString<T?> get toStr;
 
@@ -38,7 +48,16 @@ abstract class GeneratedEnumDogConverter<T extends Enum> extends DogConverter<T>
   Map<Type, OperationMode<T> Function()> get modes => {
         NativeSerializerMode: () => NativeSerializerMode.create(
             serializer: (value, engine) => toStr(value),
-            deserializer: (value, engine) => fromStr(value)!),
+            deserializer: (value, engine) {
+              final v = fromStr(value);
+              if (v == null) {
+                throw DogSerializerException(
+                  message: "Value '$value' is not a valid enum value.",
+                  converter: this,
+                );
+              }
+              return v;
+            }),
       };
 
   @override

packages/dogs_generator/lib/analyze/structurize.dart

@@ -101,6 +101,7 @@ TypeChecker dataclassChecker = TypeChecker.fromRuntime(Dataclass);
 TypeChecker mapChecker = TypeChecker.fromRuntime(Map);
 TypeChecker beanIgnoreChecker = TypeChecker.fromRuntime(beanIgnore.runtimeType);
 TypeChecker serializableChecker = TypeChecker.fromRuntime(Serializable);
+TypeChecker enumPropertyChecker = TypeChecker.fromRuntime(EnumProperty);
 
 Future<StructurizeResult> structurizeConstructor(
     DartType type,

packages/dogs_generator/lib/builders/converter_builder.dart

@@ -1,12 +1,10 @@
 import 'dart:async';
 
 import 'package:analyzer/dart/element/element.dart';
-import 'package:analyzer/dart/element/type.dart';
 import 'package:build/build.dart';
 import 'package:code_builder/code_builder.dart';
 import 'package:collection/collection.dart';
 import 'package:dogs_core/dogs_core.dart';
-
 import 'package:dogs_generator/dogs_generator.dart';
 import 'package:lyell_gen/lyell_gen.dart';
 import 'package:source_gen/source_gen.dart';
@@ -29,20 +27,49 @@ class ConverterBuilder extends DogsAdapter<Serializable> {
       SubjectCodeContext codeContext) async {
     var emitter = DartEmitter();
     var converterName = "${element.name}Converter";
+
+    String? fallbackFieldName;
+    final fieldValueMap =
+        Map.fromEntries(element.fields.where((e) => e.isEnumConstant).map((e) {
+      final actual = e.name;
+      var serializedName = e.name;
+
+      final propertyName = propertyNameChecker.firstAnnotationOf(e);
+      if (propertyName != null) {
+        serializedName =
+            propertyName.getField("name")?.toStringValue() ?? serializedName;
+      }
+
+      final enumProperty = enumPropertyChecker.firstAnnotationOf(e);
+      if (enumProperty != null) {
+        serializedName =
+            enumProperty.getField("name")?.toStringValue() ?? serializedName;
+        if (enumProperty.getField("fallback")?.toBoolValue() ?? false) {
+          fallbackFieldName = actual;
+        }
+      }
+
+      return MapEntry(actual, serializedName);
+    }));
+
     var clazz = Class((builder) {
       builder.name = converterName;
 
       builder.extend = Reference(
           "$genAlias.GeneratedEnumDogConverter<${codeContext.typeName(element.thisType)}>");
 
+      builder.constructors.add(Constructor((builder) => builder
+        ..initializers.add(Code(
+            "super.structured(serialName: '${codeContext.typeName(element.thisType)}')"))));
+
       builder.methods.add(Method((builder) => builder
         ..name = "values"
         ..type = MethodType.getter
         ..returns = Reference("List<String>")
         ..annotations.add(CodeExpression(Code("override")))
         ..lambda = true
         ..body = Code(
-            "${codeContext.typeName(element.thisType)}.values.map((e) => e.name).toList()")));
+            "[${fieldValueMap.values.map((e) => "'${sqsLiteralEscape(e)}'").join(",")}]")));
 
       builder.methods.add(Method((builder) => builder
         ..name = "toStr"
@@ -51,7 +78,12 @@ class ConverterBuilder extends DogsAdapter<Serializable> {
             "$genAlias.EnumToString<${codeContext.typeName(element.thisType)}> ")
         ..annotations.add(CodeExpression(Code("override")))
         ..lambda = true
-        ..body = Code("(e) => e!.name")));
+        ..body = Code("""
+(e) => switch(e) {
+  ${fieldValueMap.entries.map((e) => "${codeContext.typeName(element.thisType)}.${e.key} => '${sqsLiteralEscape(e.value)}',").join("\n")}
+  null => throw ArgumentError('Enum value cannot be null'),
+}
+""")));
 
       builder.methods.add(Method((builder) => builder
         ..name = "fromStr"
@@ -60,8 +92,15 @@ class ConverterBuilder extends DogsAdapter<Serializable> {
             "$genAlias.EnumFromString<${codeContext.typeName(element.thisType)}> ")
         ..annotations.add(CodeExpression(Code("override")))
         ..lambda = true
-        ..body = Code(
-            "(e) => ${codeContext.typeName(element.thisType)}.values.firstWhereOrNullDogs((element) => element.name == e)")));
+        ..body = Code("""
+(e) => switch(e) {
+  ${fieldValueMap.entries.map((e) => "'${sqsLiteralEscape(e.value)}' => ${codeContext.typeName(element.thisType)}.${e.key},").join("\n")}
+  _ => ${switch (fallbackFieldName) {
+          null => "null",
+          _ => "${codeContext.typeName(element.thisType)}.$fallbackFieldName"
+        }}
+}
+""")));
     });
     codeContext.codeBuffer.writeln(clazz.accept(emitter));
   }
@@ -148,7 +187,8 @@ class ConverterBuilder extends DogsAdapter<Serializable> {
         log.severe("""
 Generic type variables for models are not supported.
 If you wish to use class-level generics, please implement a TreeBaseConverterFactory for your base type.
-        """.trim());
+        """
+            .trim());
       }
 
       var referencedClassName = codeContext.className(element);
@@ -341,7 +381,8 @@ If you wish to use class-level generics, please implement a TreeBaseConverterFac
         builder.body = Code(bodyBuilder.toString());
       }));
 
-      var hasRebuildHook = TypeChecker.fromRuntime(PostRebuildHook).isAssignableFromType(element.thisType);
+      var hasRebuildHook = TypeChecker.fromRuntime(PostRebuildHook)
+          .isAssignableFromType(element.thisType);
 
       builder.methods.add(Method((builder) => builder
         ..name = "build"
@@ -389,8 +430,7 @@ return instance;""")));
         ..type = MethodType.getter
         ..returns = Reference("${element.name}\$Copy")
         ..body = Code("toBuilder()")
-        ..lambda = true
-      ));
+        ..lambda = true));
 
       builder.methods.add(Method((builder) => builder
         ..name = "toBuilder"

smoke/test0/lib/parts/models.dart

@@ -40,7 +40,33 @@ void testModels() {
       FieldExclusionModel.variant0, FieldExclusionModel.variant1);
   testSingleModel<ClassExclusionModel>(
       ClassExclusionModel.variant0, ClassExclusionModel.variant1);
+  testSingleModel<CombinedEnumTestModel>(CombinedEnumTestModel.variant0, CombinedEnumTestModel.variant1);
 
+  test("Enum Properties", () {
+    expect(() {
+      dogs.fromNative<EnumA>("invalid", type: EnumA);
+    }, throwsException);
+
+    final bFallback = dogs.fromNative<EnumB>("invalid");
+    expect(bFallback, EnumB.a);
+
+    final aName = dogs.toNative(EnumA.c);
+    expect(aName, "c");
+    expect(EnumA.c, dogs.fromNative<EnumA>(aName));
+
+    final enumPropertyNameOverride = dogs.toNative(EnumB.c);
+    expect(enumPropertyNameOverride, "third");
+    expect(EnumB.c, dogs.fromNative<EnumB>(enumPropertyNameOverride));
+
+    final propertyNameOverride = dogs.toNative(EnumB.b);
+    expect(propertyNameOverride, "second");
+    expect(EnumB.b, dogs.fromNative<EnumB>(propertyNameOverride));
+
+    final noPropertyNameOverride = dogs.toNative(EnumB.a);
+    expect(noPropertyNameOverride, "a");
+    expect(EnumB.a, dogs.fromNative<EnumB>(noPropertyNameOverride));
+
+  });
 
   test("Default Values", () {
     var defaultValues = DefaultValueModel.variant0();

smoke/test0/lib/special.dart

@@ -249,4 +249,34 @@ class ClassExclusionModel with Dataclass<ClassExclusionModel> {
       b: null,
     );
   }
+}
+
+@serializable
+enum EnumB {
+  @EnumProperty(fallback: true)
+  a,
+  @PropertyName("second")
+  b,
+  @EnumProperty(name: "third")
+  c;
+}
+
+
+@serializable
+class CombinedEnumTestModel with Dataclass<CombinedEnumTestModel> {
+  EnumA enumA;
+  EnumB enumB;
+
+  CombinedEnumTestModel({
+    required this.enumA,
+    required this.enumB,
+  });
+
+  factory CombinedEnumTestModel.variant0() {
+    return CombinedEnumTestModel(enumA: EnumA.a, enumB: EnumB.a);
+  }
+
+  factory CombinedEnumTestModel.variant1() {
+    return CombinedEnumTestModel(enumA: EnumA.c, enumB: EnumB.c);
+  }
 }