feat: add field and class level serialization hooks to exclude null values

Refs: #15

Author: helightdev

packages/dogs_core/lib/src/hooks.dart

@@ -40,8 +40,8 @@ abstract class SerializationHook implements StructureMetadata {
   /// - `map`: The map representation of the object to be deserialized.
   /// - `structure`: The `DogStructure` instance associated with the object to be deserialized.
   /// - `engine`: The `DogEngine` instance that will perform the deserialization.
-  void beforeDeserialization(Map<String, dynamic> map, DogStructure structure,
-      DogEngine engine) {}
+  void beforeDeserialization(
+      Map<String, dynamic> map, DogStructure structure, DogEngine engine) {}
 }
 
 /// `FieldSerializationHook` is a mixin for field structure metadata
@@ -50,12 +50,19 @@ abstract class SerializationHook implements StructureMetadata {
 ///
 /// This interface is used by [NativeSerializerMode] and descendants.
 mixin FieldSerializationHook on StructureMetadata {
-
   /// This method is called after a field is serialized by [NativeSerializerMode].
-  void postFieldSerialization(NativeStructureContext context, NativeStructureFieldContext fieldContext, Map<String, dynamic> map, DogEngine engine) {}
+  void postFieldSerialization(
+      NativeStructureContext context,
+      NativeStructureFieldContext fieldContext,
+      Map<String, dynamic> map,
+      DogEngine engine) {}
 
   /// This method is called before a field is deserialized by [NativeSerializerMode].
-  void beforeFieldDeserialization(NativeStructureContext context, NativeStructureFieldContext fieldContext, Map<String, dynamic> map, DogEngine engine) {}
+  void beforeFieldDeserialization(
+      NativeStructureContext context,
+      NativeStructureFieldContext fieldContext,
+      Map<String, dynamic> map,
+      DogEngine engine) {}
 }
 
 /// A function that may be used to transform a map before deserialization.
@@ -79,8 +86,8 @@ class LightweightMigration extends SerializationHook {
 
   /// Executes each migration function in the `migrations` list before deserialization.
   @override
-  void beforeDeserialization(Map<String, dynamic> map, DogStructure structure,
-      DogEngine engine) {
+  void beforeDeserialization(
+      Map<String, dynamic> map, DogStructure structure, DogEngine engine) {
     for (var value in migrations) {
       value(map, structure, engine);
     }
@@ -112,8 +119,8 @@ class RevisionMigration extends SerializationHook {
   /// Executes each migration function in the `migrations` list that corresponds to
   /// a version number greater than or equal to the current version.
   @override
-  void beforeDeserialization(Map<String, dynamic> map, DogStructure structure,
-      DogEngine engine) {
+  void beforeDeserialization(
+      Map<String, dynamic> map, DogStructure structure, DogEngine engine) {
     final version = map[revisionKey] as int? ?? 0;
     for (var i = version; i < migrations.length; i++) {
       if (i >= version) {
@@ -146,26 +153,64 @@ class DefaultValue extends StructureMetadata with FieldSerializationHook {
   /// otherwise it will be removed if the field is equal to the default value.
   const DefaultValue(this.value, {this.keep = false});
 
-  dynamic _getNativeDefault(NativeStructureFieldContext fieldContext, DogEngine engine) {
+  dynamic _getNativeDefault(
+      NativeStructureFieldContext fieldContext, DogEngine engine) {
     final provided = value is DefaultValueSupplier ? value() : value;
     final native = fieldContext.encodeValue(provided, engine);
     return native;
   }
 
   @override
-  void beforeFieldDeserialization(NativeStructureContext context, NativeStructureFieldContext fieldContext, Map<String, dynamic> map, DogEngine engine) {
+  void beforeFieldDeserialization(
+      NativeStructureContext context,
+      NativeStructureFieldContext fieldContext,
+      Map<String, dynamic> map,
+      DogEngine engine) {
     if (!map.containsKey(fieldContext.key)) {
       map[fieldContext.key] = _getNativeDefault(fieldContext, engine);
     }
   }
 
   @override
-  void postFieldSerialization(NativeStructureContext context, NativeStructureFieldContext fieldContext, Map<String, dynamic> map, DogEngine engine) {
+  void postFieldSerialization(
+      NativeStructureContext context,
+      NativeStructureFieldContext fieldContext,
+      Map<String, dynamic> map,
+      DogEngine engine) {
     if (!keep) {
       final nativeValue = _getNativeDefault(fieldContext, engine);
       if (deepEquality.equals(map[fieldContext.key], nativeValue)) {
         map.remove(fieldContext.key);
       }
     }
   }
-}
+}
+
+/// A **field** and **class** level serialization hook that excludes fields
+/// with a `null` value from the serialized map.
+const ExcludeNull excludeNull = ExcludeNull();
+
+/// A **field** and **class** level serialization hook that excludes fields
+/// with a `null` value from the serialized map.
+class ExcludeNull extends SerializationHook with FieldSerializationHook {
+  const ExcludeNull();
+
+  @override
+  void postFieldSerialization(
+      NativeStructureContext context,
+      NativeStructureFieldContext fieldContext,
+      Map<String, dynamic> map,
+      DogEngine engine) {
+    // Remove the field if its value is null
+    if (map[fieldContext.key] == null) {
+      map.remove(fieldContext.key);
+    }
+  }
+
+  @override
+  void postSerialization(dynamic obj, Map<String, dynamic> map,
+      DogStructure structure, DogEngine engine) {
+    // Remove all null values from the map
+    map.removeWhere((key, value) => value == null);
+  }
+}

smoke/test0/lib/parts/models.dart

@@ -36,6 +36,11 @@ void testModels() {
   testSingleModel<GetterModel>(GetterModel.variant0, GetterModel.variant1);
   testSingleModel<DefaultValueModel>(
       DefaultValueModel.variant0, DefaultValueModel.variant1);
+  testSingleModel<FieldExclusionModel>(
+      FieldExclusionModel.variant0, FieldExclusionModel.variant1);
+  testSingleModel<ClassExclusionModel>(
+      ClassExclusionModel.variant0, ClassExclusionModel.variant1);
+
 
   test("Default Values", () {
     var defaultValues = DefaultValueModel.variant0();
@@ -55,6 +60,17 @@ void testModels() {
     expect(serialName, isNotNull);
     expect(serialName, "MyCustomSerialName");
   });
+
+  test("Exclusion Hooks", () {
+    final fieldMap = dogs.toNative(FieldExclusionModel.variant1()) as Map;
+    final classMap = dogs.toNative(ClassExclusionModel.variant1()) as Map;
+
+    expect(fieldMap.containsKey("always"), true);
+    expect(fieldMap.containsKey("maybe"), false);
+
+    expect(classMap.containsKey("a"), false);
+    expect(classMap.containsKey("b"), false);
+  });
 }
 
 void testSingleModel<T>(T Function() a, T Function() b) => group("$T", () {

smoke/test0/lib/special.dart

@@ -196,4 +196,57 @@ class DefaultValueModel with Dataclass<DefaultValueModel> {
 class CustomSerialName {
   String value;
   CustomSerialName(this.value);
+}
+
+@serializable
+class FieldExclusionModel with Dataclass<FieldExclusionModel> {
+  String? always;
+
+  @excludeNull
+  String? maybe;
+
+  FieldExclusionModel({
+    this.always,
+    this.maybe,
+  });
+
+  factory FieldExclusionModel.variant0() {
+    return FieldExclusionModel(
+      always: "always",
+      maybe: "maybe",
+    );
+  }
+
+  factory FieldExclusionModel.variant1() {
+    return FieldExclusionModel(
+      always: null,
+      maybe: null,
+    );
+  }
+}
+
+@serializable
+@excludeNull
+class ClassExclusionModel with Dataclass<ClassExclusionModel> {
+  String? a;
+  String? b;
+
+  ClassExclusionModel({
+    this.a,
+    this.b,
+  });
+
+  factory ClassExclusionModel.variant0() {
+    return ClassExclusionModel(
+      a: "always",
+      b: "maybe",
+    );
+  }
+
+  factory ClassExclusionModel.variant1() {
+    return ClassExclusionModel(
+      a: null,
+      b: null,
+    );
+  }
 }