feature: allow customizing enum value serialization via annotations

* Require the latest Dart SDK
  Annotated enums fail without the CFE

* Require the latest pkg:analyzer
  Enum metadata parsing was just recently added

* Require the latest pkg:source_gen
  Uses multiple return values to allow generating shared helpers

* Deprecates enum helpers in json_annotation
  They can now be generated as part of the source, which minimizes
  versioning issues with helpers.

* Small, but breaking changes to Generator API to return multiple
  values

* Added `addMember` API to Context classes to allow helpers to be
  generated.

* Updated integration test code to include an annotated enum

* Updated yaml test code to remove now superfluous convert logic and use
  annotated enums instead

Fixes #38

Author: kevmoo

json_annotation/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.2.10
+
+* Deprecated `$enumDecode` and `$enumDecodeNullable` which are no longer needed
+  by the latest release of `package:json_serializable`.
+
 ## 0.2.9
 
 * When `FormatException` is caught in "checked mode", use the `message`

json_annotation/lib/src/json_serializable.dart

@@ -195,6 +195,8 @@ class JsonKey {
 }
 
 // Until enum supports parse: github.com/dart-lang/sdk/issues/33244
+/// **DEPRECATED** No longer used by `package:source_gen` `^0.6.0`.
+///
 /// *Helper function used in generated code with `enum` values – should not be
 /// used directly.*
 ///
@@ -209,12 +211,17 @@ class JsonKey {
 /// ```dart
 /// $enumDecode('Example', Example.values, 'desiredValue')
 /// ```
+@Deprecated('This member is no longer needed by code generated by '
+    'package:json_serializable ^0.6.0. Upgrade your dependency and regenerate '
+    'your code to remove the deprecation warning.')
 T $enumDecode<T>(String enumName, List<T> values, String enumValue) =>
     values.singleWhere((e) => e.toString() == '$enumName.$enumValue',
         orElse: () => throw new ArgumentError(
             '`$enumValue` is not one of the supported values: '
             '${values.map(_nameForEnumValue).join(', ')}'));
 
+/// **DEPRECATED** No longer used by `package:source_gen` `^0.6.0`.
+///
 /// *Helper function used in generated code with `enum` values – should not be
 /// used directly.*
 ///
@@ -230,6 +237,9 @@ T $enumDecode<T>(String enumName, List<T> values, String enumValue) =>
 /// ```dart
 /// $enumDecodeNullable('Example', Example.values, 'desiredValue')
 /// ```
+@Deprecated('This member is no longer needed by code generated by '
+    'package:json_serializable ^0.6.0. Upgrade your dependency and regenerate '
+    'your code to remove the deprecation warning.')
 T $enumDecodeNullable<T>(String enumName, List<T> values, String enumValue) =>
     enumValue == null ? null : $enumDecode(enumName, values, enumValue);
 

json_annotation/pubspec.yaml

@@ -1,5 +1,5 @@
 name: json_annotation
-version: 0.2.9
+version: 0.2.10-dev
 description: >-
   Classes and helper functions that support JSON code generation via the
   `json_serializable` package.

json_serializable/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.6.0
+
+* Now supports changing the serialized values of enums using `JsonKey`.
+
+  ```dart
+  enum AutoApply {
+    none,
+    dependents,
+    @JsonKey(name: 'all_packages')
+    allPackages,
+    @JsonKey(name: 'root_package')
+    rootPackage
+  }
+  ```
+
+* `JsonSerializableGenerator.generateForAnnotatedElement` now returns
+  `Iterable<String>` instead of `String`.
+
+* `SerializeContext` and `DeserializeContext` now have an `addMember` function
+  which allows `TypeHelper` instances to add additional members when handling
+  a field. This is useful for generating shared helpers, for instance.
+
 ## 0.5.8
 
 * Small fixes to support Dart 2 runtime semantics.

json_serializable/lib/src/helper_core.dart

@@ -20,6 +20,8 @@ abstract class HelperCore {
 
   HelperCore(this.generator, this.element, this.annotation);
 
+  void addMember(String memberContent);
+
   String get targetClassReference =>
       '${element.name}${genericClassArgumentsImpl(false)}';
 
@@ -41,7 +43,7 @@ abstract class HelperCore {
       new JsonKeyWithConversion(field, annotation);
 
   TypeHelperContext getHelperContext(FieldElement field) =>
-      new TypeHelperContext(generator, field.metadata, jsonKeyFor(field));
+      new TypeHelperContext(this, field.metadata, jsonKeyFor(field));
 }
 
 InvalidGenerationSourceError createInvalidGenerationError(

json_serializable/lib/src/json_key_with_conversion.dart

@@ -12,15 +12,13 @@ import 'package:source_gen/source_gen.dart';
 import 'json_literal_generator.dart';
 import 'utils.dart';
 
-final _jsonKeyChecker = const TypeChecker.fromRuntime(JsonKey);
-
 JsonKeyWithConversion _from(
     FieldElement element, JsonSerializable classAnnotation) {
   // If an annotation exists on `element` the source is a 'real' field.
   // If the result is `null`, check the getter – it is a property.
   // TODO(kevmoo) setters: github.com/dart-lang/json_serializable/issues/24
-  var obj = _jsonKeyChecker.firstAnnotationOfExact(element) ??
-      _jsonKeyChecker.firstAnnotationOfExact(element.getter);
+  var obj = jsonKeyChecker.firstAnnotationOfExact(element) ??
+      jsonKeyChecker.firstAnnotationOfExact(element.getter);
 
   if (obj == null) {
     return new JsonKeyWithConversion._(classAnnotation);
@@ -79,15 +77,13 @@ JsonKeyWithConversion _from(
   var defaultValueObject = obj.getField('defaultValue');
 
   Object defaultValueLiteral;
-  if (isEnum(defaultValueObject.type)) {
-    var interfaceType = defaultValueObject.type as InterfaceType;
-    var allowedValues = interfaceType.element.fields
-        .where((p) => !p.isSynthetic)
-        .map((p) => p.name)
-        .toList();
+
+  var enumFields = iterateEnumFields(defaultValueObject.type);
+  if (enumFields != null) {
+    var allowedValues = enumFields.map((p) => p.name).toList();
     var enumValueIndex = defaultValueObject.getField('index').toIntValue();
     defaultValueLiteral =
-        '${interfaceType.name}.${allowedValues[enumValueIndex]}';
+        '${defaultValueObject.type.name}.${allowedValues[enumValueIndex]}';
   } else {
     defaultValueLiteral = _getLiteral(defaultValueObject, []);
     if (defaultValueLiteral != null) {

json_serializable/lib/src/json_serializable_generator.dart

@@ -158,7 +158,7 @@ class JsonSerializableGenerator
               new List.unmodifiable(typeHelpers.followedBy(_defaultHelpers)));
 
   @override
-  String generateForAnnotatedElement(
+  Iterable<String> generateForAnnotatedElement(
       Element element, ConstantReader annotation, BuildStep buildStep) {
     if (element is! ClassElement) {
       var name = element.name;
@@ -170,7 +170,7 @@ class JsonSerializableGenerator
     var classElement = element as ClassElement;
     var classAnnotation = valueForAnnotation(annotation);
     var helper = new _GeneratorHelper(this, classElement, classAnnotation);
-    return helper._generate().join('\n\n');
+    return helper._generate();
   }
 }
 
@@ -179,7 +179,15 @@ class _GeneratorHelper extends HelperCore with EncodeHelper, DecodeHelper {
       JsonSerializable annotation)
       : super(generator, element, annotation);
 
+  final _addedMembers = new Set<String>();
+
+  @override
+  void addMember(String memberContent) {
+    _addedMembers.add(memberContent);
+  }
+
   Iterable<String> _generate() sync* {
+    assert(_addedMembers.isEmpty);
     var sortedFields = _createSortedFieldSet(element);
 
     // Used to keep track of why a field is ignored. Useful for providing
@@ -223,6 +231,8 @@ class _GeneratorHelper extends HelperCore with EncodeHelper, DecodeHelper {
     if (annotation.createToJson) {
       yield* createToJson(accessibleFieldSet);
     }
+
+    yield* _addedMembers;
   }
 }
 

json_serializable/lib/src/type_helper.dart

@@ -6,19 +6,27 @@ import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 
 abstract class SerializeContext {
+  /// `true` if [serialize] should handle the case of `expression` being null.
   bool get nullable;
   bool get useWrappers;
 
   /// [expression] may be just the name of the field or it may an expression
   /// representing the serialization of a value.
   String serialize(DartType fieldType, String expression);
   List<ElementAnnotation> get metadata;
+
+  /// Adds [memberContent] to the set of generated, top-level members.
+  void addMember(String memberContent);
 }
 
 abstract class DeserializeContext {
+  /// `true` if [deserialize] should handle the case of `expression` being null.
   bool get nullable;
   String deserialize(DartType fieldType, String expression);
   List<ElementAnnotation> get metadata;
+
+  /// Adds [memberContent] to the set of generated, top-level members.
+  void addMember(String memberContent);
 }
 
 abstract class TypeHelper {

json_serializable/lib/src/type_helper_context.dart

@@ -5,31 +5,38 @@
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 
+import 'helper_core.dart';
 import 'json_key_with_conversion.dart';
 import 'json_serializable_generator.dart';
 import 'type_helper.dart';
 
 class TypeHelperContext implements SerializeContext, DeserializeContext {
+  final HelperCore _helperCore;
+
   @override
   final List<ElementAnnotation> metadata;
 
-  final JsonSerializableGenerator _generator;
   final JsonKeyWithConversion _key;
 
   @override
-  bool get useWrappers => _generator.useWrappers;
+  bool get useWrappers => _helperCore.generator.useWrappers;
 
-  bool get anyMap => _generator.anyMap;
+  bool get anyMap => _helperCore.generator.anyMap;
 
-  bool get explicitToJson => _generator.explicitToJson;
+  bool get explicitToJson => _helperCore.generator.explicitToJson;
 
   @override
   bool get nullable => _key.nullable;
 
   ConvertData get fromJsonData => _key.fromJsonData;
   ConvertData get toJsonData => _key.toJsonData;
 
-  TypeHelperContext(this._generator, this.metadata, this._key);
+  TypeHelperContext(this._helperCore, this.metadata, this._key);
+
+  @override
+  void addMember(String memberContent) {
+    _helperCore.addMember(memberContent);
+  }
 
   @override
   String serialize(DartType targetType, String expression) => _run(
@@ -45,7 +52,8 @@ class TypeHelperContext implements SerializeContext, DeserializeContext {
 
   String _run(DartType targetType, String expression,
           String invoke(TypeHelper instance)) =>
-      allHelpersImpl(_generator).map(invoke).firstWhere((r) => r != null,
+      allHelpersImpl(_helperCore.generator).map(invoke).firstWhere(
+          (r) => r != null,
           orElse: () => throw new UnsupportedTypeError(
               targetType, expression, _notSupportedWithTypeHelpersMsg));
 }

json_serializable/lib/src/type_helpers/enum_helper.dart

@@ -15,26 +15,75 @@ class EnumHelper extends TypeHelper {
   @override
   String serialize(
       DartType targetType, String expression, SerializeContext context) {
-    if (!isEnum(targetType)) {
+    var memberContent = _enumValueMapFromType(targetType);
+
+    if (memberContent == null) {
       return null;
     }
 
-    var nullableLiteral = context.nullable ? '?' : '';
+    context.addMember(memberContent);
 
-    return '$expression$nullableLiteral.toString()'
-        "$nullableLiteral.split('.')$nullableLiteral.last";
+    return '${_constMapName(targetType)}[$expression]';
   }
 
   @override
   String deserialize(
       DartType targetType, String expression, DeserializeContext context) {
-    if (!isEnum(targetType)) {
+    var memberContent = _enumValueMapFromType(targetType);
+
+    if (memberContent == null) {
       return null;
     }
 
+    context.addMember(_enumDecodeHelper);
+
+    if (context.nullable) {
+      context.addMember(_enumDecodeHelperNullable);
+    }
+
+    context.addMember(memberContent);
+
     var functionName =
-        context.nullable ? r'$enumDecodeNullable' : r'$enumDecode';
-    return "$functionName('$targetType', $targetType.values, "
+        context.nullable ? r'_$enumDecodeNullable' : r'_$enumDecode';
+    return '$functionName(${_constMapName(targetType)}, '
         '$expression as String)';
   }
 }
+
+String _constMapName(DartType targetType) => '_\$${targetType.name}EnumMap';
+
+String _enumValueMapFromType(DartType targetType) {
+  var enumMap = enumFieldsMap(targetType);
+
+  if (enumMap == null) {
+    return null;
+  }
+
+  var items = enumMap.entries
+      .map((e) => "  ${targetType.name}.${e.key.name} : '${e.value}'");
+
+  return 'const ${_constMapName(targetType)} = '
+      'const <${targetType.name}, String>{\n${items.join(',\n')}\n};';
+}
+
+const _enumDecodeHelper = r'''
+T _$enumDecode<T>(Map<T, String> enumValues, String source) {
+  if (source == null) {
+    throw new ArgumentError('A value must be provided. Supported values: '
+        '${enumValues.values.join(', ')}');
+  }
+  return enumValues.entries
+      .singleWhere((e) => e.value == source,
+          orElse: () => throw new ArgumentError(
+              '`$source` is not one of the supported values: '
+              '${enumValues.values.join(', ')}'))
+      .key;
+}''';
+
+const _enumDecodeHelperNullable = r'''
+T _$enumDecodeNullable<T>(Map<T, String> enumValues, String source) {
+  if (source == null) {
+    return null;
+  }
+  return _$enumDecode<T>(enumValues, source);
+}''';