Merge pull request #3 from KosukeSaigusa/v0.0.2

V0.0.2

README.md

@@ -6,7 +6,7 @@ flutterfire_json_converters package supplies some useful json_converters when yo
 
 ### Requirements
 
-This package uses Dart 3 features, so you need to use compatible Dart (Flutter SDK).
+This package uses Dart 3 features, so you need to use compatible Dart (Flutter) SDK.
 
 ```yaml
 environment:
@@ -40,6 +40,51 @@ When dealing with Cloud Firestore's `Timestamp` field, you may encounter the fol
 - During the creation or updating of Cloud Firestore documents, you may want to automatically set certain fields (e.g., `updatedAt`) to `FieldValue.serverTimestamp()`.
 - For other fields (e.g., `createdAt`), you might sometimes prefer to specify a client-side DateTime and save it to a Cloud Firestore document, while at other times you might want to automatically set it to `FieldValue.serverTimestamp()`.
 
+For such scenarios, you can define `DateTime`/`Timestamp` fields as `SealedTimestamp` type with `@sealedTimestampConverter`/`@alwaysUseServerTimestampSealedTimestampConverter` json_converter annotations like below:
+
+```dart
+@JsonSerializable()
+class Entity {
+  Entity({
+    required this.name,
+    this.createdAt = const ServerTimestamp(),
+    this.updatedAt = const ServerTimestamp(),
+  });
+
+  factory Entity.fromJson(Map<String, dynamic> json) => _$EntityFromJson(json);
+
+  final String name;
+
+  // Handle both Dart's `DateTime` and Cloud Firestore's `Timestamp` types.
+  @sealedTimestampConverter
+  final SealedTimestamp createdAt;
+
+  // Handle both Dart's `DateTime` and Cloud Firestore's `Timestamp` types, and
+  // always use `FieldValue.serverTimestamp()` when creating/updating a document.
+  @alwaysUseServerTimestampSealedTimestampConverter
+  final SealedTimestamp updatedAt;
+
+  Map<String, dynamic> toJson() => _$EntityToJson(this);
+}
+```
+
+When you want to get `DateTime` value of their fields on Dart client-side, you can call `SealedTimestamp.dateTime`.
+
+```dart
+final epoch = DateTime(1970);
+final entity = Entity(name: 'foo', createdAt: ClientDateTime(epoch));
+
+print(entity.name); // 'foo'
+print(entity.createdAt.dateTime) // 1970-01-01 00:00:00.000
+print(entity.updatedAt.dateTime) // null
+
+final json = entity.toJson();
+
+print(json['name']); // 'foo'
+print(json['createdAt']); // Timestamp(seconds=0, nanoseconds=0)
+print(json['updatedAt']); // FieldValue(Instance of 'MethodChannelFieldValue')
+```
+
 ## Acknowledgements
 
 This package is developed with reference to:

example/build.yaml

@@ -0,0 +1 @@
+../build.yaml

example/lib/main.dart

@@ -11,20 +11,19 @@ class Entity {
     this.updatedAt = const ServerTimestamp(),
   });
 
-  /// Connect the generated [_$EntityFromJson] function to the `fromJson`
-  /// factory.
   factory Entity.fromJson(Map<String, dynamic> json) => _$EntityFromJson(json);
 
-  /// The generated code assumes these values exist in JSON.
   final String name;
 
+  // Handle both Dart's `DateTime` and Cloud Firestore's `Timestamp` types.
   @sealedTimestampConverter
   final SealedTimestamp createdAt;
 
+  // Handle both Dart's `DateTime` and Cloud Firestore's `Timestamp` types, and
+  // always use `FieldValue.serverTimestamp()` when creating/updating a document.
   @alwaysUseServerTimestampSealedTimestampConverter
   final SealedTimestamp updatedAt;
 
-  /// Connect the generated [_$EntityToJson] function to the `toJson` method.
   Map<String, dynamic> toJson() => _$EntityToJson(this);
 }
 

pubspec.yaml

@@ -1,7 +1,7 @@
 name: flutterfire_json_converters
 description: flutterfire_json_converters package supplies some useful json_converters for your FlutterFire apps.
 version: 0.0.1
-homepage: https://github.com/KosukeSaigusa/flutterfire_json_converters
+homepage: https://github.com/KosukeSaigusa/flutterfire-json-converters
 
 environment:
   sdk: '>=3.0.0 <4.0.0'

test/flutterfire_json_converters_test.dart

@@ -22,8 +22,6 @@ void main() {
       final entity = Entity(name: 'foo', createdAt: ClientDateTime(epoch));
       final json = entity.toJson();
 
-      print(json['updatedAt']);
-
       expect(json['name'], 'foo');
       expect(json['createdAt'], Timestamp.fromDate(epoch));
       expect(json['updatedAt'], isA<FieldValue>());

test/helper/entity.dart

@@ -11,19 +11,18 @@ class Entity {
     this.updatedAt = const ServerTimestamp(),
   });
 
-  /// Connect the generated [_$EntityFromJson] function to the `fromJson`
-  /// factory.
   factory Entity.fromJson(Map<String, dynamic> json) => _$EntityFromJson(json);
 
-  /// The generated code assumes these values exist in JSON.
   final String name;
 
+  // Handle both Dart's `DateTime` and Cloud Firestore's `Timestamp` types.
   @sealedTimestampConverter
   final SealedTimestamp createdAt;
 
+  // Handle both Dart's `DateTime` and Cloud Firestore's `Timestamp` types, and
+  // always use `FieldValue.serverTimestamp()` when creating/updating a document.
   @alwaysUseServerTimestampSealedTimestampConverter
   final SealedTimestamp updatedAt;
 
-  /// Connect the generated [_$EntityToJson] function to the `toJson` method.
   Map<String, dynamic> toJson() => _$EntityToJson(this);
 }