Add new library: json_serializable.dart

* Added a new method: jsonPartBuilder - so folks don't need to reference
  source_gen

* Deprecated generators.dart in favor of json_serializable.dart

Author: kevmoo

json_serializable/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## 0.3.0
 
+* **NEW** top-level library `json_serializable.dart`.
+
+  * Replaces now deprecated `generators.dart` to access
+  `JsonSerializableGenerator` and `JsonLiteralGenerator`.
+  
+  * Adds the `jsonPartBuilder` function to make it easy to create a
+    `PartBuilder`, without creating an explicit dependency on `source_gen`.
+
 * **BREAKING** `UnsupportedTypeError` added a new required constructor argument:
   `reason`.
 

json_serializable/lib/generators.dart

@@ -2,7 +2,11 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/// Generator classes.
+/// **DEPRECATED** import `package:json_serializable/json_serializable.dart`
+/// instead.
+@Deprecated(
+    'import `package:json_serializable/json_serializable.dart` instead.')
+library json_serializable.generators;
 
 export 'src/json_literal_generator.dart';
 export 'src/json_serializable_generator.dart';

json_serializable/lib/json_serializable.dart

@@ -0,0 +1,7 @@
+// Copyright (c) 2017, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+export 'src/json_literal_generator.dart';
+export 'src/json_part_builder.dart';
+export 'src/json_serializable_generator.dart';

json_serializable/lib/src/json_part_builder.dart

@@ -0,0 +1,42 @@
+// Copyright (c) 2017, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:source_gen/source_gen.dart';
+
+import 'json_literal_generator.dart';
+import 'json_serializable_generator.dart';
+
+/// Returns a [PartBuilder] for use within a `package:build_runner`
+/// `BuildAction`.
+///
+/// [header] is used to specify the content at the top of each generated file.
+/// If `null`, the content of [defaultFileHeader] is used.
+/// If [header] is an empty `String` no header is added.
+///
+/// If [useWrappers] is `true`, wrappers are used to minimize the number of
+/// [Map] and [List] instances created during serialization. This will
+/// increase the code size, but it may improve runtime performance, especially
+/// for large object graphs.
+///
+/// Usage:
+///
+/// ```dart
+/// new BuildAction(
+///   jsonPartBuilder(),
+///   'my_package',
+///   inputs: const ['lib/*.dart']
+/// )
+/// ```
+///
+/// See the [example] to understand how to configure your project for
+/// `json_serializable`.
+///
+/// [example]: https://github.com/dart-lang/json_serializable/tree/master/example
+PartBuilder jsonPartBuilder({String header, bool useWrappers: false}) {
+  useWrappers ??= false;
+  return new PartBuilder([
+    new JsonSerializableGenerator(useWrappers: useWrappers),
+    const JsonLiteralGenerator()
+  ], header: header);
+}

json_serializable/lib/src/json_serializable_generator.dart

@@ -42,6 +42,11 @@ class JsonSerializableGenerator
   ///
   /// If [typeHelpers] is not provided, two built-in helpers are used:
   /// [JsonHelper] and [DateTimeHelper].
+  ///
+  /// If [useWrappers] is `true`, wrappers are used to minimize the number of
+  /// [Map] and [List] instances created during serialization. This will
+  /// increase the code size, but it may improve runtime performance, especially
+  /// for large object graphs.
   const JsonSerializableGenerator(
       {List<TypeHelper> typeHelpers, bool useWrappers: false})
       : this.useWrappers = useWrappers ?? false,

json_serializable/test/json_serializable_test.dart

@@ -12,7 +12,7 @@ import 'dart:async';
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/src/string_source.dart';
 import 'package:dart_style/dart_style.dart' as dart_style;
-import 'package:json_serializable/generators.dart';
+import 'package:json_serializable/json_serializable.dart';
 import 'package:json_serializable/src/utils.dart';
 import 'package:path/path.dart' as p;
 import 'package:source_gen/source_gen.dart';

json_serializable/tool/build_actions.dart

@@ -7,7 +7,7 @@ import 'dart:async';
 import 'package:build/build.dart';
 
 import 'package:build_runner/build_runner.dart';
-import 'package:json_serializable/generators.dart';
+import 'package:json_serializable/json_serializable.dart';
 import 'package:path/path.dart' as p;
 import 'package:source_gen/source_gen.dart';
 
@@ -31,9 +31,7 @@ final List<BuildAction> buildActions = [
         'test/test_files/json_test_example.non_nullable.dart',
       ]),
   new BuildAction(
-    new PartBuilder(
-        const [const JsonSerializableGenerator(), const JsonLiteralGenerator()],
-        header: _copyrightHeader),
+    jsonPartBuilder(header: _copyrightHeader),
     'json_serializable',
     inputs: const [
       'test/test_files/json_literal.dart',
@@ -44,8 +42,7 @@ final List<BuildAction> buildActions = [
     ],
   ),
   new BuildAction(
-    new PartBuilder(const [const JsonSerializableGenerator(useWrappers: true)],
-        header: _copyrightHeader),
+    jsonPartBuilder(useWrappers: true, header: _copyrightHeader),
     'json_serializable',
     inputs: const [
       'test/test_files/kitchen_sink*wrapped.dart',