Allow customizable "reading" of JSON maps (#1045)

Allows aliasing values to different names or computing a single
field value from any aspect of the source JSON map

Fixes #144
Fixes #888

Author: kevmoo

_test_yaml/pubspec.yaml

@@ -8,7 +8,7 @@ dev_dependencies:
   build_runner: ^2.0.0
   build_verify: ^2.0.0
   checked_yaml: any
-  json_annotation: ^4.3.0
+  json_annotation: ^4.4.0
   json_serializable: any
   test: ^1.6.0
   yaml: ^3.0.0

json_annotation/CHANGELOG.md

@@ -1,5 +1,8 @@
-## 4.3.1-dev
+## 4.4.0-dev
 
+- Added `JsonKey.readValue`.
+- Non-breaking updates to `checkedCreate` and `checkedConvert` to support
+  `JsonKey.readValue`.
 - Improved `toString` in included exceptions.
 
 ## 4.3.0

json_annotation/lib/src/checked_helpers.dart

@@ -13,11 +13,22 @@ typedef _CastFunction<R> = R Function(Object?);
 T $checkedCreate<T>(
   String className,
   Map map,
-  T Function(S Function<S>(String, _CastFunction<S>) converter) constructor, {
+  T Function(
+    S Function<S>(
+      String,
+      _CastFunction<S>, {
+      Object? Function(Map, String)? readValue,
+    }),
+  )
+      constructor, {
   Map<String, String> fieldKeyMap = const {},
 }) {
-  Q _checkedConvert<Q>(String key, _CastFunction<Q> convertFunction) =>
-      $checkedConvert<Q>(map, key, convertFunction);
+  Q _checkedConvert<Q>(
+    String key,
+    _CastFunction<Q> convertFunction, {
+    Object? Function(Map, String)? readValue,
+  }) =>
+      $checkedConvert<Q>(map, key, convertFunction, readValue: readValue);
 
   return $checkedNew(
     className,
@@ -69,9 +80,14 @@ T $checkedNew<T>(
 /// `JsonSerializableGenerator.checked` is `true`.
 ///
 /// Should not be used directly.
-T $checkedConvert<T>(Map map, String key, T Function(dynamic) castFunc) {
+T $checkedConvert<T>(
+  Map map,
+  String key,
+  T Function(dynamic) castFunc, {
+  Object? Function(Map, String)? readValue,
+}) {
   try {
-    return castFunc(map[key]);
+    return castFunc(readValue == null ? map[key] : readValue(map, key));
   } on CheckedFromJsonException {
     rethrow;
   } catch (error, stack) {

json_annotation/lib/src/json_key.dart

@@ -67,6 +67,21 @@ class JsonKey {
   /// If `null`, the field name is used.
   final String? name;
 
+  /// Specialize how a value is read from the source JSON map.
+  ///
+  /// Typically, the value corresponding to a given key is read directly from
+  /// the JSON map using `map[key]`. At times it's convenient to customize this
+  /// behavior to support alternative names or to support logic that requires
+  /// accessing multiple values at once.
+  ///
+  /// The provided, the [Function] must be a top-level or static within the
+  /// using class.
+  ///
+  /// Note: using this feature does not change any of the subsequent decoding
+  /// logic for the field. For instance, if the field is of type [DateTime] we
+  /// expect the function provided here to return a [String].
+  final Object? Function(Map, String)? readValue;
+
   /// When `true`, generated code for `fromJson` will verify that the source
   /// JSON map contains the associated key.
   ///
@@ -108,6 +123,7 @@ class JsonKey {
     this.ignore,
     this.includeIfNull,
     this.name,
+    this.readValue,
     this.required,
     this.toJson,
     this.unknownEnumValue,

json_serializable/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 6.1.0-dev
+
+- Support `JsonKey.readValue` to allow customized reading of values from source
+  JSON map objects.
+- Require `json_annotation` `'>=4.4.0 <4.5.0'`.
+
 ## 6.0.1
 
 - Don't require `json_annotation` in `dependencies` if it's just used in tests.

json_serializable/README.md

@@ -199,14 +199,14 @@ targets:
 [`Enum`]: https://api.dart.dev/stable/dart-core/Enum-class.html
 [`int`]: https://api.dart.dev/stable/dart-core/int-class.html
 [`Iterable`]: https://api.dart.dev/stable/dart-core/Iterable-class.html
-[`JsonConverter`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonConverter-class.html
-[`JsonEnum`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonEnum-class.html
-[`JsonKey.fromJson`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonKey/fromJson.html
-[`JsonKey.toJson`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonKey/toJson.html
-[`JsonKey`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonKey-class.html
-[`JsonLiteral`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonLiteral-class.html
-[`JsonSerializable`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonSerializable-class.html
-[`JsonValue`]: https://pub.dev/documentation/json_annotation/4.3.0/json_annotation/JsonValue-class.html
+[`JsonConverter`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonConverter-class.html
+[`JsonEnum`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonEnum-class.html
+[`JsonKey.fromJson`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/fromJson.html
+[`JsonKey.toJson`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey/toJson.html
+[`JsonKey`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonKey-class.html
+[`JsonLiteral`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonLiteral-class.html
+[`JsonSerializable`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonSerializable-class.html
+[`JsonValue`]: https://pub.dev/documentation/json_annotation/latest/json_annotation/JsonValue-class.html
 [`List`]: https://api.dart.dev/stable/dart-core/List-class.html
 [`Map`]: https://api.dart.dev/stable/dart-core/Map-class.html
 [`num`]: https://api.dart.dev/stable/dart-core/num-class.html

json_serializable/lib/src/check_dependencies.dart

@@ -10,7 +10,7 @@ import 'package:pubspec_parse/pubspec_parse.dart';
 
 const _productionDirectories = {'lib', 'bin'};
 const _annotationPkgName = 'json_annotation';
-final requiredJsonAnnotationMinVersion = Version.parse('4.3.0');
+final requiredJsonAnnotationMinVersion = Version.parse('4.4.0');
 
 Future<void> pubspecHasRightVersion(BuildStep buildStep) async {
   final segments = buildStep.inputId.pathSegments;

json_serializable/lib/src/decode_helper.dart

@@ -86,16 +86,24 @@ abstract class DecodeHelper implements HelperCore {
         ..write('''
     final val = ${data.content};''');
 
-      for (final field in data.fieldsToSet) {
+      for (final fieldName in data.fieldsToSet) {
         sectionBuffer.writeln();
-        final safeName = safeNameAccess(accessibleFields[field]!);
+        final fieldValue = accessibleFields[fieldName]!;
+        final safeName = safeNameAccess(fieldValue);
         sectionBuffer
           ..write('''
     \$checkedConvert($safeName, (v) => ''')
-          ..write('val.$field = ')
-          ..write(_deserializeForField(accessibleFields[field]!,
-              checkedProperty: true))
-          ..write(');');
+          ..write('val.$fieldName = ')
+          ..write(
+            _deserializeForField(fieldValue, checkedProperty: true),
+          );
+
+        final readValueFunc = jsonKeyFor(fieldValue).readValueFunctionName;
+        if (readValueFunc != null) {
+          sectionBuffer.writeln(',readValue: $readValueFunc,');
+        }
+
+        sectionBuffer.write(');');
       }
 
       sectionBuffer.write('''\n    return val;
@@ -182,6 +190,8 @@ abstract class DecodeHelper implements HelperCore {
     }
   }
 
+  /// If [checkedProperty] is `true`, we're using this function to write to a
+  /// setter.
   String _deserializeForField(
     FieldElement field, {
     ParameterElement? ctorParam,
@@ -192,6 +202,7 @@ abstract class DecodeHelper implements HelperCore {
     final contextHelper = getHelperContext(field);
     final jsonKey = jsonKeyFor(field);
     final defaultValue = jsonKey.defaultValue;
+    final readValueFunc = jsonKey.readValueFunctionName;
 
     String deserialize(String expression) => contextHelper
         .deserialize(
@@ -206,14 +217,21 @@ abstract class DecodeHelper implements HelperCore {
       if (config.checked) {
         value = deserialize('v');
         if (!checkedProperty) {
-          value = '\$checkedConvert($jsonKeyName, (v) => $value)';
+          final readValueBit =
+              readValueFunc == null ? '' : ',readValue: $readValueFunc,';
+          value = '\$checkedConvert($jsonKeyName, (v) => $value$readValueBit)';
         }
       } else {
         assert(
           !checkedProperty,
           'should only be true if `_generator.checked` is true.',
         );
-        value = deserialize('json[$jsonKeyName]');
+
+        value = deserialize(
+          readValueFunc == null
+              ? 'json[$jsonKeyName]'
+              : '$readValueFunc(json, $jsonKeyName)',
+        );
       }
     } on UnsupportedTypeError catch (e) // ignore: avoid_catching_errors
     {

json_serializable/lib/src/json_key_utils.dart

@@ -209,6 +209,13 @@ KeyConfig _from(FieldElement element, ClassConfig classAnnotation) {
     }
   }
 
+  String? readValueFunctionName;
+  final readValue = obj.read('readValue');
+  if (!readValue.isNull) {
+    final objValue = readValue.objectValue.toFunctionValue()!;
+    readValueFunctionName = objValue.name;
+  }
+
   return _populateJsonKey(
     classAnnotation,
     element,
@@ -217,6 +224,7 @@ KeyConfig _from(FieldElement element, ClassConfig classAnnotation) {
     ignore: obj.read('ignore').literalValue as bool?,
     includeIfNull: obj.read('includeIfNull').literalValue as bool?,
     name: obj.read('name').literalValue as String?,
+    readValueFunctionName: readValueFunctionName,
     required: obj.read('required').literalValue as bool?,
     unknownEnumValue: _annotationValue('unknownEnumValue', mustBeEnum: true),
   );
@@ -230,6 +238,7 @@ KeyConfig _populateJsonKey(
   bool? ignore,
   bool? includeIfNull,
   String? name,
+  String? readValueFunctionName,
   bool? required,
   String? unknownEnumValue,
 }) {
@@ -249,6 +258,7 @@ KeyConfig _populateJsonKey(
     includeIfNull: _includeIfNull(
         includeIfNull, disallowNullValue, classAnnotation.includeIfNull),
     name: name ?? encodedFieldName(classAnnotation.fieldRename, element.name),
+    readValueFunctionName: readValueFunctionName,
     required: required ?? false,
     unknownEnumValue: unknownEnumValue,
   );

json_serializable/lib/src/type_helpers/config_types.dart

@@ -20,12 +20,15 @@ class KeyConfig {
 
   final String? unknownEnumValue;
 
+  final String? readValueFunctionName;
+
   KeyConfig({
     required this.defaultValue,
     required this.disallowNullValue,
     required this.ignore,
     required this.includeIfNull,
     required this.name,
+    required this.readValueFunctionName,
     required this.required,
     required this.unknownEnumValue,
   });