Add support for JsonKey.required

fixes #216

Author: kevmoo

json_annotation/CHANGELOG.md

@@ -4,6 +4,10 @@
   Upgrading to the latest `json_serializable` and re-running your build will
   eliminate any `@deprecated` hints you see.
 
+* Added `JsonKey.required` field and an associated
+  `MissingRequiredKeysException` that is thrown when `required` fields don't
+  have corresponding keys in a source JSON map.
+
 ## 0.2.7+1
 
 * Small improvement to `UnrecognizedKeysException.message` output and

json_annotation/lib/src/allowed_keys_helpers.dart

@@ -13,16 +13,26 @@ void $checkAllowedKeys(Map map, Iterable<String> allowedKeys) {
   $checkKeys(map, allowedKeys: allowedKeys?.toList());
 }
 
-/// Helper function used in generated code when
-/// `JsonSerializable.disallowUnrecognizedKeys` is `true`.
+/// Helper function used in generated `fromJson` code when
+/// `JsonSerializable.disallowUnrecognizedKeys` is true for an annotated type or
+/// `JsonKey.required` is `true` for any annotated fields.
 ///
 /// Should not be used directly.
-void $checkKeys(Map map, {Iterable<String> allowedKeys}) {
-  if (map == null) return;
-  var invalidKeys = map.keys.where((k) => !allowedKeys.contains(k));
-  if (invalidKeys.isNotEmpty) {
-    throw new UnrecognizedKeysException(
-        new List<String>.from(invalidKeys), map, allowedKeys.toList());
+void $checkKeys(Map map,
+    {List<String> allowedKeys, List<String> requiredKeys}) {
+  if (map != null && allowedKeys != null) {
+    var invalidKeys =
+        map.keys.cast<String>().where((k) => !allowedKeys.contains(k)).toList();
+    if (invalidKeys.isNotEmpty) {
+      throw new UnrecognizedKeysException(invalidKeys, map, allowedKeys);
+    }
+  }
+
+  if (requiredKeys != null) {
+    var missingKeys = requiredKeys.where((k) => !map.keys.contains(k)).toList();
+    if (missingKeys.isNotEmpty) {
+      throw new MissingRequiredKeysException(missingKeys, map);
+    }
   }
 }
 
@@ -45,3 +55,19 @@ class UnrecognizedKeysException implements Exception {
 
   UnrecognizedKeysException(this.unrecognizedKeys, this.map, this.allowedKeys);
 }
+
+/// Exception thrown if there are missing required keys in a JSON map that was
+/// provided during deserialization.
+class MissingRequiredKeysException implements Exception {
+  /// The keys that [map] is missing.
+  final List<String> missingKeys;
+
+  /// The source [Map] that the required keys were missing in.
+  final Map map;
+
+  /// A human-readable message corresponding to the error.
+  String get message => 'Required keys are missing: ${missingKeys.join(', ')}.';
+
+  MissingRequiredKeysException(this.missingKeys, this.map)
+      : assert(missingKeys.isNotEmpty);
+}

json_annotation/lib/src/checked_helpers.dart

@@ -23,6 +23,8 @@ T $checkedNew<T>(String className, Map map, T constructor(),
     String key;
     if (error is ArgumentError) {
       key = fieldKeyMap[error.name] ?? error.name;
+    } else if (error is MissingRequiredKeysException) {
+      key = error.missingKeys.first;
     }
     throw new CheckedFromJsonException._(error, stack, map, key,
         className: className);
@@ -92,6 +94,8 @@ class CheckedFromJsonException implements Exception {
       return error.message?.toString();
     } else if (error is UnrecognizedKeysException) {
       return error.message;
+    } else if (error is MissingRequiredKeysException) {
+      return error.message;
     }
     return null;
   }

json_annotation/lib/src/json_serializable.dart

@@ -129,6 +129,16 @@ class JsonKey {
   /// value is `null`.
   final Object defaultValue;
 
+  /// When `true`, generated code for `fromJson` will verify that the source
+  /// JSON map contains the associated key.
+  ///
+  /// If the key does not exist, a `MissingRequiredKeysException` exception is
+  /// thrown.
+  ///
+  /// Note: only the existence of the key is checked. A key with a `null` value
+  /// is considered valid.
+  final bool required;
+
   /// Creates a new [JsonKey] instance.
   ///
   /// Only required when the default behavior is not desired.
@@ -139,7 +149,8 @@ class JsonKey {
       this.ignore,
       this.fromJson,
       this.toJson,
-      this.defaultValue});
+      this.defaultValue,
+      this.required});
 }
 
 // Until enum supports parse: github.com/dart-lang/sdk/issues/33244

json_serializable/CHANGELOG.md

@@ -1,13 +1,19 @@
 ## 0.5.7
 
+* Added support for `JsonKey.required`.
+  * When `true`, generated code throws a `MissingRequiredKeysException` if
+    the key does not exist in the JSON map used to populate the annotated field.
+  * Will be captured and wrapped in a `CheckedFromJsonException` if
+    `checked` is enabled in `json_serializable`.
+
 * Added support for `Uri` conversion.
 
 ## 0.5.6
 
 * Added support for `JsonSerializable.disallowUnrecognizedKeys`.
   * Throws an `UnrecognizedKeysException` if it finds unrecognized keys in the
-    JSON map used to create the annotated object.
-  * Will be captured captured and wrapped in a `CheckedFromJsonException` if
+    JSON map used to populate the annotated field.
+  * Will be captured and wrapped in a `CheckedFromJsonException` if
     `checked` is enabled in `json_serializable`.
 * All `fromJson` constructors now use block syntax instead of fat arrows.
 

json_serializable/lib/src/generator_helper.dart

@@ -249,6 +249,15 @@ class _GeneratorHelper {
       args.add('allowedKeys: $allowKeysLiteral');
     }
 
+    var requiredKeys =
+        accessibleFields.values.where((fe) => jsonKeyFor(fe).required).toList();
+    if (requiredKeys.isNotEmpty) {
+      var requiredKeyLiteral =
+          jsonLiteralAsDart(requiredKeys.map(_nameAccess).toList(), true);
+
+      args.add('requiredKeys: $requiredKeyLiteral');
+    }
+
     if (args.isNotEmpty) {
       _buffer.writeln('${' ' * indent}\$checkKeys(json, ${args.join(', ')});');
     }

json_serializable/lib/src/json_key_helpers.dart

@@ -119,6 +119,7 @@ JsonKeyWithConversion _from(FieldElement element) {
       obj.getField('includeIfNull').toBoolValue(),
       obj.getField('ignore').toBoolValue(),
       defaultValueLiteral,
+      obj.getField('required').toBoolValue(),
       fromJsonName,
       toJsonName);
 }
@@ -137,16 +138,24 @@ class JsonKeyWithConversion extends JsonKey {
   const JsonKeyWithConversion._empty()
       : fromJsonData = null,
         toJsonData = null,
-        super();
-
-  JsonKeyWithConversion._(String name, bool nullable, bool includeIfNull,
-      bool ignore, Object defaultValue, this.fromJsonData, this.toJsonData)
+        super(required: false);
+
+  JsonKeyWithConversion._(
+      String name,
+      bool nullable,
+      bool includeIfNull,
+      bool ignore,
+      Object defaultValue,
+      bool required,
+      this.fromJsonData,
+      this.toJsonData)
       : super(
             name: name,
             nullable: nullable,
             includeIfNull: includeIfNull,
             ignore: ignore,
-            defaultValue: defaultValue);
+            defaultValue: defaultValue,
+            required: required ?? false);
 }
 
 ConvertData _getFunctionName(

json_serializable/test/kitchen_sink/kitchen_sink_test.dart

@@ -18,16 +18,32 @@ import 'kitchen_sink.non_nullable.wrapped.dart' as nnwrapped
 import 'kitchen_sink.wrapped.dart' as wrapped show testFactory, testFromJson;
 
 import 'kitchen_sink_interface.dart';
+import 'strict_keys_object.dart';
 
 final _isATypeError = const isInstanceOf<TypeError>();
-final _isAUnrecognizedKeysEexception =
-    const isInstanceOf<UnrecognizedKeysException>();
+
+Matcher _isAUnrecognizedKeysEexception(expectedMessage) => allOf(
+    const isInstanceOf<UnrecognizedKeysException>(),
+    new FeatureMatcher<UnrecognizedKeysException>(
+        'message', (e) => e.message, expectedMessage));
+
+Matcher _isMissingKeyException(expectedMessage) => allOf(
+    const isInstanceOf<MissingRequiredKeysException>(),
+    new FeatureMatcher<MissingRequiredKeysException>(
+        'message', (e) => e.message, expectedMessage));
 
 void main() {
   test('valid values covers all keys', () {
     expect(_invalidValueTypes.keys, orderedEquals(_validValues.keys));
   });
 
+  test('required keys', () {
+    expect(
+        () => new StrictKeysObject.fromJson({}),
+        throwsA(_isMissingKeyException(
+            'Required keys are missing: value, custom_field.')));
+  });
+
   group('nullable', () {
     group('unwrapped', () {
       _nullableTests(nullable.testFactory, nullable.testFromJson);
@@ -241,8 +257,11 @@ Matcher _getMatcher(bool checked, String expectedKey, bool checkedAssignment) {
 
     innerMatcher = _checkedMatcher(expectedKey);
   } else {
-    innerMatcher =
-        anyOf(isACastError, _isATypeError, _isAUnrecognizedKeysEexception);
+    innerMatcher = anyOf(
+        isACastError,
+        _isATypeError,
+        _isAUnrecognizedKeysEexception(
+            'Unrecognized keys: [invalid_key]; supported keys: [value, custom_field]'));
 
     if (checkedAssignment) {
       switch (expectedKey) {
@@ -253,7 +272,7 @@ Matcher _getMatcher(bool checked, String expectedKey, bool checkedAssignment) {
           innerMatcher = isArgumentError;
           break;
         case 'strictKeysObject':
-          innerMatcher = _isAUnrecognizedKeysEexception;
+          innerMatcher = _isAUnrecognizedKeysEexception('bob');
           break;
         case 'intIterable':
         case 'datetime-iterable':

json_serializable/test/kitchen_sink/strict_keys_object.dart

@@ -9,10 +9,11 @@ part 'strict_keys_object.g.dart';
 @JsonSerializable(disallowUnrecognizedKeys: true)
 class StrictKeysObject extends Object with _$StrictKeysObjectSerializerMixin {
   @override
+  @JsonKey(required: true)
   final int value;
 
   @override
-  @JsonKey(name: 'custom_field')
+  @JsonKey(name: 'custom_field', required: true)
   final String customField;
 
   StrictKeysObject(this.value, this.customField);

json_serializable/test/kitchen_sink/strict_keys_object.g.dart

@@ -11,7 +11,9 @@ part of 'strict_keys_object.dart';
 // **************************************************************************
 
 StrictKeysObject _$StrictKeysObjectFromJson(Map json) {
-  $checkKeys(json, allowedKeys: const ['value', 'custom_field']);
+  $checkKeys(json,
+      allowedKeys: const ['value', 'custom_field'],
+      requiredKeys: const ['value', 'custom_field']);
   return new StrictKeysObject(
       json['value'] as int, json['custom_field'] as String);
 }

json_serializable/test/yaml/build_config.dart

@@ -11,6 +11,7 @@ part 'build_config.g.dart';
 
 @JsonSerializable()
 class Config extends Object with _$ConfigSerializerMixin {
+  @JsonKey(required: true)
   final Map<String, Builder> builders;
 
   Config({@required this.builders});

json_serializable/test/yaml/build_config.g.dart

@@ -12,6 +12,7 @@ part of 'build_config.dart';
 
 Config _$ConfigFromJson(Map json) {
   return $checkedNew('Config', json, () {
+    $checkKeys(json, requiredKeys: const ['builders']);
     var val = new Config(
         builders: $checkedConvert(
             json,

json_serializable/test/yaml/yaml_test.dart

@@ -121,6 +121,13 @@ line 4, column 5 of file.yaml: Invalid key "baz"
 line 3, column 5 of file.yaml: Invalid key "foo"
     foo: bar
     ^^^''',
+  r'''
+  bob: cool
+  ''': '''
+Could not create `Config`.
+line 1, column 3 of file.yaml: Required keys are missing: builders.
+  bob: cool
+  ^^^^^^^^^^'''
 };
 
 String _prettyPrintCheckedFromJsonException(CheckedFromJsonException err) {
@@ -131,15 +138,21 @@ String _prettyPrintCheckedFromJsonException(CheckedFromJsonException err) {
         orElse: () => null) as YamlScalar;
   }
 
+  var innerError = err.innerError;
+
   var message = 'Could not create `${err.className}`.';
-  if (err.innerError is UnrecognizedKeysException) {
-    var innerError = err.innerError as UnrecognizedKeysException;
+  if (innerError is UnrecognizedKeysException) {
+    expect(err.message, innerError.message);
     message += '\n${innerError.message}\n';
     for (var key in innerError.unrecognizedKeys) {
       var yamlKey = _getYamlKey(key);
       assert(yamlKey != null);
       message += '\n${yamlKey.span.message('Invalid key "$key"')}';
     }
+  } else if (innerError is MissingRequiredKeysException) {
+    expect(err.message, innerError.message);
+    expect(err.key, innerError.missingKeys.first);
+    message += '\n${yamlMap.span.message(innerError.message)}';
   } else {
     var yamlValue = yamlMap.nodes[err.key];