dart_mappable

You can serialize and deserialize objects without knowing their static types by using a special __type key in the JSON data. This is known as typeless serialization.

Deserialization

If the JSON contains a "__type": "ClassName" key, MapperContainer.globals.fromJson(json) will return the correct instance type even if the static type is dynamic.

Serialization

To include the __type indicator in your output, use MapperContainer.globals.toValue<T>(T value), toMap, or toJson. The __type property is added when the static type T differs from the runtime type of the value being encoded (e.g., when encoding a specific instance as dynamic).

// Typeless Deserialization
void main() {
  initializeMappers(); // Generated via @MappableLib
  
  var json = '{"__type": "Person", "name": "Bob"}';
  dynamic object = MapperContainer.globals.fromJson(json);
  
  assert(object.runtimeType == Person);
}

// Typeless Serialization (adding __type)
void main() {
  initializeMappers();
  var myClassInstance = Person(name: 'Bob');

  // Adding '__type' by using dynamic as the static type
  var json = MapperContainer.globals.toJson<dynamic>(myClassInstance);
  
  // Resulting JSON will include: {"__type": "Person", ...}
}

Instead of complex configuration, dart_mappable uses constructor arguments to handle advanced use cases. The library analyzes constructor arguments rather than class fields. This allows you to:

• Provide default values: Use standard Dart default parameters.
• Rename fields: Map a constructor argument to a different field name.
• Ignore fields: Simply omit a field from a specific constructor.
• Compute values: Assign values to fields based on constructor arguments.

Warning for Computed Values: If you use a constructor to compute a field (e.g., combining firstName and lastName into name), you must provide matching getters for the original arguments (e.g., get firstName => ...) to ensure successful deserialization back to the original state.

@MappableClass()
class Person with PersonMappable {
  String name;
  int age;
    
  Person.base(this.name, this.age);
  
  Person.opt(this.name, [this.age = 18]);

  Person.renamed(this.name, int years) : age = years;
  
  Person.ignored(this.name);
 
  Person.computed(String firstName, String lastName, this.age) 
      : name = '$firstName $lastName';

  // Required for correct deserialization
  String get firstName => name.split(' ')[0];
  String get lastName => name.split(' ')[1];
}

When working with polymorphic types, you may encounter JSON where the discriminator is either null or contains an unrecognized value. dart_mappable provides two ways to handle these cases:

1. Handling null values: To map a null discriminator to a specific subclass, set the discriminatorValue of that subclass to null in the @MappableClass annotation.
2. Handling unknown values (Fallback): To provide a fallback class for any unrecognized discriminator value, set the discriminatorValue of the fallback class to MappableClass.useAsDefault.

Example

// This sub-class will be chosen when the discriminator is null.
@MappableClass(discriminatorValue: null)
class NullAnimal extends Animal with NullAnimalMappable {
  NullAnimal(String name) : super(name);
}

// This sub-class will be chosen on any unknown discriminator.
@MappableClass(discriminatorValue: MappableClass.useAsDefault)
class DefaultAnimal extends Animal with DefaultAnimalMappable {
  String type;
  DefaultAnimal(String name, this.type) : super(name);
}

void main() {
  // Decodes to NullAnimal
  Animal animal1 = AnimalMapper.fromJson('{"name": "Scar", "type": null}');
  
  // Decodes to DefaultAnimal because "Bear" is unknown
  Animal animal2 = AnimalMapper.fromJson('{"name": "Balu", "type": "Bear"}');
  print(animal2.type); // Bear
}

@MappableClass(discriminatorValue: null)
class NullAnimal extends Animal with NullAnimalMappable { ... }

@MappableClass(discriminatorValue: MappableClass.useAsDefault)
class DefaultAnimal extends Animal with DefaultAnimalMappable { ... }

Hooks allow you to inspect and modify values during the encoding or decoding process for an entire class or a specific field.

To implement a hook, extend the MappingHook class and override one or more of the following methods:

• Object? beforeDecode(Object? value): Modify the raw input before decoding begins.
• Object? afterDecode(Object? value): Modify the object after decoding is complete.
• Object? beforeEncode(Object? value): Modify the object before it is encoded.
• Object? afterEncode(Object? value): Modify the encoded value after encoding is complete.

Important Behavior:

• If beforeDecode returns an instance of the target type, the standard decoding logic is skipped.
• If beforeEncode returns a value, the standard encoding logic is skipped.
• Inheritance: Class-hooks are inherited by subclasses. When both superclass and subclass define class-hooks, they are applied in this order: super.beforeDecode $\rightarrow$ sub.beforeDecode $\rightarrow$ decode $\rightarrow$ sub.afterDecode $\rightarrow$ super.afterDecode.
• Field-hooks: For field-level hooks, only the subclass hook is applied; they are not chained like class-hooks.

class GameHook extends MappingHook {
  const GameHook();

  @override
  Object? beforeDecode(Object? value) {
    // logic here
    return value;
  }
}

@MappableClass(hook: GameHook())
class Game {
  @MappableField(hook: PlayerHook())
  Player player;

  Game(this.player);
}