From 749a996d3339d6fb7795c75da21b7d3d9e217419 Mon Sep 17 00:00:00 2001
From: pavanpodila <pavan@pixelingene.com>
Date: Sat, 13 Jul 2019 17:07:53 +0530
Subject: [PATCH] Adding a detailed guide about json serialization.

---
 .idea/workspace.xml                    |  14 +--
 docs/src/guides/json-serialization.mdx | 168 +++++++++++++++++++++++++
 mobx_examples/lib/todos/todo.dart      |   2 +-
 3 files changed, 176 insertions(+), 8 deletions(-)
 create mode 100644 docs/src/guides/json-serialization.mdx

diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 4f7c9e3da..9f994affa 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -7,7 +7,7 @@
   </component>
   <component name="ChangeListManager">
     <list default="true" id="87dccf31-231e-4b6a-9b49-5967bcdc0ac7" name="Default Changelist" comment="">
-      <change beforePath="$PROJECT_DIR$/.idea/libraries/Dart_Packages.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/libraries/Dart_Packages.xml" afterDir="false" />
+      <change afterPath="$PROJECT_DIR$/docs/src/guides/json-serialization.mdx" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/mobx_examples/lib/todos/todo.dart" beforeDir="false" afterPath="$PROJECT_DIR$/mobx_examples/lib/todos/todo.dart" afterDir="false" />
     </list>
@@ -53,7 +53,7 @@
     <property name="dart.analysis.tool.window.force.activate" value="false" />
     <property name="io.flutter.reload.alreadyRun" value="true" />
     <property name="javascript.nodejs.core.library.configured.version" value="11.14.0" />
-    <property name="last_opened_file_path" value="$PROJECT_DIR$/docs/src/examples" />
+    <property name="last_opened_file_path" value="$PROJECT_DIR$/docs/src/guides" />
     <property name="node.js.detected.package.eslint" value="true" />
     <property name="node.js.detected.package.tslint" value="true" />
     <property name="node.js.path.for.package.eslint" value="project" />
@@ -74,15 +74,15 @@
     <property name="ts.external.directory.path" value="$APPLICATION_HOME_DIR$/plugins/JavaScriptLanguage/jsLanguageServicesImpl/external" />
   </component>
   <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="$PROJECT_DIR$/docs/src/guides" />
+      <recent name="$PROJECT_DIR$/docs/src/examples" />
+    </key>
     <key name="MoveFile.RECENT_KEYS">
       <recent name="$PROJECT_DIR$/docs/src/development" />
       <recent name="$PROJECT_DIR$/docs/src/examples/random-stream" />
       <recent name="$PROJECT_DIR$/mobx_codegen/lib/src" />
     </key>
-    <key name="CopyFile.RECENT_KEYS">
-      <recent name="$PROJECT_DIR$/docs/src/examples" />
-      <recent name="$PROJECT_DIR$/docs/src/guides" />
-    </key>
   </component>
   <component name="RunAnythingCache">
     <option name="myCommands">
@@ -177,8 +177,8 @@
     </list>
     <recent_temporary>
       <list>
-        <item itemvalue="npm.gen:mobx_examples" />
         <item itemvalue="npm.start" />
+        <item itemvalue="npm.gen:mobx_examples" />
         <item itemvalue="Flutter Test.tests in todos_test.dart" />
         <item itemvalue="npm.pub:get:mobx" />
         <item itemvalue="npm.pub:get:mobx_codegen" />
diff --git a/docs/src/guides/json-serialization.mdx b/docs/src/guides/json-serialization.mdx
new file mode 100644
index 000000000..2d218f79a
--- /dev/null
+++ b/docs/src/guides/json-serialization.mdx
@@ -0,0 +1,168 @@
+---
+menu: Guides
+route: /guides/json
+name: JSON Serialization of Stores
+---
+
+# JSON Serialization of Stores
+
+The [![pub package](https://img.shields.io/pub/v/json_serializable.svg?label=json_serializable&color=blue)](https://pub.dartlang.org/packages/json_serializable) package is a popular way to encode/decode between json representations of your models. It works by attaching the `@JsonSerializable` annotation to the `Store` classes. Since this is a custom annotation, we have to invoke the `build_runner` command, just like we do for `mobx_codegen`. After the code is generated, you will have the _to/from-Json_ methods created for you.
+
+Let's add support for `json_serializable` to the **todos** example.
+
+## Adding dependency in `pubspec.yaml`
+
+The first step is to include the dependency on the [![pub package](https://img.shields.io/pub/v/json_serializable.svg?label=json_serializable&color=blue)](https://pub.dartlang.org/packages/json_serializable) package. We add this to the `pubspec.yaml` and run `flutter packages get` to download it.
+
+```yaml
+dependencies:
+  json_serializable: ^3.0.0
+```
+
+## Adding annotations
+
+To generate the json-serialization code, we need to annotate our Store classes: `Todo` and `TodoList`. In the code below, you can see these annotations, as well as some convenience methods (`toJson`, `fromJson`) that wrap the generated methods.
+
+```dart
+import 'package:json_annotation/json_annotation.dart';
+import 'package:mobx/mobx.dart';
+
+part 'todo.g.dart';
+
+@JsonSerializable()
+class Todo extends _Todo with _$Todo {
+  Todo(String description) : super(description);
+
+  static Todo fromJson(Map<String, dynamic> json) => _$TodoFromJson(json);
+  static Map<String, dynamic> toJson(Todo todo) => _$TodoToJson(todo);
+}
+
+```
+
+> In the above code, the `_$TodoFromJson()` and `_$TodoToJson()` methods are generated by `json_serializable`.
+
+### Dealing with `ObservableList<T>`
+
+For the `TodoList`, we have to do a bit more work. The `todos` field is not directly supported by `json_serializable`. It has no understanding of the `ObservableList<Todo>` type. We have to help it out with a type-helper, essentially a `JsonConverter<T, S>` class.
+
+```dart
+@JsonSerializable()
+class TodoList = _TodoList with _$TodoList;
+
+abstract class _TodoList with Store {
+  @observable
+  @_ObservableListConverter()
+  ObservableList<Todo> todos = ObservableList<Todo>();
+
+  // ...
+}
+```
+
+Notice the use of the `@_ObservableListConverter()` annotation. This is the custom type-helper (`JsonConverter<T, S>`) that will handle the serialization for the `ObservableList<Todo>`. This converter class is as below:
+
+```dart
+class _ObservableListConverter
+    implements JsonConverter<ObservableList<Todo>, List<Map<String, dynamic>>> {
+  const _ObservableListConverter();
+
+  @override
+  ObservableList<Todo> fromJson(List<Map<String, dynamic>> json) =>
+      ObservableList.of(json.map(Todo.fromJson));
+
+  @override
+  List<Map<String, dynamic>> toJson(ObservableList<Todo> list) =>
+      list.map(Todo.toJson).toList();
+}
+
+```
+
+> A similar kind of converter would be needed for `ObservableSet<T>` and `ObservableMap<T>` for fields that have those types.
+
+## On with the code-generation
+
+With these changes, let's run the `build_runner` command in the project folder:
+
+```
+flutter packages pub run build_runner watch --delete-conflicting-outputs
+```
+
+This generates the code the looks like so for the `Todo` class, found in `todo.g.dart`.
+
+```dart
+// GENERATED CODE - DO NOT MODIFY BY HAND
+
+part of 'todo.dart';
+
+// **************************************************************************
+// JsonSerializableGenerator
+// **************************************************************************
+
+Todo _$TodoFromJson(Map<String, dynamic> json) {
+  return Todo(json['description'] as String)..done = json['done'] as bool;
+}
+
+Map<String, dynamic> _$TodoToJson(Todo instance) => <String, dynamic>{
+      'description': instance.description,
+      'done': instance.done
+    };
+
+```
+
+> We have wrapped these methods in the `Todo` class with the convenience functions `toJson` and `fromJson`.
+
+The `TodoList` serialization is a bit more involved but should not be too hard to follow. Note that it also includes the serialization for the Enum `VisibilityFilter`. This is in the `todo_list.g.dart`.
+
+```dart
+// GENERATED CODE - DO NOT MODIFY BY HAND
+
+part of 'todo_list.dart';
+
+// **************************************************************************
+// JsonSerializableGenerator
+// **************************************************************************
+
+TodoList _$TodoListFromJson(Map<String, dynamic> json) {
+  return TodoList()
+    ..todos = const _ObservableListConverter()
+        .fromJson(json['todos'] as List<Map<String, dynamic>>)
+    ..filter = _$enumDecodeNullable(_$VisibilityFilterEnumMap, json['filter'])
+    ..currentDescription = json['currentDescription'] as String;
+}
+
+Map<String, dynamic> _$TodoListToJson(TodoList instance) => <String, dynamic>{
+      'todos': const _ObservableListConverter().toJson(instance.todos),
+      'filter': _$VisibilityFilterEnumMap[instance.filter],
+      'currentDescription': instance.currentDescription
+    };
+
+T _$enumDecode<T>(Map<T, dynamic> enumValues, dynamic source) {
+  if (source == null) {
+    throw ArgumentError('A value must be provided. Supported values: '
+        '${enumValues.values.join(', ')}');
+  }
+  return enumValues.entries
+      .singleWhere((e) => e.value == source,
+          orElse: () => throw ArgumentError(
+              '`$source` is not one of the supported values: '
+              '${enumValues.values.join(', ')}'))
+      .key;
+}
+
+T _$enumDecodeNullable<T>(Map<T, dynamic> enumValues, dynamic source) {
+  if (source == null) {
+    return null;
+  }
+  return _$enumDecode<T>(enumValues, source);
+}
+
+const _$VisibilityFilterEnumMap = <VisibilityFilter, dynamic>{
+  VisibilityFilter.all: 'all',
+  VisibilityFilter.pending: 'pending',
+  VisibilityFilter.completed: 'completed'
+};
+
+```
+
+## Summary
+
+With these changes, you should now be able to serialize the **Todos** to/from `JSON` ✌️. BTW, its worth noting that `mobx_codegen` can co-exist with other generators.
diff --git a/mobx_examples/lib/todos/todo.dart b/mobx_examples/lib/todos/todo.dart
index cf679acdc..321a4c17c 100644
--- a/mobx_examples/lib/todos/todo.dart
+++ b/mobx_examples/lib/todos/todo.dart
@@ -3,7 +3,7 @@ import 'package:mobx/mobx.dart';
 
 part 'todo.g.dart';
 
-@JsonSerializable(nullable: false)
+@JsonSerializable()
 class Todo extends _Todo with _$Todo {
   Todo(String description) : super(description);