Add JsonKey.required, plus other things

json_annotation/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.2.8
+
+* Added `$checkKeys` helper function and deprecated `$checkAllowedKeys`.
+  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

@@ -2,16 +2,37 @@
 // 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.
 
-/// Helper function used in generated code when
+/// **DEPRECATED** Helper function used in generated code when
 /// `JsonSerializable.disallowUnrecognizedKeys` is `true`.
 ///
 /// Should not be used directly.
+@Deprecated('Code generated with the latest `json_serializable` will use '
+    '`\$checkKeys` instead. This function will be removed in the next major '
+    'release.')
 void $checkAllowedKeys(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());
+  $checkKeys(map, allowedKeys: allowedKeys?.toList());
+}
+
+/// 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,
+    {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);
+    }
   }
 }
 
@@ -34,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_annotation/pubspec.yaml

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

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

@@ -170,12 +170,7 @@ class _GeneratorHelper {
 
         fieldsSetByFactory = data.usedCtorParamsAndFields;
 
-        if (_annotation.disallowUnrecognizedKeys) {
-          var listLiteral = jsonLiteralAsDart(
-              accessibleFields.values.map(_nameAccess).toList(), true);
-          _buffer.write('''
-      \$checkAllowedKeys(json, $listLiteral);''');
-        }
+        _writeChecks(6, _annotation, accessibleFields);
         _buffer.write('''
     var val = ${data.content};''');
 
@@ -222,15 +217,7 @@ class _GeneratorHelper {
 
         fieldsSetByFactory = data.usedCtorParamsAndFields;
 
-        if (_annotation.disallowUnrecognizedKeys) {
-          var listLiteral = jsonLiteralAsDart(
-              fieldsSetByFactory
-                  .map((k) => _nameAccess(accessibleFields[k]))
-                  .toList(),
-              true);
-          _buffer.write('''
-  \$checkAllowedKeys(json, $listLiteral);''');
-        }
+        _writeChecks(2, _annotation, accessibleFields);
 
         _buffer.write('''
   return ${data.content}''');
@@ -251,6 +238,31 @@ class _GeneratorHelper {
     return accessibleFields.values.toSet();
   }
 
+  void _writeChecks(int indent, JsonSerializable classAnnotation,
+      Map<String, FieldElement> accessibleFields) {
+    var args = <String>[];
+
+    if (classAnnotation.disallowUnrecognizedKeys) {
+      var allowKeysLiteral = jsonLiteralAsDart(
+          accessibleFields.values.map(_nameAccess).toList(), true);
+
+      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(', ')});');
+    }
+  }
+
   void _writeWrapper(Iterable<FieldElement> fields) {
     _buffer.writeln();
     // TODO(kevmoo): write JsonMapWrapper if annotation lib is prefix-imported

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/pubspec.yaml

@@ -12,7 +12,7 @@ dependencies:
 
   # Use a tight version constraint to ensure that a constraint on
   # `json_annotation`. Properly constrains all features it provides.
-  json_annotation: '>=0.2.7 <0.2.8'
+  json_annotation: '>=0.2.8 <0.2.9'
   meta: ^1.1.0
   path: ^1.3.2
   source_gen: '>=0.8.1 <0.9.0'
@@ -25,3 +25,7 @@ dev_dependencies:
   logging: ^0.11.3+1
   test: ^0.12.3
   yaml: ^2.1.13
+
+dependency_overrides:
+  json_annotation:
+    path: ../json_annotation

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) {
-  $checkAllowedKeys(json, 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,
@@ -29,7 +30,7 @@ abstract class _$ConfigSerializerMixin {
 
 Builder _$BuilderFromJson(Map json) {
   return $checkedNew('Builder', json, () {
-    $checkAllowedKeys(json, const [
+    $checkKeys(json, allowedKeys: const [
       'target',
       'import',
       'is_optional',