feat: add DogNativeMapReader and ConverterHelperExtensions for improved deserialization

Author: helightdev

docs/basics/converters.md

@@ -17,7 +17,7 @@ class LatLng {
   String toString() => "LatLng($lat, $lng)";
 }
 
-@linkSerializer/*(1)!*/
+@dogsLinked/*(1)!*/
 class LatLngConverter extends SimpleDogConverter<LatLng>/*(2)!*/ {
   LatLngConverter() : super(serialName: "LatLng");
 
@@ -34,13 +34,13 @@ class LatLngConverter extends SimpleDogConverter<LatLng>/*(2)!*/ {
 }
 ```
 
-1. The `@linkSerializer` annotation is used to automatically register the converter in the `DogEngine`.
+1. The `@linkSerializer` annotation is used to automatically register compatible extensions in the `DogEngine`.
 2. The `SimpleDogConverter` class is a convenience class that implements `DogConverter` and provides
    both the NativeSerializerMode and the GraphSerializerMode. It also creates a synthetic structure for
    the converter type that uses the `serialName`.
 
 In this example, we created a converter for the `LatLng` class. The converter is registered in the
-`DogEngine` using the `@linkSerializer` annotation. The 'SimpleDogConverter' base class is the easiest
+`DogEngine` using the `@dogsLinked` annotation. The 'SimpleDogConverter' base class is the easiest
 way to create a converter – it implements the `DogConverter` interface and automatically creates a native
 serialization mode and a synthetic structure.
 
@@ -74,6 +74,7 @@ first base type. If the type tree has type arguments, the base converter will mo
 recursively**.
 
 ``` { .dart title="List Converter using createIterableFactory" } 
+@dogsLinked
 final myListFactory = TreeBaseConverterFactory.createIterableFactory<MyList>(
   wrap: <T>(Iterable<T> entries) => MyList(entries.toList()),
   unwrap: <T>(MyList value) => value,
@@ -83,17 +84,19 @@ Iterable converters are the most basic and also the most common type of tree con
 easy to create and can be used to convert any type of iterable. The `wrap` and `unwrap` functions
 are used to convert the iterable to and from the tree's base type.
 
-``` { .dart title="Registering a custom tree base factory"  }
-dogs.registerTreeBaseFactory(
-  TypeToken<MyConverterBaseType>(),
-  myCustomConverterFactory
-);
-```
+??? note "Manual Registration"
+    You can register a custom tree base factory using the `registerTreeBaseFactory` method of the `DogEngine`.
 
-You can register a custom tree base factory using the `registerTreeBaseFactory` method of the `DogEngine`.
+    ```{ .dart title="Registering a custom tree base factory" }
+    dogs.registerTreeBaseFactory(
+      TypeToken<MyConverterBaseType>(),
+      myCustomConverterFactory
+    );
+    ```
 
 
 ```{ .dart title="Map Converter using NTreeArgConverter" }
+@dogsLinked
 final mapFactory = TreeBaseConverterFactory.createNargsFactory<Map>(
   nargs: 2, consume: <K, V>() => MapNTreeArgConverter<K, V>()
 );

packages/dogs_core/lib/dogs_converter_utils.dart

@@ -0,0 +1,118 @@
+library;
+
+import "package:dogs_core/dogs_core.dart";
+
+/// Utility class for converters to access dogs deserialization capabilities when decoding custom
+/// map structures.
+class DogNativeMapReader {
+  final DogEngine _engine;
+  final Map<String, dynamic> _backing;
+  final DogConverter _converter;
+
+  /// Utility class for converters to access dogs deserialization capabilities when decoding custom
+  /// map structures.
+  const DogNativeMapReader(this._engine, this._backing, this._converter);
+
+  /// Reads a value of type [T] from the backing map by [key].
+  /// The type parameter [T] must be specified explicitly and cannot be nullable.
+  ///
+  /// Strategy:
+  /// 1. If the key is not found and [defaultValue] is provided, returns [defaultValue]. Otherwise,
+  /// throws [DogSerializerException].
+  /// 2. If the value is already of type [T], returns it.
+  /// 3. If [T] is a native type (as per the engine's codec), attempts to coerce the value to [T].
+  /// 4. Otherwise, uses the engine to deserialize the value into type [T].
+  T read<T>(String key, [T? defaultValue]) {
+    final value = _backing[key];
+    if (value == null) {
+      if (defaultValue != null) return defaultValue;
+      throw DogSerializerException(message: "Missing required field '$key'", converter: _converter);
+    }
+    if (value is T) return value;
+    if (_engine.codec.isNative(T)) {
+      try {
+        return _engine.codec.primitiveCoercion.coerce(TypeToken<T>(), value, key);
+      } catch (e) {
+        throw DogSerializerException(
+          message: "Failed to coerce field '$key' to type $T: $e",
+          converter: _converter,
+          cause: e,
+        );
+      }
+    }
+    try {
+      return _engine.fromNative<T>(value);
+    } catch (e) {
+      throw DogSerializerException(
+        message: "Failed to deserialize field '$key' to type $T: $e",
+        converter: _converter,
+        cause: e,
+      );
+    }
+  }
+
+  /// Reads a value of type [T] from the backing map by [key], expecting it to be exactly of type [T].
+  T expects<T>(String key, [String? message]) {
+    final value = _backing[key];
+    if (value is T) return value;
+    throw DogSerializerException(
+        message: message ?? "Expected type $T for field '$key' but got ${value.runtimeType}");
+  }
+
+  /// Direct access to the underlying map to retrieve raw values.
+  dynamic operator [](String key) => _backing[key];
+}
+
+/// Extension methods for [DogConverter] to simplify common deserialization tasks.
+extension ConverterHelperExtensions on DogConverter {
+  /// Converts this object to a [DogNativeMapReader] if it is a [Map<String, dynamic>],
+  /// otherwise throws a [DogSerializerException].
+  DogNativeMapReader readAsMap(dynamic input, DogEngine engine) {
+    if (input is Map<String, dynamic>) {
+      return DogNativeMapReader(engine, input, this);
+    }
+    throw DogSerializerException(message: "Expected a map but got $runtimeType", converter: this);
+  }
+
+  /// Reads a value of type [T] from [value].
+  T readAs<T>(dynamic value, DogEngine engine, [T? defaultValue]) {
+    if (value == null) {
+      if (defaultValue != null) return defaultValue;
+      throw DogSerializerException(message: "Value is null", converter: this);
+    }
+    if (value is T) return value;
+    if (engine.codec.isNative(T)) {
+      try {
+        return engine.codec.primitiveCoercion.coerce(TypeToken<T>(), value, null);
+      } catch (e) {
+        throw DogSerializerException(
+          message: "Failed to coerce value to type $T: $e",
+          converter: this,
+          cause: e,
+        );
+      }
+    }
+    try {
+      return engine.fromNative<T>(value);
+    } catch (e) {
+      throw DogSerializerException(
+        message: "Failed to deserialize value to type $T: $e",
+        converter: this,
+        cause: e,
+      );
+    }
+  }
+
+  /// Casts this object to type [T] if possible, otherwise throws a [DogSerializerException].
+  T expects<T>(dynamic input, DogEngine engine, [String? message]) {
+    if (input is T) return input;
+    throw DogSerializerException(
+        message: message ?? "Expected type $T but got $runtimeType", converter: this);
+  }
+
+  /// Casts this object to type [T] if possible, otherwise returns [defaultValue].
+  T expectsOr<T>(dynamic input, T defaultValue, DogEngine engine) {
+    if (input is T) return input;
+    return defaultValue;
+  }
+}

packages/dogs_flutter/lib/converters/auto.dart

@@ -1,18 +1,21 @@
+import 'package:dogs_core/dogs_converter_utils.dart';
 import 'package:dogs_core/dogs_core.dart';
 import 'package:flutter/painting.dart';
 
-List<double> _parseDoubleTuple4(dynamic value, {required String typeName}) {
-  if (value is! List) {
-    throw DogSerializerException(message: "Invalid $typeName value, expected a list");
-  }
-  if (value.length != 4) {
-    throw DogSerializerException(message: "Invalid $typeName value, expected 4 values");
-  }
-  final [a, b, c, d] = value;
-  if (a is num && b is num && c is num && d is num) {
-    return [a.toDouble(), b.toDouble(), c.toDouble(), d.toDouble()];
+List<double> _parseDoubleTuple4(dynamic value, DogEngine engine, DogConverter converter) {
+  var list = converter.expects<List>(value, engine);
+  if (list.length != 4) {
+    throw DogSerializerException(
+      message: "Expected list of 4 numeric values",
+      converter: converter,
+    );
   }
-  throw DogSerializerException(message: "Invalid $typeName value, expected numeric values");
+  return [
+    converter.readAs<double>(list[0], engine),
+    converter.readAs<double>(list[1], engine),
+    converter.readAs<double>(list[2], engine),
+    converter.readAs<double>(list[3], engine),
+  ];
 }
 
 @linkSerializer
@@ -21,14 +24,8 @@ class FlutterOffsetConverter extends SimpleDogConverter<Offset> {
 
   @override
   Offset deserialize(value, DogEngine engine) {
-    if (value is Map<String, dynamic>) {
-      var dx = value["dx"];
-      var dy = value["dy"];
-      if (dx is num && dy is num) {
-        return Offset(dx.toDouble(), dy.toDouble());
-      }
-    }
-    throw DogSerializerException(message: "Invalid offset value", converter: this);
+    var map = readAsMap(value, engine);
+    return Offset(map.read<double>("dx"), map.read<double>("dy"));
   }
 
   @override
@@ -43,14 +40,8 @@ class FlutterSizeConverter extends SimpleDogConverter<Size> {
 
   @override
   Size deserialize(value, DogEngine engine) {
-    if (value is Map<String, dynamic>) {
-      var width = value["width"];
-      var height = value["height"];
-      if (width is num && height is num) {
-        return Size(width.toDouble(), height.toDouble());
-      }
-    }
-    throw DogSerializerException(message: "Invalid size value", converter: this);
+    var map = readAsMap(value, engine);
+    return Size(map.read<double>("width"), map.read<double>("height"));
   }
 
   @override
@@ -65,18 +56,14 @@ class FlutterRectConverter extends SimpleDogConverter<Rect> {
 
   @override
   Rect deserialize(value, DogEngine engine) {
-    return fromValue(value);
+    final [left, top, right, bottom] = _parseDoubleTuple4(value, engine, this);
+    return Rect.fromLTRB(left, top, right, bottom);
   }
 
   @override
   serialize(Rect value, DogEngine engine) {
     return [value.left, value.top, value.right, value.bottom];
   }
-
-  static Rect fromValue(dynamic fieldValue) {
-    final [left, top, right, bottom] = _parseDoubleTuple4(fieldValue, typeName: "rect");
-    return Rect.fromLTRB(left, top, right, bottom);
-  }
 }
 
 @linkSerializer
@@ -85,18 +72,14 @@ class FlutterEdgeInsetsConverter extends SimpleDogConverter<EdgeInsets> {
 
   @override
   EdgeInsets deserialize(value, DogEngine engine) {
-    return fromValue(value);
+    final [left, top, right, bottom] = _parseDoubleTuple4(value, engine, this);
+    return EdgeInsets.fromLTRB(left, top, right, bottom);
   }
 
   @override
   serialize(EdgeInsets value, DogEngine engine) {
     return [value.left, value.top, value.right, value.bottom];
   }
-
-  static EdgeInsets fromValue(dynamic fieldValue) {
-    final [left, top, right, bottom] = _parseDoubleTuple4(fieldValue, typeName: "edge insets");
-    return EdgeInsets.fromLTRB(left, top, right, bottom);
-  }
 }
 
 @linkSerializer
@@ -130,26 +113,19 @@ class FlutterBorderRadiusConverter extends SimpleDogConverter<BorderRadius> {
 
   @override
   BorderRadius deserialize(value, DogEngine engine) {
-    return fromValue(value);
-  }
-
-  @override
-  serialize(BorderRadius value, DogEngine engine) {
-    return [value.topLeft.x, value.topRight.x, value.bottomLeft.x, value.bottomRight.x];
-  }
-
-  static BorderRadius fromValue(dynamic fieldValue) {
-    final [topLeft, topRight, bottomLeft, bottomRight] = _parseDoubleTuple4(
-      fieldValue,
-      typeName: "border radius",
-    );
+    final [topLeft, topRight, bottomLeft, bottomRight] = _parseDoubleTuple4(value, engine, this);
     return BorderRadius.only(
       topLeft: Radius.circular(topLeft),
       topRight: Radius.circular(topRight),
       bottomLeft: Radius.circular(bottomLeft),
       bottomRight: Radius.circular(bottomRight),
     );
   }
+
+  @override
+  serialize(BorderRadius value, DogEngine engine) {
+    return [value.topLeft.x, value.topRight.x, value.bottomLeft.x, value.bottomRight.x];
+  }
 }
 
 @linkSerializer
@@ -158,25 +134,30 @@ class FlutterRRectConverter extends SimpleDogConverter<RRect> {
 
   @override
   RRect deserialize(value, DogEngine engine) {
-    if (value is Map<String, dynamic>) {
-      final rect = FlutterRectConverter.fromValue(value["dimensions"]);
-      final borderRadius = FlutterBorderRadiusConverter.fromValue(value["radii"]);
-      return RRect.fromRectAndCorners(
-        rect,
-        topLeft: borderRadius.topLeft,
-        topRight: borderRadius.topRight,
-        bottomLeft: borderRadius.bottomLeft,
-        bottomRight: borderRadius.bottomRight,
-      );
-    }
-    throw DogSerializerException(message: "Invalid RRect value", converter: this);
+    var map = readAsMap(value, engine);
+    final rect = map.read<Rect>("dimensions");
+    final borderRadius = map.read<BorderRadius>("radii");
+    return RRect.fromRectAndCorners(
+      rect,
+      topLeft: borderRadius.topLeft,
+      topRight: borderRadius.topRight,
+      bottomLeft: borderRadius.bottomLeft,
+      bottomRight: borderRadius.bottomRight,
+    );
   }
 
   @override
   serialize(RRect value, DogEngine engine) {
     return <String, dynamic>{
-      "dimensions": [value.left, value.top, value.right, value.bottom],
-      "radii": [value.tlRadius.x, value.trRadius.x, value.blRadius.x, value.brRadius.x],
+      "dimensions": engine.toNative<Rect>(value.outerRect),
+      "radii": engine.toNative<BorderRadius>(
+        BorderRadius.only(
+          topLeft: value.tlRadius,
+          topRight: value.trRadius,
+          bottomLeft: value.blRadius,
+          bottomRight: value.brRadius,
+        ),
+      ),
     };
   }
 }