json_god 1.0.1

JSON God #

version 1.0.0

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:

@thosakwe or @regios_tech

Use this package as a library

1. Depend on it

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


dependencies:
  json_god: ^1.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

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

3. Import it

Now in your Dart code, you can use:


import 'package:json_god/json_god.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
24
Health:
Code health derived from static analysis. [more]
--
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
--
Overall:
Weighted score of the above. [more]
12
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Support Dart 2 in pubspec.yaml.

The SDK constraint in pubspec.yaml doesn't allow the Dart 2.0.0 release. For information about upgrading it to be Dart 2 compatible, please see https://dart.dev/dart-2#migration.

Maintenance issues and suggestions

Make sure dartdoc successfully runs on your package's source files. (-10 points)

Dependencies were not resolved.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.0.0

Admin