Add @JsonEnum annotation

Allows generating the associated helpers without requiring usage as a field
in a @JsonSerializable class

Fixes #778

Author: kevmoo

json_annotation/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Added `JsonSerializabel.constructor` field to allow specifying an alternative
   constructor to invoke when creating a `fromJson` helper.
+- Added `JsonEnum` for annotating `enum` types.  
 
 ## 4.1.0
 

json_annotation/lib/json_annotation.dart

@@ -13,6 +13,7 @@ library json_annotation;
 export 'src/allowed_keys_helpers.dart';
 export 'src/checked_helpers.dart';
 export 'src/json_converter.dart';
+export 'src/json_enum.dart';
 export 'src/json_key.dart';
 export 'src/json_literal.dart';
 export 'src/json_serializable.dart';

json_annotation/lib/src/json_enum.dart

@@ -0,0 +1,13 @@
+// Copyright (c) 2021, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:meta/meta_meta.dart';
+
+/// When applied to `enum` definitions, causes the corresponding private
+//  `_$EnumNameEnumMap` and `_$enumDecode` helpers to be generated, even  if the
+//  `enum` is not referenced elsewhere in generated code.
+@Target({TargetKind.enumType})
+class JsonEnum {
+  const JsonEnum();
+}

json_serializable/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 - Added support for `JsonSerializabel.constructor` to allow specifying an 
   alternative constructor to invoke when creating a `fromJson` helper.
+- Support the new `@JsonEnum` annotation by generating the corresponding private
+  `_$EnumNameEnumMap` and `_$enumDecode` helpers, even  if the `enum` is not
+  referenced elsewhere in generated code.
 - Require `json_annotation` `'>=4.2.0 <4.3.0'`.
 
 ## 5.0.2

json_serializable/lib/json_serializable.dart

@@ -2,5 +2,6 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+export 'src/json_enum_generator.dart' show JsonEnumGenerator;
 export 'src/json_literal_generator.dart' show JsonLiteralGenerator;
 export 'src/json_serializable_generator.dart' show JsonSerializableGenerator;

json_serializable/lib/src/json_enum_generator.dart

@@ -0,0 +1,33 @@
+// Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analyzer/dart/element/element.dart';
+import 'package:build/build.dart';
+import 'package:json_annotation/json_annotation.dart';
+import 'package:source_gen/source_gen.dart';
+
+import 'type_helpers/enum_helper.dart';
+
+class JsonEnumGenerator extends GeneratorForAnnotation<JsonEnum> {
+  const JsonEnumGenerator();
+
+  @override
+  List<String> generateForAnnotatedElement(
+    Element element,
+    ConstantReader annotation,
+    BuildStep buildStep,
+  ) {
+    if (element is! ClassElement || !element.isEnum) {
+      throw InvalidGenerationSourceError(
+        '`@JsonEnum` can only be used on enum elements.',
+        element: element,
+      );
+    }
+
+    return [
+      enumDecodeHelper,
+      enumValueMapFromType(element.thisType)!,
+    ];
+  }
+}

json_serializable/lib/src/json_part_builder.dart

@@ -6,6 +6,7 @@ import 'package:build/build.dart';
 import 'package:json_annotation/json_annotation.dart';
 import 'package:source_gen/source_gen.dart';
 
+import 'json_enum_generator.dart';
 import 'json_literal_generator.dart';
 import 'json_serializable_generator.dart';
 import 'settings.dart';
@@ -23,10 +24,70 @@ Builder jsonPartBuilder({
 
   return SharedPartBuilder(
     [
-      JsonSerializableGenerator.fromSettings(settings),
+      _UnifiedGenerator([
+        JsonSerializableGenerator.fromSettings(settings),
+        const JsonEnumGenerator(),
+      ]),
       const JsonLiteralGenerator(),
     ],
     'json_serializable',
     formatOutput: formatOutput,
   );
 }
+
+/// Allows exposing separate [GeneratorForAnnotation] instances as one
+/// generator.
+///
+/// Output can be merged while keeping implementations separate.
+class _UnifiedGenerator extends Generator {
+  final List<GeneratorForAnnotation> _generators;
+
+  _UnifiedGenerator(this._generators);
+
+  @override
+  Future<String?> generate(LibraryReader library, BuildStep buildStep) async {
+    final values = <String>{};
+
+    for (var generator in _generators) {
+      for (var annotatedElement
+          in library.annotatedWith(generator.typeChecker)) {
+        final generatedValue = generator.generateForAnnotatedElement(
+            annotatedElement.element, annotatedElement.annotation, buildStep);
+        for (var value in _normalizeGeneratorOutput(generatedValue)) {
+          assert(value.length == value.trim().length);
+          values.add(value);
+        }
+      }
+    }
+
+    return values.join('\n\n');
+  }
+
+  @override
+  String toString() => 'JsonSerializableGenerator';
+}
+
+// Borrowed from `package:source_gen`
+Iterable<String> _normalizeGeneratorOutput(Object? value) {
+  if (value == null) {
+    return const [];
+  } else if (value is String) {
+    value = [value];
+  }
+
+  if (value is Iterable) {
+    return value.where((e) => e != null).map((e) {
+      if (e is String) {
+        return e.trim();
+      }
+
+      throw _argError(e as Object);
+    }).where((e) => e.isNotEmpty);
+  }
+  throw _argError(value);
+}
+
+// Borrowed from `package:source_gen`
+ArgumentError _argError(Object value) => ArgumentError(
+    'Must be a String or be an Iterable containing String values. '
+    'Found `${Error.safeToString(value)}` (${value.runtimeType}).');

json_serializable/lib/src/json_serializable_generator.dart

@@ -69,7 +69,7 @@ class JsonSerializableGenerator
       );
     }
 
-    if (element is! ClassElement) {
+    if (element is! ClassElement || element.isEnum) {
       throw InvalidGenerationSourceError(
         '`@JsonSerializable` can only be used on classes.',
         element: element,

json_serializable/lib/src/type_helpers/enum_helper.dart

@@ -21,7 +21,7 @@ class EnumHelper extends TypeHelper<TypeHelperContextWithConfig> {
     String expression,
     TypeHelperContextWithConfig context,
   ) {
-    final memberContent = _enumValueMapFromType(targetType);
+    final memberContent = enumValueMapFromType(targetType);
 
     if (memberContent == null) {
       return null;
@@ -39,13 +39,13 @@ class EnumHelper extends TypeHelper<TypeHelperContextWithConfig> {
     TypeHelperContextWithConfig context,
     bool defaultProvided,
   ) {
-    final memberContent = _enumValueMapFromType(targetType);
+    final memberContent = enumValueMapFromType(targetType);
 
     if (memberContent == null) {
       return null;
     }
 
-    context.addMember(_enumDecodeHelper);
+    context.addMember(enumDecodeHelper);
 
     String functionName;
     if (targetType.isNullableType || defaultProvided) {
@@ -72,7 +72,7 @@ class EnumHelper extends TypeHelper<TypeHelperContextWithConfig> {
 String _constMapName(DartType targetType) =>
     '_\$${targetType.element!.name}EnumMap';
 
-String? _enumValueMapFromType(DartType targetType) {
+String? enumValueMapFromType(DartType targetType) {
   final enumMap = enumFieldsMap(targetType);
 
   if (enumMap == null) {
@@ -87,7 +87,7 @@ String? _enumValueMapFromType(DartType targetType) {
   return 'const ${_constMapName(targetType)} = {\n$items\n};';
 }
 
-const _enumDecodeHelper = r'''
+const enumDecodeHelper = r'''
 K _$enumDecode<K, V>(
   Map<K, V> enumValues,
   Object? source, {

json_serializable/lib/src/type_helpers/json_helper.dart

@@ -270,6 +270,9 @@ InterfaceType? _instantiate(
 }
 
 ClassConfig? _annotation(ClassConfig config, InterfaceType source) {
+  if (source.isEnum) {
+    return null;
+  }
   final annotations = const TypeChecker.fromRuntime(JsonSerializable)
       .annotationsOfExact(source.element, throwOnUnresolved: false)
       .toList();

json_serializable/test/integration/integration_test.dart

@@ -296,4 +296,8 @@ void main() {
 
     validateRoundTrip(value, (json) => PrivateConstructor.fromJson(json));
   });
+
+  test('enum helpers', () {
+    expect(standAloneEnumKeys, ['a', 'b', 'g', 'd']);
+  });
 }

json_serializable/test/integration/json_test_example.dart

@@ -239,3 +239,17 @@ class PrivateConstructor {
   bool operator ==(Object other) =>
       other is PrivateConstructor && id == other.id && value == other.value;
 }
+
+@JsonEnum()
+enum StandAloneEnum {
+  @JsonValue('a')
+  alpha,
+  @JsonValue('b')
+  beta,
+  @JsonValue('g')
+  gamma,
+  @JsonValue('d')
+  delta,
+}
+
+Iterable<String> get standAloneEnumKeys => _$StandAloneEnumEnumMap.values;

json_serializable/test/integration/json_test_example.g.dart

@@ -247,3 +247,17 @@ class PrivateConstructor {
   bool operator ==(Object other) =>
       other is PrivateConstructor && id == other.id && value == other.value;
 }
+
+@JsonEnum()
+enum StandAloneEnum {
+  @JsonValue('a')
+  alpha,
+  @JsonValue('b')
+  beta,
+  @JsonValue('g')
+  gamma,
+  @JsonValue('d')
+  delta,
+}
+
+Iterable<String> get standAloneEnumKeys => _$StandAloneEnumEnumMap.values;