Breaking changes to signature of snapshots and setData in cloud_firestore (flutter#536)

These changes are required to support the metadata argument to snapshots and other future API changes.

Author: collinjackson

packages/cloud_firestore/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.7.0
+
+* **Breaking change**. `snapshots` is now a method instead of a getter.
+* **Breaking change**. `setData` uses named arguments instead of `SetOptions`.
+
 ## 0.6.3
 
 * Updated Google Play Services dependencies to version 15.0.0.

packages/cloud_firestore/example/lib/main.dart

@@ -32,7 +32,7 @@ class MessageList extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return new StreamBuilder<QuerySnapshot>(
-      stream: firestore.collection('messages').snapshots,
+      stream: firestore.collection('messages').snapshots(),
       builder: (BuildContext context, AsyncSnapshot<QuerySnapshot> snapshot) {
         if (!snapshot.hasData) return const Text('Loading...');
         final int messageCount = snapshot.data.documents.length;

packages/cloud_firestore/lib/cloud_firestore.dart

@@ -26,7 +26,6 @@ part 'src/firestore.dart';
 part 'src/geo_point.dart';
 part 'src/query.dart';
 part 'src/query_snapshot.dart';
-part 'src/set_options.dart';
 part 'src/firestore_message_codec.dart';
 part 'src/snapshot_metadata.dart';
 part 'src/transaction.dart';

packages/cloud_firestore/lib/src/document_reference.dart

@@ -33,17 +33,20 @@ class DocumentReference {
   /// This document's given or generated ID in the collection.
   String get documentID => _pathComponents.last;
 
-  /// Writes to the document referred to by this [DocumentReference]. If the
-  /// document does not yet exist, it will be created. If you pass [SetOptions],
-  /// the provided data will be merged into an existing document.
-  Future<void> setData(Map<String, dynamic> data, [SetOptions options]) {
+  /// Writes to the document referred to by this [DocumentReference].
+  ///
+  /// If the document does not yet exist, it will be created.
+  ///
+  /// If [merge] is true, the provided data will be merged into an
+  /// existing document instead of overwriting.
+  Future<void> setData(Map<String, dynamic> data, {bool merge: false}) {
     return Firestore.channel.invokeMethod(
       'DocumentReference#setData',
       <String, dynamic>{
         'app': firestore.app.name,
         'path': path,
         'data': data,
-        'options': options?._data,
+        'options': <String, bool>{'merge': merge},
       },
     );
   }
@@ -95,7 +98,7 @@ class DocumentReference {
 
   /// Notifies of documents at this location
   // TODO(jackson): Reduce code duplication with [Query]
-  Stream<DocumentSnapshot> get snapshots {
+  Stream<DocumentSnapshot> snapshots() {
     Future<int> _handle;
     // It's fine to let the StreamController be garbage collected once all the
     // subscribers have cancelled; this analyzer warning is safe to ignore.

packages/cloud_firestore/lib/src/query.dart

@@ -47,7 +47,7 @@ class Query {
 
   /// Notifies of query results at this location
   // TODO(jackson): Reduce code duplication with [DocumentReference]
-  Stream<QuerySnapshot> get snapshots {
+  Stream<QuerySnapshot> snapshots() {
     Future<int> _handle;
     // It's fine to let the StreamController be garbage collected once all the
     // subscribers have cancelled; this analyzer warning is safe to ignore.

packages/cloud_firestore/lib/src/set_options.dart

@@ -61,10 +61,10 @@ class WriteBatch {
   ///
   /// If the document does not yet exist, it will be created.
   ///
-  /// If you pass [SetOptions], the provided data will be merged into an
-  /// existing document.
+  /// If [merge] is true, the provided data will be merged into an
+  /// existing document instead of overwriting.
   void setData(DocumentReference document, Map<String, dynamic> data,
-      [SetOptions options]) {
+      {bool merge: false}) {
     if (!_committed) {
       _handle.then((dynamic handle) {
         _actions.add(
@@ -75,7 +75,7 @@ class WriteBatch {
               'handle': handle,
               'path': document.path,
               'data': data,
-              'options': options?._data,
+              'options': <String, bool>{'merge': merge},
             },
           ),
         );

packages/cloud_firestore/lib/src/write_batch.dart

@@ -3,7 +3,7 @@ description: Flutter plugin for Cloud Firestore, a cloud-hosted, noSQL database
   live synchronization and offline support on Android and iOS.
 author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/cloud_firestore
-version: 0.6.3
+version: 0.7.0
 
 flutter:
   plugin:

packages/cloud_firestore/pubspec.yaml

@@ -246,7 +246,7 @@ void main() {
       });
       test('listen', () async {
         final QuerySnapshot snapshot =
-            await collectionReference.snapshots.first;
+            await collectionReference.snapshots().first;
         final DocumentSnapshot document = snapshot.documents[0];
         expect(document.documentID, equals('0'));
         expect(document.reference.path, equals('foo/0'));
@@ -275,7 +275,7 @@ void main() {
         final StreamSubscription<QuerySnapshot> subscription =
             collectionReference
                 .where('createdAt', isLessThan: 100)
-                .snapshots
+                .snapshots()
                 .listen((QuerySnapshot querySnapshot) {});
         subscription.cancel();
         await new Future<Null>.delayed(Duration.zero);
@@ -306,7 +306,7 @@ void main() {
         final StreamSubscription<QuerySnapshot> subscription =
             collectionReference
                 .where('profile', isNull: true)
-                .snapshots
+                .snapshots()
                 .listen((QuerySnapshot querySnapshot) {});
         subscription.cancel();
         await new Future<Null>.delayed(Duration.zero);
@@ -337,7 +337,7 @@ void main() {
         final StreamSubscription<QuerySnapshot> subscription =
             collectionReference
                 .orderBy('createdAt')
-                .snapshots
+                .snapshots()
                 .listen((QuerySnapshot querySnapshot) {});
         subscription.cancel();
         await new Future<Null>.delayed(Duration.zero);
@@ -369,7 +369,7 @@ void main() {
     group('DocumentReference', () {
       test('listen', () async {
         final DocumentSnapshot snapshot =
-            await firestore.document('path/to/foo').snapshots.first;
+            await firestore.document('path/to/foo').snapshots().first;
         expect(snapshot.documentID, equals('foo'));
         expect(snapshot.reference.path, equals('path/to/foo'));
         expect(snapshot.data, equals(kMockDocumentSnapshotData));
@@ -405,7 +405,7 @@ void main() {
                 'app': app.name,
                 'path': 'foo/bar',
                 'data': <String, String>{'bazKey': 'quxValue'},
-                'options': null,
+                'options': <String, bool>{'merge': false},
               },
             ),
           ],
@@ -414,8 +414,7 @@ void main() {
       test('merge set', () async {
         await collectionReference
             .document('bar')
-            .setData(<String, String>{'bazKey': 'quxValue'}, SetOptions.merge);
-        expect(SetOptions.merge, isNotNull);
+            .setData(<String, String>{'bazKey': 'quxValue'}, merge: true);
         expect(
           log,
           <Matcher>[
@@ -576,7 +575,7 @@ void main() {
                 'handle': 1,
                 'path': 'foo/bar',
                 'data': <String, String>{'bazKey': 'quxValue'},
-                'options': null,
+                'options': <String, bool>{'merge': false},
               },
             ),
             isMethodCall(
@@ -593,10 +592,9 @@ void main() {
         batch.setData(
           collectionReference.document('bar'),
           <String, String>{'bazKey': 'quxValue'},
-          SetOptions.merge,
+          merge: true,
         );
         await batch.commit();
-        expect(SetOptions.merge, isNotNull);
         expect(
           log,
           <Matcher>[