dartson 1.0.0-alpha+3

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 90

dartson #

Pub Version Build Status Coverage Status

Dartson 1.0.0 is currently in alpha. The public API might be subject to change. For further details of potential breaks and a roadmap take a look at project 1.0.0.

Dartson is a dart library which converts Dart Objects into their JSON representation. It helps you keep your code clean of fromJSON and toJSON functions by providing a builder which generates the serialization methods.

Usage #

Add the following lines to your pubspec.yaml in order to use dartson:

dependencies:
  dartson: ^1.0.0-alpha+2
  
dev_dependencies:
  build_runner: ^0.10.0

Dartson is using a central serializer instead of serializers for each object, therefore create a central file which refers the objects that need to be serialized:

import 'package:dartson/dartson.dart';
import 'package:some_dependency/some_class.dart';

import 'my_class.dart';

@Serializer(
  entities: [
    MyClass,
    SomeClass,
  ],
)
final Dartson<Map<String, dynamic>> serializer = _serializer$dartson;

Dartson encodes and decodes into a serializable Map (Map<String, dynamic>) by default. In order to encode and decode into a json string (in previous versions done by using Dartson.JSON) directly, call the useCodec method on the generated Dartson instance, which creates a new instance using the provided codec.

import 'dart:convert';

import 'package:dartson/dartson.dart';
import 'package:some_dependency/some_class.dart';

import 'my_class.dart';

@Serializer(
  entities: [
    MyClass,
    SomeClass,
  ],
)
final Dartson<String> serializer = _serializer$dartson.useCodec(json);

Private properties #

It's not possible to encode / decode private properties. To set private properties, expose these within the constructor and provide a getter for encoding the entity.

Encoding / decoding lists #

As of dartson >1.0.0 there are specific encodeList and decodeList methods. Because of type restrictions encodeList returns an Object and decodeList expects an Object. This should not cause any further actions when using json codec, however when working with the default serializer without any Codec, than a cast to List<Map<String, dynamic>> might be necessary when using the encodeList result.

main() {
  final result = serializer.encodeList([
	MyClass()..name = 'test1',
	MyClass()..name = 'test2',
  ]) as List<Map<String, dynamic>>;

  expect(result, allOf(isList, hasLength(2)));
  expect(result[0]['name'], 'test1');
  expect(result[1]['name'], 'test2');
}

Replacing entities #

Sometimes entities are automatically generated and as such cannot contain any handwritten code, which could provide further logic and reduce complexity. This is where the replacement feature of dartson can help.

Here an example of an entity called Money which is replaced using MoneyImpl for replacing the operators.

import 'package:dartson/dartson.dart';
import 'package:dartson/transformers/date_time.dart';

// Imagine Money and Product couldn't be touched.
class Money {
  double net;
  double gross;
}

class Product {
  Money price;
  String name;
}


class MoneyImpl extends Money {
  operator +(dynamic ob) {
    if (obj is! Money) {
      throw TypeError();
    }
    
    net += ob.net;
    gross += ob.gross;
  }
}


@Serializer(
  entities: [
    Money,
    Product,
  ],
  replacements: {
    Money: MoneyImpl,
  },
  transformers: [
    DateTimeParser,
  ],
)
final Dartson serializer = _serializer$dartson;

Extending the serializer #

Dartson supports extending serializers to provide a module approach. This is necessary to support functionality like deferred loading. This also may improve build times, so when changing an entity only a part of the serializer is regenerated.

serializer_init.dart

import 'dart:convert';

import 'package:dartson/dartson.dart';
import 'package:some_dependency/some_class.dart';

import 'my_class.dart';

@Serializer(
  entities: [
    MyClass,
    SomeClass,
  ],
)
final Dartson<String> serializer = _serializer$dartson.useCodec(json);

serializer_second.dart

import 'package:dartson/dartson.dart';

import 'other_class.dart';
import 'serializer_init.dart' as fs;

@Serializer(
  entities: [
    OtherClass,
  ],
)
final Dartson<String> serializer = fs.serializer.extend(_serializer$dartson);

Notice that extend provides a completely new instance of Dartson. Also the entities provided by the serializer on which extend was called can be overwritten by the entities used in the serializer passed as the argument (in this case: _serializer$dartson entities may overwrite fs.serializer entities).

Writting custom TypeTransformers #

Transformers are used to encode / decode none serializable types that shouldn't be treated as objects / lists (for example DateTime).


/// A simple DateTime transformer which uses the toString() method.
class DateTimeParser implements TypeTransformer<String, DateTime> {
  // Make sure to add a constant constructor, because dartson will initiate all tranformers
  // as constant to improve dart2js compilation.
  const DateTimeParser();
  DateTime decode(String value) => DateTime.parse(value);
  String encode(DateTime value) => value.toString();
}

In order to use the TypeTransformer you need to register the transformer for the serializer:

import 'package:dartson/dartson.dart';
import 'package:dartson/transformers/date_time.dart';

import 'my_class.dart';

@Serializer(
  entities: [
    MyClass,
  ],
  transformers: [
    DateTimeParser,
  ],
)
final Dartson serializer = _serializer$dartson;

Roadmap for 1.0.0 alpha/beta #

  • First alpha release evaluates and tests the reuse of json_serializable (refactorings during the alpha/beta will be necessary)
  • Additional functionality from proposals will be ported
  • Looking for feedback in regards of usability from users
  • Further benchmarking of potential bottlenecks because of single point of
    the builder

Further features planned #

  • See doc/proposal for general features
  • Add tool to generate serializer.dart based on serializer.decode<T>() and serializer.encode(T) usage
  • Add analyzer plugin to detect potential issues of used entities which are not present in the serializer definition

Changelog #

1.0.0-alpha+3 (09/20/2018) #

  • Add support for final properties
  • Add support to skip private properties
  • Add support for constructor arguments
  • Add support for getters

Breaking changes

  • DateTimeParser is deprecated. The default is now the json_serializable implementation and it's no longer necessary to register a transformer at all.
  • Generator no longer create _Dartson$impl class instance and instead calls Dartson constructor directly

1.0.0-alpha+2 (09/17/2018) #

  • Add replacement functionality
  • Add encodeList and decodeList for de/serializing lists directly
  • Fix #51 by adding latest version constrain

1.0.0-alpha+1 (09/10/2018) #

  • Add extend method to Dartson to extend a serializer
  • Fix bug where codec is always set to null

Breaking changes

  • Codec usage is now different, please see README.md
  • DartsonEntityNotExistsException renamed to UnknownEntityException
  • NoDeserializeMethodOnTypeTransformer renamed to MissingDecodeMethodException
  • NoSerializeMethodOnTypeTransformer renamed to MissingEncodeMethodException

1.0.0-alpha (09/06/2018) #

  • Support dart 2.0 with build_runner
  • Add enum support (thanks to json_serializable)

Breaking changes

  • @Entity is deprecated and ignored
  • See README.md for how to use dartson 1.0.0
  • Reflection implementation is currently not supported (still under evaluation if it will be supported in the future)

0.2.6 (10/05/2015) #

  • Bump dependency versions in pubspec

0.2.4 (7/04/2015) #

  • Support for "double" types
  • Update of source_spans dependency

0.2.3 (5/25/2015) #

  • Updated analyzer and test dependency (thanks to @rightisleft)

0.2.1 (2/10/2015) #

  • Changed the default DateTime serialized format to ISO 8601 with Z notation.

0.2.0 (1/29/2015) #

  • Added a transformer that generates static serialization rules and does not use mirrors.
  • Breaking changes:
    • You now have to instantiate a Dartson instance instead of relying on global functions.
    • You now add custom transformer to the Dartson instance instead of adding them globally.

0.1.6 (6/05/2014) #

  • Added dartson.fill function
  • Compatible to dart 1.4+

0.1.5 (3/14/2014) #

  • Added dartson.TypeTransformer see README.md
  • Added package:dartson/default_transformers.dart

0.1.4 #

  • Fixed @MirrorsUsed annotations
  • Added map and mapList functions to use an already parsed map

example/lib/example.dart

import 'serializer.dart';

void main() {
  print(serializer.encode(MyClass()..name = 'test'));
  print(serializer.decode<MyClass>('{"name":"test"}').name);
}

Use this package as a library

1. Depend on it

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


dependencies:
  dartson: ^1.0.0-alpha+3

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:dartson/dartson.dart';
  
Version Uploaded Documentation Archive
0.2.7 Mar 31, 2017 Go to the documentation of dartson 0.2.7 Download dartson 0.2.7 archive
0.2.6 Oct 5, 2016 Go to the documentation of dartson 0.2.6 Download dartson 0.2.6 archive
0.2.5 Oct 19, 2015 Go to the documentation of dartson 0.2.5 Download dartson 0.2.5 archive
0.2.4 Jul 4, 2015 Go to the documentation of dartson 0.2.4 Download dartson 0.2.4 archive
0.2.3 May 26, 2015 Go to the documentation of dartson 0.2.3 Download dartson 0.2.3 archive
0.2.2 Mar 2, 2015 Go to the documentation of dartson 0.2.2 Download dartson 0.2.2 archive
0.2.1 Feb 13, 2015 Go to the documentation of dartson 0.2.1 Download dartson 0.2.1 archive
0.2.0 Jan 29, 2015 Go to the documentation of dartson 0.2.0 Download dartson 0.2.0 archive
0.1.6 Jun 6, 2014 Go to the documentation of dartson 0.1.6 Download dartson 0.1.6 archive
0.1.5 Mar 15, 2014 Go to the documentation of dartson 0.1.5 Download dartson 0.1.5 archive

All 19 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
82
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
95
Overall:
Weighted score of the above. [more]
90
Learn more about scoring.

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

  • Dart: 2.1.0
  • pana: 0.12.13

Platforms

Detected platforms: Flutter, other

Primary library: package:dartson/dartson.dart with components: io, isolate.

Maintenance suggestions

Package is pre-release. (-5 points)

Pre-release versions should be used with caution; their API can change in breaking ways.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.65 <3.0.0
analyzer ^0.32.2 0.32.6 0.35.1
build ^0.12.6 0.12.8 1.1.1
build_config >=0.2.6 <0.4.0 0.3.1+4
code_builder ^3.1.2 3.2.0
dart_style ^1.1.3 1.1.3 1.2.3
json_serializable ^1.2.1 1.5.1 2.0.2
meta ^1.1.0 1.1.7
source_gen ^0.9.0 0.9.1+3 0.9.4+1
Transitive dependencies
args 1.5.1
async 2.0.8
built_collection 4.1.0
built_value 6.3.0
charcode 1.1.2
collection 1.14.11
convert 2.1.1
crypto 2.0.6
csslib 0.14.6
fixnum 0.10.9
front_end 0.1.4+2 0.1.11
glob 1.1.7
html 0.13.3+3
json_annotation 1.2.0 2.0.0
kernel 0.3.4+2 0.3.11
logging 0.11.3+2
matcher 0.12.4
package_config 1.0.5
plugin 0.2.0+3
pub_semver 1.4.2
pubspec_parse 0.1.4
quiver 2.0.1
source_span 1.5.4
stack_trace 1.9.3
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
utf 0.9.0+5
watcher 0.9.7+10
yaml 2.1.15
Dev dependencies
build_test ^0.10.0
dart_coveralls ^0.6.0
path ^1.3.2 1.6.2
test ^1.2.0