feat: implement sealed class serialization

Author: O-Hannonen

_test_yaml/test/src/build_config.dart

@@ -85,7 +85,7 @@ class Builder {
   Map<String, dynamic> toJson() => _$BuilderToJson(this);
 }
 
-@JsonEnum(fieldRename: FieldRename.snake)
+@JsonEnum(fieldRename: RenameType.snake)
 enum AutoApply { none, dependents, allPackages, rootPackage }
 
 enum BuildTo { cache, source }

example/lib/complex_sealed_class_examples.dart

@@ -0,0 +1,36 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'complex_sealed_class_examples.g.dart';
+
+@JsonSerializable(unionDiscriminator: 'organization')
+sealed class Organization {
+  final String name;
+
+  Organization({required this.name});
+
+  factory Organization.fromJson(Map<String, dynamic> json) =>
+      _$OrganizationFromJson(json);
+
+  Map<String, dynamic> toJson() => _$OrganizationToJson(this);
+}
+
+@JsonSerializable(unionDiscriminator: 'department')
+sealed class Department extends Organization {
+  final String departmentHead;
+
+  Department({required this.departmentHead, required super.name});
+
+  factory Department.fromJson(Map<String, dynamic> json) =>
+      _$DepartmentFromJson(json);
+}
+
+@JsonSerializable()
+class Team extends Department {
+  final String teamLead;
+
+  Team({
+    required this.teamLead,
+    required super.departmentHead,
+    required super.name,
+  });
+}

example/lib/complex_sealed_class_examples.g.dart

@@ -0,0 +1,32 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'sealed_class_example.g.dart';
+
+@JsonSerializable(
+  unionDiscriminator: 'vehicle_type',
+  unionRename: RenameType.snake,
+)
+sealed class Vehicle {
+  final String vehicleID;
+
+  Vehicle({required this.vehicleID});
+
+  factory Vehicle.fromJson(Map<String, dynamic> json) =>
+      _$VehicleFromJson(json);
+
+  Map<String, dynamic> toJson() => _$VehicleToJson(this);
+}
+
+@JsonSerializable()
+class Car extends Vehicle {
+  final int numberOfDoors;
+
+  Car({required this.numberOfDoors, required super.vehicleID});
+}
+
+@JsonSerializable()
+class Bicycle extends Vehicle {
+  final bool hasBell;
+
+  Bicycle({required this.hasBell, required super.vehicleID});
+}

example/lib/sealed_class_example.dart

@@ -7,7 +7,7 @@ environment:
 resolution: workspace
 
 dependencies:
-  json_annotation: ^4.9.0
+  json_annotation: ^4.10.0-wip
 
 dev_dependencies:
   # Used by tests. Not required to use `json_serializable`.
@@ -21,7 +21,7 @@ dev_dependencies:
   build_verify: ^3.0.0
 
   # REQUIRED!
-  json_serializable: ^6.8.0
+  json_serializable: ^6.10.0
 
   # Not required to use `json_serializable`.
   path: ^1.8.0

example/lib/sealed_class_example.g.dart

@@ -1,6 +1,9 @@
-## 4.9.1-wip
+## 4.10.0-wip
 
+- Add `JsonSerializable.unionRename`
+- Add `JsonSerializable.unionDiscriminator`
 - Require Dart 3.8
+- Deprecated `FieldRename` in favor of `RenameType`
 
 ## 4.9.0
 

example/pubspec.yaml

@@ -79,6 +79,24 @@ class UnrecognizedKeysException extends BadKeyException {
     : super._(map);
 }
 
+/// Exception thrown if there is an unrecognized union type in a JSON map
+/// that was provided during deserialization.
+class UnrecognizedUnionTypeException extends BadKeyException {
+  /// The discriminator that was not recognized.
+  final String unrecognizedType;
+
+  /// The type of the union that was being deserialized.
+  final Type unionType;
+
+  @override
+  String get message =>
+      'Unrecognized type: $unrecognizedType '
+      'for union: $unionType.';
+
+  UnrecognizedUnionTypeException(this.unrecognizedType, this.unionType, Map map)
+    : super._(map);
+}
+
 /// Exception thrown if there are missing required keys in a JSON map that was
 /// provided during deserialization.
 class MissingRequiredKeysException extends BadKeyException {

json_annotation/CHANGELOG.md

@@ -12,7 +12,7 @@ import 'json_value.dart';
 class JsonEnum {
   const JsonEnum({
     this.alwaysCreate = false,
-    this.fieldRename = FieldRename.none,
+    this.fieldRename = RenameType.none,
     this.valueField,
   });
 
@@ -27,14 +27,14 @@ class JsonEnum {
   /// Defines the naming strategy when converting enum entry names to JSON
   /// values.
   ///
-  /// With a value [FieldRename.none] (the default), the name of the enum entry
+  /// With a value [RenameType.none] (the default), the name of the enum entry
   /// is used without modification.
   ///
-  /// See [FieldRename] for details on the other options.
+  /// See [RenameType] for details on the other options.
   ///
   /// Note: the value for [JsonValue.value] takes precedence over this option
   /// for entries annotated with [JsonValue].
-  final FieldRename fieldRename;
+  final RenameType fieldRename;
 
   /// Specifies the field within an "enhanced enum" to use as the value
   /// to use for serialization.

json_annotation/lib/src/allowed_keys_helpers.dart

@@ -12,8 +12,12 @@ import 'json_key.dart';
 
 part 'json_serializable.g.dart';
 
+// TODO: Remove typedef
+@Deprecated('Use RenameType instead')
+typedef FieldRename = RenameType;
+
 /// Values for the automatic field renaming behavior for [JsonSerializable].
-enum FieldRename {
+enum RenameType {
   /// Use the field name without changes.
   none,
 
@@ -35,7 +39,7 @@ enum FieldRename {
 @JsonSerializable(
   checked: true,
   disallowUnrecognizedKeys: true,
-  fieldRename: FieldRename.snake,
+  fieldRename: RenameType.snake,
 )
 @Target({TargetKind.classType})
 class JsonSerializable {
@@ -153,14 +157,14 @@ class JsonSerializable {
   /// Defines the automatic naming strategy when converting class field names
   /// into JSON map keys.
   ///
-  /// With a value [FieldRename.none] (the default), the name of the field is
+  /// With a value [RenameType.none] (the default), the name of the field is
   /// used without modification.
   ///
-  /// See [FieldRename] for details on the other options.
+  /// See [RenameType] for details on the other options.
   ///
   /// Note: the value for [JsonKey.name] takes precedence over this option for
   /// fields annotated with [JsonKey].
-  final FieldRename? fieldRename;
+  final RenameType? fieldRename;
 
   /// When `true` on classes with type parameters (generic types), extra
   /// "helper" parameters will be generated for `fromJson` and/or `toJson` to
@@ -224,6 +228,20 @@ class JsonSerializable {
   /// `includeIfNull`, that value takes precedent.
   final bool? includeIfNull;
 
+  /// The discriminator key used to identify the union type.
+  ///
+  /// Defaults to `type`.
+  final String? unionDiscriminator;
+
+  /// Defines the automatic naming strategy when converting class names
+  /// to union type names.
+  ///
+  /// With a value [RenameType.none] (the default), the name of the class is
+  /// used without modification.
+  ///
+  /// See [RenameType] for details on the other options.
+  final RenameType? unionRename;
+
   /// A list of [JsonConverter] to apply to this class.
   ///
   /// Writing:
@@ -276,6 +294,8 @@ class JsonSerializable {
     this.converters,
     this.genericArgumentFactories,
     this.createPerFieldToJson,
+    this.unionDiscriminator,
+    this.unionRename,
   });
 
   factory JsonSerializable.fromJson(Map<String, dynamic> json) =>
@@ -292,10 +312,12 @@ class JsonSerializable {
     createToJson: true,
     disallowUnrecognizedKeys: false,
     explicitToJson: false,
-    fieldRename: FieldRename.none,
+    fieldRename: RenameType.none,
     ignoreUnannotated: false,
     includeIfNull: true,
     genericArgumentFactories: false,
+    unionDiscriminator: 'type',
+    unionRename: RenameType.none,
   );
 
   /// Returns a new [JsonSerializable] instance with fields equal to the
@@ -318,6 +340,8 @@ class JsonSerializable {
     includeIfNull: includeIfNull ?? defaults.includeIfNull,
     genericArgumentFactories:
         genericArgumentFactories ?? defaults.genericArgumentFactories,
+    unionDiscriminator: unionDiscriminator ?? defaults.unionDiscriminator,
+    unionRename: unionRename ?? defaults.unionRename,
   );
 
   Map<String, dynamic> toJson() => _$JsonSerializableToJson(this);