Add sentinel value for null as the fallback for an unknown enum value

Fixes #559

Author: kevmoo

json_annotation/CHANGELOG.md

@@ -5,6 +5,8 @@
 - Added `JsonEnum` for annotating `enum` types.
 - Added `$enumDecodeNullable` and `$enumDecode` helpers to minimize generated
   code.
+- Added `const` `JsonKey.nullForUndefinedEnumValue` for use in
+  `JsonKey.unknownEnumValue` when you want to use `null` for an unknown value.
 - Require Dart SDK `>=2.14.0`.
 
 ## 4.1.0

json_annotation/lib/src/enum_helpers.dart

@@ -2,6 +2,8 @@
 // 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 'json_key.dart';
+
 /// Returns the key associated with value [source] from [enumValues], if one
 /// exists.
 ///
@@ -14,13 +16,31 @@
 /// Not meant to be used directly by user code.
 K? $enumDecodeNullable<K extends Enum, V>(
   Map<K, V> enumValues,
-  dynamic source, {
-  K? unknownValue,
+  Object? source, {
+  Object? unknownValue,
 }) {
   if (source == null) {
     return null;
   }
-  return $enumDecode<K, V>(enumValues, source, unknownValue: unknownValue);
+
+  for (var entry in enumValues.entries) {
+    if (entry.value == source) {
+      return entry.key;
+    }
+  }
+
+  if (unknownValue == JsonKey.nullForUndefinedEnumValue) {
+    return null;
+  }
+
+  if (unknownValue == null) {
+    throw ArgumentError(
+      '`$source` is not one of the supported values: '
+      '${enumValues.values.join(', ')}',
+    );
+  }
+
+  return unknownValue as K;
 }
 
 /// Returns the key associated with value [source] from [enumValues], if one
@@ -45,16 +65,18 @@ K $enumDecode<K extends Enum, V>(
     );
   }
 
-  return enumValues.entries.singleWhere(
-    (e) => e.value == source,
-    orElse: () {
-      if (unknownValue == null) {
-        throw ArgumentError(
-          '`$source` is not one of the supported values: '
-          '${enumValues.values.join(', ')}',
-        );
-      }
-      return MapEntry(unknownValue, enumValues.values.first);
-    },
-  ).key;
+  for (var entry in enumValues.entries) {
+    if (entry.value == source) {
+      return entry.key;
+    }
+  }
+
+  if (unknownValue == null) {
+    throw ArgumentError(
+      '`$source` is not one of the supported values: '
+      '${enumValues.values.join(', ')}',
+    );
+  }
+
+  return unknownValue;
 }

json_annotation/lib/src/json_key.dart

@@ -91,6 +91,10 @@ class JsonKey {
   /// source enum.
   ///
   /// Valid only on enum fields with a compatible enum value.
+  ///
+  /// If you want to use the value `null` when encountering an unknown value,
+  /// use the value of [JsonKey.nullForUndefinedEnumValue] instead. This is only
+  /// valid on an nullable enum field.
   final Object? unknownEnumValue;
 
   /// Creates a new [JsonKey] instance.
@@ -108,4 +112,10 @@ class JsonKey {
     this.toJson,
     this.unknownEnumValue,
   });
+
+  /// Sentinel value for use with [unknownEnumValue].
+  ///
+  /// Read the documentation on [unknownEnumValue] for more details.
+  static const Object nullForUndefinedEnumValue =
+      r'JsonKey.nullForUndefinedEnumValue';
 }

json_serializable/CHANGELOG.md

@@ -3,6 +3,8 @@
 - Added support for `JsonSerializabel.constructor` to allow specifying an 
   alternative constructor to invoke when creating a `fromJson` helper.
 - Support the new `@JsonEnum` annotation in `package:json_annotation`.
+- Support `JsonKey.nullForUndefinedEnumValue` as a value for
+  `JsonKey.unknownEnumValue` when you want to use `null` as the unknown value.
 - Use the new `$enumDecodeNullable` and `$enumDecode` in `json_annotation'
   instead of generating these for each library.
   **NOTE**: This is a potential breaking change if any user code relies on

json_serializable/lib/src/json_key_utils.dart

@@ -6,6 +6,7 @@ import 'package:analyzer/dart/constant/value.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:build/build.dart';
+import 'package:json_annotation/json_annotation.dart';
 import 'package:source_gen/source_gen.dart';
 import 'package:source_helper/source_helper.dart';
 
@@ -171,6 +172,9 @@ KeyConfig _from(FieldElement element, ClassConfig classAnnotation) {
         return null;
       }
       if (mustBeEnum) {
+        if (defaultValueLiteral == JsonKey.nullForUndefinedEnumValue) {
+          return defaultValueLiteral as String;
+        }
         throwUnsupported(
           element,
           'The value provided for `$fieldName` must be a matching enum.',
@@ -212,7 +216,7 @@ KeyConfig _populateJsonKey(
   bool? includeIfNull,
   String? name,
   bool? required,
-  Object? unknownEnumValue,
+  String? unknownEnumValue,
 }) {
   if (disallowNullValue == true) {
     if (includeIfNull == true) {

json_serializable/lib/src/type_helpers/config_types.dart

@@ -18,7 +18,7 @@ class KeyConfig {
 
   final bool required;
 
-  final Object? unknownEnumValue;
+  final String? unknownEnumValue;
 
   KeyConfig({
     required this.defaultValue,

json_serializable/lib/src/type_helpers/enum_helper.dart

@@ -3,6 +3,8 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analyzer/dart/element/type.dart';
+import 'package:json_annotation/json_annotation.dart';
+import 'package:source_gen/source_gen.dart';
 import 'package:source_helper/source_helper.dart';
 
 import '../enum_utils.dart';
@@ -44,6 +46,26 @@ class EnumHelper extends TypeHelper<TypeHelperContextWithConfig> {
       return null;
     }
 
+    final jsonKey = jsonKeyForField(context.fieldElement, context.config);
+
+    if (jsonKey.defaultValue == "'${JsonKey.nullForUndefinedEnumValue}'") {
+      throw InvalidGenerationSourceError(
+        '`${JsonKey.nullForUndefinedEnumValue}` cannot be used with '
+        '`JsonKey.defaultValue`.',
+        element: context.fieldElement,
+      );
+    }
+
+    if (!targetType.isNullableType &&
+        jsonKey.unknownEnumValue == JsonKey.nullForUndefinedEnumValue) {
+      // If the target is not nullable,
+      throw InvalidGenerationSourceError(
+        '`${JsonKey.nullForUndefinedEnumValue}` cannot be used with '
+        '`JsonKey.unknownEnumValue` unless the field is nullable.',
+        element: context.fieldElement,
+      );
+    }
+
     String functionName;
     if (targetType.isNullableType || defaultProvided) {
       functionName = r'$enumDecodeNullable';
@@ -53,7 +75,6 @@ class EnumHelper extends TypeHelper<TypeHelperContextWithConfig> {
 
     context.addMember(memberContent);
 
-    final jsonKey = jsonKeyForField(context.fieldElement, context.config);
     final args = [
       constMapName(targetType),
       expression,

json_serializable/test/integration/integration_test.dart

@@ -2,6 +2,7 @@
 // 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:json_annotation/json_annotation.dart';
 import 'package:test/test.dart';
 
 import '../test_utils.dart';
@@ -302,4 +303,23 @@ void main() {
     expect(standAloneEnumValues, ['a', 'b', 'g', 'd']);
     expect(dayTypeEnumValues, ['no-good', 'rotten', 'very-bad']);
   });
+
+  test('unknown as null for enum', () {
+    expect(
+      () => Issue559Regression.fromJson({}).status,
+      throwsA(isA<MissingRequiredKeysException>()),
+    );
+    expect(
+      () => Issue559Regression.fromJson({'status': null}).status,
+      throwsA(isA<DisallowedNullValueException>()),
+    );
+    expect(
+      Issue559Regression.fromJson({'status': 'gamma'}).status,
+      Issue559RegressionEnum.gamma,
+    );
+    expect(
+      Issue559Regression.fromJson({'status': 'bob'}).status,
+      isNull,
+    );
+  });
 }

json_serializable/test/integration/json_enum_example.dart

@@ -24,3 +24,28 @@ enum DayType {
 }
 
 Iterable<String> get dayTypeEnumValues => _$DayTypeEnumMap.values;
+
+@JsonSerializable(
+  createToJson: false,
+)
+class Issue559Regression {
+  Issue559Regression({
+    required this.status,
+  });
+
+  factory Issue559Regression.fromJson(Map<String, dynamic> json) =>
+      _$Issue559RegressionFromJson(json);
+
+  @JsonKey(
+    disallowNullValue: true,
+    required: true,
+    unknownEnumValue: JsonKey.nullForUndefinedEnumValue,
+  )
+  final Issue559RegressionEnum? status;
+}
+
+enum Issue559RegressionEnum {
+  alpha,
+  beta,
+  gamma,
+}

json_serializable/test/integration/json_enum_example.g.dart

@@ -41,6 +41,7 @@ const _expectedAnnotatedTests = {
   'BadOneNamed',
   'BadToFuncReturnType',
   'BadTwoRequiredPositional',
+  'BadEnumDefaultValue',
   '_BetterPrivateNames',
   'CtorDefaultValueAndJsonKeyDefaultValue',
   'DefaultDoubleConstants',
@@ -98,6 +99,7 @@ const _expectedAnnotatedTests = {
   'NoDeserializeFieldType',
   'NoSerializeBadKey',
   'NoSerializeFieldType',
+  'NullForUndefinedEnumValueOnNonNullableField',
   'ObjectConvertMethods',
   'OkayOneNormalOptionalNamed',
   'OkayOneNormalOptionalPositional',
@@ -130,6 +132,7 @@ const _expectedAnnotatedTests = {
   'UnsupportedSetField',
   'UnsupportedUriField',
   'ValidToFromFuncClassStatic',
+  'WeirdValueForUnknownEnumValue',
   'WithANonCtorGetter',
   'WithANonCtorGetterChecked',
   'WrongConstructorNameClass',

json_serializable/test/json_serializable_test.dart

@@ -73,6 +73,19 @@ class DefaultWithNestedEnum {
   DefaultWithNestedEnum();
 }
 
+@ShouldThrow(
+  '`JsonKey.nullForUndefinedEnumValue` cannot be used with '
+  '`JsonKey.defaultValue`.',
+  element: 'enumValue',
+)
+@JsonSerializable()
+class BadEnumDefaultValue {
+  @JsonKey(defaultValue: JsonKey.nullForUndefinedEnumValue)
+  Enum? enumValue;
+
+  BadEnumDefaultValue();
+}
+
 @ShouldGenerate(
   r'''
 DefaultWithToJsonClass _$DefaultWithToJsonClassFromJson(

json_serializable/test/src/default_value_input.dart

@@ -86,3 +86,23 @@ class UnknownEnumValueNotEnumField {
   @JsonKey(unknownEnumValue: UnknownEnumValueItems.vUnknown)
   int? value;
 }
+
+@ShouldThrow(
+  '`JsonKey.nullForUndefinedEnumValue` cannot be used with '
+  '`JsonKey.unknownEnumValue` unless the field is nullable.',
+)
+@JsonSerializable()
+class NullForUndefinedEnumValueOnNonNullableField {
+  @JsonKey(unknownEnumValue: JsonKey.nullForUndefinedEnumValue)
+  late UnknownEnumValueItems value;
+}
+
+@ShouldThrow(
+  'Error with `@JsonKey` on the `value` field. `unknownEnumValue` is '
+  '`JsonSerializable`, it must be a literal.',
+)
+@JsonSerializable()
+class WeirdValueForUnknownEnumValue {
+  @JsonKey(unknownEnumValue: JsonSerializable())
+  late UnknownEnumValueItems value;
+}