dart_json_mapper 0.1.0

This package allows programmers to annotate Dart classes in order to serialize / deserialize them from / to JSON.

dart-json-mapper

Serialize / Deserialize Dart Objects to / from JSON

This package allows programmers to annotate Dart classes in order to serialize / deserialize them from / to JSON.

Basic setup

Library has NO dependency on dart:mirrors, one of the reasons is described here.

Dart classes reflection mechanism is based on reflectable library. This means "extended types information" is auto-generated out of existing Dart program guided by the annotated classes only, as the result types information is accesible at runtime, at a reduced cost.

Say, you have a dart program main.dart having some classes intended to be traveling to JSON and back.

• First thing you should do is to put @jsonSerializable annotation on each of those classes
• Next step is to auto generate main.reflectable.dart file. And afterwards import that file into main.dart

lib/main.dart

import 'package:dart_json_mapper/annotations.dart';
import 'package:dart_json_mapper/json_mapper.dart';

import 'main.reflectable.dart'; // Import generated code.

@jsonSerializable // This annotation let instances of MyData traveling to/from JSON
class MyData {
  int a = 123;

  @JsonProperty(ignore: true)
  bool b;

  @JsonProperty(name: 'd')
  String c;

  // Important! Constructor must not have any required parameters.
  MyData([this.a, this.b, this.c]);
}

main() {
  initializeReflectable(); // Imported from main.reflectable.dart
  
  print(JsonMapper.serialize(new MyData(456, true, "yes")));
  // { 
  //  "a": 456,
  //  "d": "yes"
  // }
}

Now run the code generation step with the root of your package as the current directory:

> pub run dart_json_mapper:build lib/main.dart

where lib/main.dart should be replaced by the root library of the program for which you wish to generate code. You can generate code for several programs in one step; for instance, to generate code for a set of test files in test, this would typically be pub run dart_json_mapper:build test/*_test.dart. You'll need to re-run code generation each time you are making changes to lib/main.dart So for development time, use watch like this

> pub run dart_json_mapper:watch lib/main.dart

Each time you modify your project code, all *.reflectable.dart files will be updated as well.

• Next step is to add "*.reflectable.dart" to your .gitignore
• This is it, basic setup is done.

Example

  enum Color { Red, Blue, Green, Brown, Yellow, Black, White }
  
  @jsonSerializable
  class Car {
    @JsonProperty(name: 'modelName')
    String model;
  
    @JsonProperty(enumValues: Color.values)
    Color color;
  
    @JsonProperty(type: Car)
    Car replacement;
  
    Car([this.model, this.color]);
  }
  
  @jsonSerializable
  class Immutable {
    final int id;
    final String name;
    final Car car;
  
    Immutable({this.id, this.name, this.car});
  }
  
  print(
      JsonMapper.serialize(
        new Immutable(id: 1, name: 'Bob', car: new Car('Audi', Color.Green))
      )
  );

Output:

        {
         "id": 1,
         "name": "Bob",
         "car": {
          "modelName": "Audi",
          "color": "Color.Green",
          "replacement": null
         }
        }

Why is this library exists?

When there are so many alternatives out there

It would be nice to have a Json serialization/deserialization library

• Compatible with all Dart platforms, including Flutter and Web platforms.
• No need to extend target classes from any mixins/base/abstract classes to keep code cleaner
• Clean and simple setup, transparent and straightforward usage with no heavy maintanance involved
• No extra boilerplate code involved
• Custom converters support per each target class field

But, as of today we have...

Name	Web + Flutter support	Concerns
json_object_lite	yes	Target class has to be inherited from JsonObjectLite + boilerplate code
jaguar_serializer	yes	Tons of boilerplate, personal serializer generated per each target class, unnecessary abstraction - "model"
nomirrorsmap	yes	Cumbersome usage
dson_core	no
dson	yes	Requires target class to be inherited from mixin + too much different unobvious annotations, like @ignore, @cyclical, @uid, etc
dartson	no
json_god	no
jaguar_json	no
serializer_generator	no
dynamo	yes	Produces JSON output with type information injected in it
serialization	yes	Cumbersome configuration and setup, will require continuous maintenance
serializable	yes	Requires target class to be inherited from mixin, no custom logic allowed
json_annotation	yes	Depends on json_serializable which is not compatible with Flutter
json_serializable	no
json_mapper	no
built_value	yes	Over engineered solution, boilerplate, yes it's auto generated, but it is still boilerplate! enforces Immutability for all models, imply own patterns on your code base, too much responsibility in one library

Feature requests and bug reports

Please file feature requests and bugs using the github issue tracker for this repository.