dson 0.15.2

  • README.md
  • Installing
  • Versions
  • 89

Build Status

DSON is a dart library which converts Dart Objects into their JSON representation.

This library was initially a fork from Dartson. Now it contains some differences:

  • Dartson uses custom transformers to convert objects to JSON. This produce faster and smaller code after dart2Js. Instead DSON uses [serializable]() and [built_mirrors]() libraries. This should produce code as fast and small as Dartson transformer.

  • DSON has the ability to serialize cyclical objects by mean of depth parameter, which allows users to specify how deep in the object graph they want to serialize.

  • DSON has the ability to exclude attributes for serialziation in two ways.

  • Using @ignore over every attribute. This make excluding attributes too global and hardcoded, so users can only specify one exclusion schema.

  • Using exclude map as parameter for toJson method. This is more flexible, since it allows to have many exclusion schemas for serialization.

  • DSON uses the annotation @serializable instead @entity which is used by Dartson.

Comparison with other libraries #


Tutorials #

DSON tutorials

Configuration #

1- Create a new dart project.

2- Add dependencies to pubspec.yaml

  dson: any # replace for latest version

3- Create/edit bin/main.dart or web/main.dart and add the code shown in any of the samples below.

4- Run either pub run build_runner build, or pub run build_runner watch, or pub run build_runner serve in the console

Convert objects to JSON strings #

To convert objects to JSON strings you only need to use the toJson function, annotate the object with @serializable and pass the object to the toJson function as parameter:

library example.object_to_json; // this line is needed for the generator

import 'package:dson/dson.dart';

part 'object_to_json.g.dart'; // this line is needed for the generator

class Person extends _$PersonSerializable {
  int id;
  String firstName;
  var lastName; //This is a dynamic attribute could be String, int, double, num, date or another type
  double height;
  DateTime dateOfBirth;

  String otherName;

  String notVisible;

  // private members are never serialized
  String _private = "name";

  String get doGetter => _private;

void main() {

  Person object = new Person()
    ..id = 1
    ..firstName = "Jhon"
    ..lastName = "Doe"
    ..height = 1.8
    ..dateOfBirth = new DateTime(1988, 4, 1, 6, 31)
    ..otherName = "Juan"
    ..notVisible = "hallo";

  String jsonString = toJson(object);
  // will print: '{"id":1,"firstName":"Jhon","lastName":"Doe","height":1.8,"dateOfBirth":"1988-04-01T06:31:00.000","renamed":"Juan","doGetter":"name"}'

Converting objects to Maps #

To convert objects to Maps you only need to use the toMap function, annotate the object with @serializable and pass the object to toMap function as parameter:


Serializing Cyclical Objects #

To serialize objects that contains Cyclical References it would be needed to use the annotation @cyclical. If this annotation is present and the depth variable is not set then the non-primitive objects are not going to be parsed and only the id (or hashmap if the object does not contains id) is going to be present. Let’s see next example:


as you can see employee has an address, and the address has an owner of type Employee. If the property id is not present in the object then it is going to take the hashcode value from the object as reference. And finally, the depth parameter passed to serialize function tells serializer how deep you want to go throw the reference. This help us not only to avoid cyclical reference, but to determine what referenced objects should be serialized.

The same applies for lists:


Without the annotation @cyclical the program is going to throw a stack overflow error caused by the serializing of cyclical objects.

Excluding attributes from being serialized #

To exclude parameter from being serialized we have two options the first option is using @ignore over the attribute to ignore. However this approach is too global. What I want to say with this is that the attribute is going to be ignored always.

Another way to exclude attributes is adding the parameter exclude to serialize function. In this way we only exclude those attributes during that serialization.


Convert JSON strings to objects #

To convert JSON strings to objects you only need to use the fromJson and fromJsonList functions and pass the json string to deserialize and the Type of the object as parameters:


Converting Maps and Lists<Map> to dart objects

Frameworks like Angular.dart come with several HTTP services which already transform the HTTP response to a map using JSON.encode. To use those encoded Maps or Lists use fromMap function.


Extend serializable Objects #

To extends objects that are going to be serializable you will need to add the comment:

// ignore: mixin_inherits_from_not_object

This is to advice the analyzer to ignore the error caused by inheriting from an object that is not a mixin. For example:


Serialize/Deserialize immutable objects #

To make an immutable class to be able to serialize/deserialize you only need to declare it with a constructor which only contains final parameters. For example:


Be sure the names of the fields and constructor parameters match. If they do not match, then the deserialized object will contain attributes with null value

Todo #

  • [ ] Add include parameter to serialize function
  • [x] Add uuid check over hashCode for cyclical references
  • [ ] Add types to serialized values
  • [ ] Add support for hal-json
  • [ ] Add support for schema-json
  • [ ] Add support for csv
  • [ ] Add support for MessagePack
  • [ ] Add support for converting to array of values-only

0.15.2 #

  • upgrade analyzer to version ^0.33.0
  • upgrade build_runner to version ^1.0.0
  • upgrade build to version ^1.0.1
  • upgrade built_mirrors_core to version ^0.10.1
  • upgrade serializable_core to version ^0.11.1
  • upgrade dson_core to version ^0.15.2

0.15.1 #

  • fix deserialize class with default constructor with optional args (fix #37).
  • deserialize immutable with wrong constructor-parameter name now is possible. However now it returns null for that parameter after deserializing instead throwing NoConstructorFound error.

0.15.0 #

  • upgrade serializable_core to version 0.11.0 since this version now generates from methods which now allows convert objects from generic values.
  • move SerializedName to built_mirrors library since the serialized name is now generated at build time

0.14.0 #

  • upgrade source_gen to version ^0.9.0
  • upgrade analyzer to version ^0.32.0
  • upgrade built_mirrors_core to version ^0.9.0
  • upgrade serializable_core to version ^0.10.0
  • upgrade build_runner to version ^0.9.0
  • upgrade test to version ^1.0.0

0.13.3 #

  • fix #34 and fix #35

0.13.2 #

  • fix error serializing immutable with optional parameters

0.13.1 #

  • upgrade source_gen to version ^0.8.0
  • add extend object sample to README

0.13.0 #

  • upgrade serializable_core to version 0.9.0 (fixes #32)

0.12.0 #

  • add dson_core package
  • upgrade build_runner to version 0.7.0
  • upgrade build to version 0.12.0

0.11.0 #

  • add caches for SerializedName and Ignored annotations
  • upgrade to serializable@0.8.0 and built_mirrors@0.7.1

0.10.2 #

  • fixes #23: The getter 'name' was called on null

0.10.1 #

  • deserialize int to double if required (fixes #22)

0.10.0 #

  • Upgrade to built_mirrors@^0.6.0 and serializable@^0.7.0

0.9.1 #

  • Add @uId annotation

0.9.0 #

  • upgrade serializable to version ^0.6.0
  • upgrade buidl_mirrors to version ^0.5.0
  • upgrade build_runner to version ^0.4.0
  • upgrade build to version ^0.10.0

0.8.0 #

  • upgrade serializable to version 0.5.0
  • add other dependencies needed

0.7.0 #

  • upgrade serializable to version 0.4.0

0.6.0 #

  • remove packageName parameter from phase and make globs parameter optional
  • upgrade serializable to version ^0.3.0

0.5.0 #

  • upgrade to new version of serializable
  • change usage of _initClassMirrors to _initMirrors

0.4.1 #

  • use latest version of serializable and built_mirrors
  • change use of BuiltMirrorsGenerator to ClassMirrorsGenerator
  • add InitClassMirrorsGenerator to phase.dart

0.4.0 #

0.3.3 #

  • Correct bug about deserializing var types
  • Add support for deserializing generic types in the browser

0.3.2 #

  • Add Set deserializer

0.3.1 #

  • Add check for double on deserializer._convertValue
  • add check if (valueType is DynamicMirrorImpl) to deserializer._convertValue to convert var or dynamic attributes

0.3.0+1 #

  • Update to reflectable 0.5.1

0.3.0 #

  • Update to reflectable 0.4.0
  • add enum support
  • rename methods:
    • serialize to toJson
    • deserialize to fromJson
    • deserializeList to fromJsonList
    • deserializeMap to fromJsonMap
    • objectToSerializable remains with the same name
    • toMap method was created
    • map to fromMap
    • mapList to fromMapList

0.2.0 #

  • Breaking change: reflectable < 0.3.0 is not supported
  • Bump reflectable support to ^0.3.0

0.1.8+1 #

  • Extend version support for reflectable package

0.1.8 #

  • Add support for deserializing Maps of objects (in values)
  • Support for excludes, depth, and fieldName when serializing Maps of objects

0.1.5 #

  • Add exclude parameter to serialize function

0.1.4 #

  • Create stack for deserializer to get objects previously deserialized from cyclical conversions.

0.1.3 #

  • Handle cyclical reference for serializing lists

0.1.2 #

  • Handle cyclical reference for serializing objects using annotation @cyclical and depth parameter to avoid cyclical reference errors and determine how deep the user wants to serialize the object.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  dson: ^0.15.2

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:dson/dson.dart';
Version Uploaded Documentation Archive
0.15.5 Mar 20, 2019 Go to the documentation of dson 0.15.5 Download dson 0.15.5 archive
0.15.4+1 Mar 20, 2019 Go to the documentation of dson 0.15.4+1 Download dson 0.15.4+1 archive
0.15.4 Mar 20, 2019 Go to the documentation of dson 0.15.4 Download dson 0.15.4 archive
0.15.3 Jan 28, 2019 Go to the documentation of dson 0.15.3 Download dson 0.15.3 archive
0.15.2+3 Jan 25, 2019 Go to the documentation of dson 0.15.2+3 Download dson 0.15.2+3 archive
0.15.2+2 Jan 25, 2019 Go to the documentation of dson 0.15.2+2 Download dson 0.15.2+2 archive
0.15.2+1 Dec 2, 2018 Go to the documentation of dson 0.15.2+1 Download dson 0.15.2+1 archive
0.15.2 Oct 17, 2018 Go to the documentation of dson 0.15.2 Download dson 0.15.2 archive
0.15.1 Aug 26, 2018 Go to the documentation of dson 0.15.1 Download dson 0.15.1 archive
0.15.0+1 Aug 7, 2018 Go to the documentation of dson 0.15.0+1 Download dson 0.15.0+1 archive

All 50 versions...

Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on May 8, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.3.0
  • pana: 0.12.15


Detected platforms: Flutter, web, other

No platform restriction found in primary library package:dson/dson.dart.

Health suggestions

Format lib/builder.dart.

Run dartfmt to format lib/builder.dart.

Format lib/dson.dart.

Run dartfmt to format lib/dson.dart.

Maintenance suggestions

The package description is too short. (-17 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Update README.md. (-2 points)

1 image link is insecure (e.g. http://img.youtube.com/vi/dZrCrCsw208/0.jpg), use https URLs instead.

Maintain an example.

None of the files in the package's example/ directory matches known example patterns.

Common filename patterns include main.dart, example.dart, and dson.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev <3.0.0
analyzer ^0.33.0 0.33.6+1 0.36.3
build ^1.0.0 1.1.0 1.1.4
built_mirrors_core ^0.10.1 0.10.1 0.10.4
dson_core ^0.15.2 0.15.2 0.15.4
logging ^0.11.0 0.11.3+2
serializable_core ^0.11.1 0.11.1 0.11.2+1
source_gen ^0.9.0 0.9.4+1 0.9.4+2
Transitive dependencies
args 1.5.1
async 2.2.0
charcode 1.1.2
collection 1.14.11
convert 2.1.1
crypto 2.0.6
csslib 0.16.0
dart_style 1.2.0 1.2.7
front_end 0.1.6+9 0.1.18
glob 1.1.7
html 0.14.0+2
kernel 0.3.6+9 0.3.18
meta 1.1.7
package_config 1.0.5
path 1.6.2
plugin 0.2.0+3
pub_semver 1.4.2
source_span 1.5.5
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
watcher 0.9.7+10
yaml 2.1.15
Dev dependencies
build_runner ^1.0.0
build_test any
test ^1.0.0