• Bump analyzer to >=13.0.0 <14.0.0

• Bump analyzer to >=10.0.0 <13.0.0.

4.7.0

• Allow analyzer 10.0.0.
• Add useNodoc option for excluding generated classes from dartdoc output.
• Fix type signature of nested copyWith parameters in some cases.

• Fix nested copyWith on a inherited class with the superclass and field type in another library.
• Fix default value of a field not being prefixed correctly when set to a static constant.
• Add ignore for invalid_use_of_protected_member warning in generated code.

• Added support for annotated enum typedefs.

• Allow analyzer 9.0.0.

• Record mappers now correctly uses hooks specified on the @MappableRecord annotation.
• Nested records are now correctly initialized, and record mappers are included in the generated initializeMappers() method.
• Getters are no longer falsely used in equality or stringify methods.
• Bump analyzerto ^8.0.0, and build and source_gen to ^4.0.0.

• Migrate to new element2 analyzer model. Bump analyzer to >=7.5.9, build to 3.0.0 and source_gen to 3.0.0.
• Added support for self-referencing generics (e.g. T extends Comparable<T>)
• Fix handling of nullable function fields.
• Disable formatting of generated files through // dart format off.
• Require sdk: >=3.7.0.

• Added support for shallowEncoding and includeTypeId options of @MappableClass().
• Fixed escaping of enum values.
• Fixed copyWith method for unbounded and nullable-bounded generic types.
• Fixed bug when using top-level variables as hooks.

• Update analyzer to >=7.0.0 <8.0.0 and source_gen to ^2.0.0. Bump other dependencies accordingly.
• Require sdk: >=3.6.0.

• Fixed bug with bounded generic deep copyWith parameters.

• Added support for reusing annotations as constant variables.
• Fixed generation for generic functions.
• Fixed bug with nullable generic field.
• Fixed bug with import path on windows.

• Added lint ignores for 'override_on_non_overriding_member'.

• Fixed issues with adding unnecessary '__type' property for nullable generics.
• Improved serialization consistency and equality handling.

• Performance improvements.

• Added custom typedef for mapping fields to resolve naming conflict.
• Deprecated creating and linking custom MapperContainers. If you are affected by this see https://github.com/schultek/dart_mappable/issues/159.

• Added support for shallow encoding a class:
  • MyClassMapper.ensureInitialized().encodeMap<MyClass>(myClass, EncodingOptions(shallow: true))
• Correctly escape $ in class names.
• Added option to use unordered list equality with iterables:
  • IterableMapper.equalityMode = IterableEqualityMode.unordered
• Added build_extensions option to builder configuration.

• Added support for generic typed parameters for deep copyWith.
• Added lint ignores for 'unnecessary_cast', 'strict_raw_type' and 'inference_failure_on_untyped_parameter'.

Changelog

• Require sdk: >=3.0.0.

• Added support for Records.

  • Fields of a class can now be any record type.

  • You can annotate toplevel record typedefs:

      @MappableRecord()
      typedef Coordinates = ({double latitude, double longitude});

Documentation

Record Fields

dart_mappable supports record fields out of the box.
When you define a class, any field using a record type will be automatically included in the serialization.

@MappableClass()
class Location with LocationMappable {
  
  const Location({
    required this.name,
    required this.coordinates, 
  });

  final (String, String) name;
  final ({double lat, double lng}) coordinates;
}

An instance of this class would be encoded to:

{
  "name": {
    "$1": "John",
    "$2": "Doe"
  },
  "coordinates": {
    "lat": 123,
    "lng": 456
  }
}

Record Aliases

Additionally, you can create record type aliases using annotated typedefs:

@MappableRecord()
typedef Coordinates = ({double lat, double lng});

When using this type for a field of another class, it will be serialized as expected.

This also allows you to serialize records using the standalone generated mapper class as well as the generated extension methods:

void main() {
  // Using the generated mapper class.
  Coordinates coords  = CoordinatesMapper.fromJson('{"lat": 123, "lng": 456}');
  
  // Using the generated extension methods.
  String json = coords.toJson();
}

Renaming Record Properties

You can also annotate individual fields of a record alias to change the key or add a hook:

@MappableRecord()
typedef FullName = (@MappableField(key: 'firstName') String, @MappableField(hook: MyHook()) String);

This will only work on annotated record type aliases, not inline record fields.

Note: Since typedefs are just an alias for a type, you cannot define two aliases for the same type
with different @MappableField() modifiers. Only one will be used for serialization.

• Require sdk: >=3.0.0.

• Added support for Records.

  • Fields of a class can now be any record type.

  • You can annotate toplevel record typedefs:

      @MappableRecord()
      typedef Coordinates = ({double latitude, double longitude});
    

  For a more detailed usage see the documentation.

• Make enum encoding explicitly typed.
• Update analyzer to '>=5.11.0 <7.0.0'

• Respect keys and hooks for annotated getters.

• Handle even more cases for generic subclassing.

• Handle bounded nested type parameters in subclasses.

• Added support for annotating getters with @MappableField, which will then be included in the encoding, equality checks, and stringification of that class.

• Fixed bug with broken mapper generation.

Changelog

• The builder now respects basic initializer expressions of a constructor. This makes it
  possible to do field renaming or assigning to private fields without requiring an additional
  getter matching the parameter.

  The following is now supported out of the box:

  class MyClass {
    MyClass(int value, {String? name}) 
        // Effectively renaming 'value' to 'data'.
      : data = value,
        // Assigning to a private field + having a null fallback.
        _name = name ?? 'Unnamed';
  
    final int value;
    final String _name;

• Fixed encoding of a map now returns a Map<String, dynamic> where possible
  (instead of a Map<dynamic, dynamic>)

• Fixed supporting expressions in @MappableClass.includeCustomMappers.

• Fixed error when using non-literal values in @MappableValue().

• Fixed generic decoding when using generic superclass.

• Fixed unknown-type bug for serialized non-constructor fields.

• Fixed bug with undetermined includeSubClasses.

• Fixed supporting expressions in @MappableClass.includeCustomMappers.

• Fixed error when using non-literal values in @MappableValue().

• The builder now respects basic initializer expressions of a constructor. This makes it possible to do field renaming or assigning to private fields without requiring an additional getter matching the parameter.

  The following is now supported out of the box:

  class MyClass {
    MyClass(int value, {String? name}) 
        // Effectively renaming 'value' to 'data'.
      : data = value,
        // Assigning to a private field + having a null fallback.
        _name = name ?? 'Unnamed';
  
    final int value;
    final String _name;
  

• Fixed encoding of a map now returns a Map<String, dynamic> where possible (instead of a Map<dynamic, dynamic>)

• Fixed generic decoding when using generic superclass.
• Fixed unknown-type bug for serialized non-constructor fields.

• Fixed bug with undetermined includeSubClasses.

Changelog

• Breaking: Generated mappers no longer have a .container property. This was removed in favor
  of the new MapperContainer.globals container.

  // Instead of this:
  var value = MyClassMapper.container.fromValue(...);
  // Do this:
  var value = MapperContainer.globals.fromValue(...);

  Mapper initialization and usage is now simplified to the following:

  1. When used explicitly (e.g. through MyClassMapper.fromMap or myClass.toMap()) no additional
     initialization is needed.
  2. When used implicitly (through a generic type e.g. MapperContainer.globals.fromMap<MyClass>()) the
     mapper needs to be initialized once before being used with MyClassMapper.ensureInitialized().

• Breaking: Changed internal mapper implementation which causes any custom mapper to break.

  • Removed MapperElementBase class.
  • Added MappingContext being passed to mapper methods.

  See docs on how to use custom mappers in v3.

• Breaking: Removed @MappableLib.createCombinedContainer in favor of @MappableLib.generateInitializerForScope.

  Instead of generating a new container, v3 generates an initialization function for all mappers. Use it early on in your
  application:

  @MappableLib(generateInitializerForScope: InitializerScope.package)
  library main;
  
  import 'main.init.dart';
  
  void main() {
    initializeMappers();
    ...
  }

• Breaking: Improved support and features for .copyWith.

  • Copy-With now supports classes that implement multiple interfaces.
  • Renamed .copyWith.apply() method to .copyWith.$update().
  • Added .copyWith.$merge() and .copyWith.$delta().

  You can now use .copyWith with either an existing instance using .$merge or a map of values using .$delta.

  @MappableClass()
  class A with AMappable {
    A(this.a, this.b);
    
    int? a;
    int? b;
  }
  
  void main() {
    var a = A(1, null);
    
    var c = a.copyWith.$merge(A(null, 2));
    assert(c == A(1, 2));
  
    var d = a.copyWith.$delta({'b': 2});
    assert(d == A(1, 2));
  }

• Breaking: Removed CheckTypesHook in favor of discriminator functions.

  You can now use a custom predicate function as the discriminatorValue of a class. This function can check
  whether the encoded value should be decoded to this subclass and return a boolean.

  @MappableClass()
  abstract class A with AMappable {
    A();
  }
  
  @MappableClass(discriminatorValue: B.checkType)
  class B extends A with BMappable {
    B();
    
    /// checks if [value] should be decoded to [B]
    static bool checkType(value) {
      return value is Map && value['isB'] == true;
    }
  }
  
  @MappableClass(discriminatorValue: C.checkType)
  class C extends A with CMappable {
    C();
    
    /// checks if [value] should be decoded to [C]
    static bool checkType(value) {
      return value is Map && value['isWhat'] == 'C';
    }
  }

• Added support for serializing fields that are not part of the constructor
  when annotated with @MappableField().

• Added EncodingOptions to toValue method.

• Added support for third-party models by using annotated typedefs.

• Added renameMethods to build options.

• Improved performance of generated encoding and decoding methods.

For a detailed migration guide, see this issue.

• Breaking: Generated mappers no longer have a .container property. This was removed in favor of the new MapperContainer.globals container.

  // Instead of this:
  var value = MyClassMapper.container.fromValue(...);
  // Do this:
  var value = MapperContainer.globals.fromValue(...);
  

  Mapper initialization and usage is now simplified to the following:

  1. When used explicitly (e.g. through MyClassMapper.fromMap or myClass.toMap()) no additional initialization is needed.
  2. When used implicitly (through a generic type e.g. MapperContainer.globals.fromMap<MyClass>()) the mapper needs to be initialized once before being used with MyClassMapper.ensureInitialized().

• Breaking: Changed internal mapper implementation which causes any custom mapper to break.

  • Removed MapperElementBase class.
  • Added MappingContext being passed to mapper methods.

  See docs on how to use custom mappers in v3.

• Breaking: Removed @MappableLib.createCombinedContainer in favor of @MappableLib.generateInitializerForScope.

  Instead of generating a new container, v3 generates an initialization function for all mappers. Use it early on in your application:

  @MappableLib(generateInitializerForScope: InitializerScope.package)
  library main;
  
  import 'main.init.dart';
  
  void main() {
    initializeMappers();
    ...
  }
  

• Breaking: Improved support and features for .copyWith.

  • Copy-With now supports classes that implement multiple interfaces.
  • Renamed .copyWith.apply() method to .copyWith.$update().
  • Added .copyWith.$merge() and .copyWith.$delta().

  You can now use .copyWith with either an existing instance using .$merge or a map of values using .$delta.

  @MappableClass()
  class A with AMappable {
    A(this.a, this.b);
    
    int? a;
    int? b;
  }
  
  void main() {
    var a = A(1, null);
    
    var c = a.copyWith.$merge(A(null, 2));
    assert(c == A(1, 2));
  
    var d = a.copyWith.$delta({'b': 2});
    assert(d == A(1, 2));
  }
  

• Breaking: Removed CheckTypesHook in favor of discriminator functions.

  You can now use a custom predicate function as the discriminatorValue of a class. This function can check whether the encoded value should be decoded to this subclass and return a boolean.

  @MappableClass()
  abstract class A with AMappable {
    A();
  }
  
  @MappableClass(discriminatorValue: B.checkType)
  class B extends A with BMappable {
    B();
    
    /// checks if [value] should be decoded to [B]
    static bool checkType(value) {
      return value is Map && value['isB'] == true;
    }
  }
  
  @MappableClass(discriminatorValue: C.checkType)
  class C extends A with CMappable {
    C();
    
    /// checks if [value] should be decoded to [C]
    static bool checkType(value) {
      return value is Map && value['isWhat'] == 'C';
    }
  }
  

• Added support for serializing fields that are not part of the constructor when annotated with @MappableField().

• Added EncodingOptions to toValue method.

• Added support for third-party models by using annotated typedefs.

• Added renameMethods to build options.

• Improved performance of generated encoding and decoding methods.

For a detailed migration guide, see this issue.

• Fixed an analysis error when using core interfaces.

• Fixed generated container for private libraries.

• Mappers are now generated for each file containing annotated classes. This removes the
  need to specify entry points in the build.yaml.

  This is now similar to how packages like json_serializable or freezed generate code.

  • Generated files are now part files and need to be included as such.
  • All annotated classes must now use their respective <MyClass>Mappable mixin.
  • Instead of one global Mapper each class has its own <ClassName>Mapper.
    • A new global container that includes all models can now be generated using
      @MappableLib(createCombinedContainer: true).
  • Mappers can be linked together to enable working with multiple classes.
  • Removed @CustomMapper annotation in favor of includeCustomMappers property on @MappableClass().

  For a detailed migration guide, see this issue.

• Documentation is now separated from the README using the official pub.dev documentation topics.
  Find the new documentation here

• Improvements in performance and support for generics and inheritance.

• Added the [CheckTypesHook] to allow for custom discriminator checks on subclasses in a
  polymorphic class structure.

• CopyWith is now more powerful and also works for generic or polymorphic classes, while being
  completely type-safe.

  When called on a superclass, the concrete subtype will be retained through a
  .copyWith call, which also respects generics:

    // with `class A` and `class B<T> extends A`
    A a = B<int>(); // static type A, dynamic type B<int>
  
    // signature will be `A copyWith()`, so static type A
    A a2 = a.copyWith(); 
  
    // this will still resolve to a dynamic type of B<int>
    assert(a2 is B<int>);

  For more checkout the docs
  or example

• Mappers are now generated for each file containing annotated classes. This removes the need to specify entry points in the build.yaml.

  This is now similar to how packages like json_serializable or freezed generate code.

  • Generated files are now part files and need to be included as such.
  • All annotated classes must now use their respective <MyClass>Mappable mixin.
  • Instead of one global Mapper each class has its own <ClassName>Mapper.
    • A new global container that includes all models can now be generated using @MappableLib(createCombinedContainer: true).
  • Mappers can be linked together to enable working with multiple classes.
  • Removed @CustomMapper annotation in favor of includeCustomMappers property on @MappableClass().

  For a detailed migration guide, see this issue.

• Documentation is now separated from the README using the official pub.dev documentation topics. Find the new documentation here

• Improvements in performance and support for generics and inheritance.

• Added the [CheckTypesHook] to allow for custom discriminator checks on subclasses in a polymorphic class structure.

• CopyWith is now more powerful and also works for generic or polymorphic classes, while being completely type-safe.

  When called on a superclass, the concrete subtype will be retained through a .copyWith call, which also respects generics:

    // with `class A` and `class B<T> extends A`
    A a = B<int>(); // static type A, dynamic type B<int>
  
    // signature will be `A copyWith()`, so static type A
    A a2 = a.copyWith(); 
  
    // this will still resolve to a dynamic type of B<int>
    assert(a2 is B<int>);
  

  For more checkout the docs or example

• Added support for 2.17 super parameters

• Fixed import paths on windows

• Improved Readme for constructor utilization
• Fixed missing imports for custom hooks