json_god 1.0.1
Easy JSON serialization and deserialization in Dart.
JSON God
The definitive solution for JSON in Dart.
Contents
About
I think Dart is really freaking cool, and far better than Javascript. However, coming from a Javascript background, I really am not a fan of native JSON support only coming in the form of Maps. What about classes? What if I want to serialize my precious objects? What if I want to validate JSON input?
My main problem with Dart is that it does not natively support this. And the standard JsonObject Library is outdated and incompatible with SDK 1.0+.
To remedy this, I wrote JSON God. JSON God exposes a class called God. God contains just two methods: serialize and deserialize. You can call these synchronously, and even in the browser. Cool, right?
I made a few provisions for compatibility with JsonObject, too.
Bow down to JSON God.
Installation
To install JSON God for your Dart project, simply add json_god to your pub dependencies. If you use an old version of the SDK (<1.0), stick with JsonObject.
dependencies:
json_god: ^1.0.0
Usage
Serialization and deserialization are run through the God class. Instantiate a new
God to begin.
import 'package:json_god/json_god.dart';
God god = new God();
// Set .debug to true to print debug output.
// CAUTION: It is very verbose.
// god.debug = true;
Dart2JS Compatibility
IMPORTANT - Reflection through dart:mirrors is not yet perfect in Dart2JS. Make sure
to add a @MirrorsUsed() annotation to any classes you want to serialize/deserialize.
library app;
@MirrorsUsed(targets: 'app')
import 'dart:mirrors';
@MirrorsUsed documentation can be found here.
Serializing JSON
Simply call god.serialize(x) to synchronously transform an object into a JSON
string.
Map map = {"foo": "bar", "numbers": [1, 2, {"three": 4}]};
// Output: {"foo":"bar","numbers":[1,2,{"three":4]"}
String json = god.serialize(map);
print(json);
You can easily serialize classes, too. JSON God also supports classes as members.
class A {
String foo;
A(this.foo);
}
class B {
String hello;
A nested;
B(String hello, String foo) {
this.hello = hello;
this.nested = new A(foo);
}
}
main() {
God god = new God();
print(god.serialize(new B("world", "bar")));
}
// Output: {"hello":"world","nested":{"foo":"bar"}}
Deserializing JSON
Deserialization is equally easy, and is provided through god.deserialize.
Map map = god.deserialize('{"hello":"world"}');
int three = god.deserialize("3");
Deserializing to Classes
JSON God lets you deserialize JSON into an instance of any type. Simply pass the
type as the second argument to god.deserialize.
class Child {
String foo;
}
class Parent {
String hello;
Child child = new Child();
}
main() {
God god = new God();
Parent parent = god.deserialize('{"hello":"world","child":{"foo":"bar"}}', Parent);
print(parent);
}
Any JSON-deserializable classes must initializable without parameters.
If new Foo() would throw an error, then you can't use Foo with JSON.
This allows for validation of a sort, as only fields you have declared will be accepted.
class HasAnInt { int theInt; }
HasAnInt invalid = god.deserialize('["some invalid input"]', HasAnInt);
// Throws an error
Compatiblity with JsonObject
As mentioned before, there is some compatibility with JsonObject for projects that already use that library.
objectToJson
JsonObject, as I said before, is old, and uses the older Future API. It exposes
a Future<String> called objectToJson that serializes an object. I felt like this
was worth keeping, so I kept it.
main() async {
Map map = {"hello": "world"};
// Using await
String json = await objectToJson(map);
// Using Future.then
objectToJson(map).then(print);
}
It's marked as deprecated, because with JSON God you really should just stick with
god.serialize.
enableJsonObjectDebugMessages
This boolean flag is used internally by the God class, and is the equivalent of
god.debug.
Thank you for using JSON God
Thank you for using this library. I hope you like it.
Feel free to follow me on Twitter: