Replace `QueryListenOptions` with simple booleans (#1106)

* Replace `QueryListenOptions` with simple booleans

Instead of calling

  addSnapshotListener(
      options:QueryListenOptions.includeQueryMetadataChanges()
                                .includeDocumentMetadataChanges())

call

  addSnapshotListener(includeMetadataChanges:true)

Also change `QuerySnapshot.documentChanges()` into a method which
optionally takes `includeMetadataChanges:true`. By default even when
listening to a query with `inlcudeMetadataChanges:true` metadata-only
document changes are suppressed because they're confusing.

* Revert QuerySnapshot.documentChanges back to a property

Add usage.

11 files changed, 193 insertions, 126 deletions

diff --git a/Firestore/CHANGELOG.md b/Firestore/CHANGELOG.md
index 00e16f5..4761a62 100644
--- a/Firestore/CHANGELOG.md
+++ b/Firestore/CHANGELOG.md
@@ -3,6 +3,16 @@
   Instead of calling
   `addSnapshotListener(options: DocumentListenOptions.includeMetadataChanges(true))`
   call `addSnapshotListener(includeMetadataChanges:true)`.
+- [changed] Replaced the `QueryListenOptions` object with simple booleans.
+  Instead of calling
+  `addSnapshotListener(options:
+      QueryListenOptions.includeQueryMetadataChanges(true)
+          .includeDocumentMetadataChanges(true))`
+  call `addSnapshotListener(includeMetadataChanges:true)`.
+- [changed] `QuerySnapshot.documentChanges()` is now a method which optionally
+  takes `includeMetadataChanges:true`. By default even when listening to a
+  query with `includeMetadataChanges:true` metadata-only document changes are
+  suppressed in `documentChanges()`.
 - [changed] Replaced the `SetOptions` object with a simple boolean. Instead of
   calling `setData(["a": "b"], options: SetOptions.merge())` call
   `setData(["a": "b"], merge: true)`.
diff --git a/Firestore/Example/SwiftBuildTest/main.swift b/Firestore/Example/SwiftBuildTest/main.swift
index ad6c0f6..8de5ed4 100644
--- a/Firestore/Example/SwiftBuildTest/main.swift
+++ b/Firestore/Example/SwiftBuildTest/main.swift
@@ -321,6 +321,26 @@ func listenToQueryDiffs(onQuery query: Query) {
   listener.remove()
 }
 
+func listenToQueryDiffsWithMetadata(onQuery query: Query) {
+  let listener = query.addSnapshotListener(includeMetadataChanges: true) { snap, error in
+    if let snap = snap {
+      for change in snap.documentChanges(includeMetadataChanges: true) {
+        switch change.type {
+        case .added:
+          print("New document: \(change.document.data())")
+        case .modified:
+          print("Modified document: \(change.document.data())")
+        case .removed:
+          print("Removed document: \(change.document.data())")
+        }
+      }
+    }
+  }
+
+  // Unsubscribe
+  listener.remove()
+}
+
 func transactions() {
   let db = Firestore.firestore()
 
@@ -361,7 +381,6 @@ func types() {
   let _: GeoPoint
   let _: Timestamp
   let _: ListenerRegistration
-  let _: QueryListenOptions
   let _: Query
   let _: QuerySnapshot
   let _: SnapshotMetadata
diff --git a/Firestore/Example/Tests/API/FIRQuerySnapshotTests.mm b/Firestore/Example/Tests/API/FIRQuerySnapshotTests.mm
index f8c7d60..746c107 100644
--- a/Firestore/Example/Tests/API/FIRQuerySnapshotTests.mm
+++ b/Firestore/Example/Tests/API/FIRQuerySnapshotTests.mm
@@ -19,9 +19,31 @@
 #import <XCTest/XCTest.h>
 
 #import "Firestore/Example/Tests/API/FSTAPIHelpers.h"
+#import "Firestore/Example/Tests/Util/FSTHelpers.h"
+#import "Firestore/Source/API/FIRDocumentChange+Internal.h"
+#import "Firestore/Source/API/FIRDocumentSnapshot+Internal.h"
+#import "Firestore/Source/API/FIRQuerySnapshot+Internal.h"
+#import "Firestore/Source/API/FIRSnapshotMetadata+Internal.h"
+#import "Firestore/Source/Core/FSTViewSnapshot.h"
+#import "Firestore/Source/Model/FSTDocument.h"
+#import "Firestore/Source/Model/FSTDocumentSet.h"
+
+#include "Firestore/core/src/firebase/firestore/util/string_apple.h"
+
+namespace util = firebase::firestore::util;
 
 NS_ASSUME_NONNULL_BEGIN
 
+@interface FIRDocumentChange ()
+
+// Expose initializer for testing.
+- (instancetype)initWithType:(FIRDocumentChangeType)type
+                    document:(FIRQueryDocumentSnapshot *)document
+                    oldIndex:(NSUInteger)oldIndex
+                    newIndex:(NSUInteger)newIndex;
+
+@end
+
 @interface FIRQuerySnapshotTests : XCTestCase
 @end
 
@@ -51,6 +73,67 @@ NS_ASSUME_NONNULL_BEGIN
   XCTAssertNotEqual([foo hash], [fromCache hash]);
 }
 
+- (void)testIncludeMetadataChanges {
+  FSTDocument *doc1Old = FSTTestDoc("foo/bar", 1, @{@"a" : @"b"}, YES);
+  FSTDocument *doc1New = FSTTestDoc("foo/bar", 1, @{@"a" : @"b"}, NO);
+
+  FSTDocument *doc2Old = FSTTestDoc("foo/baz", 1, @{@"a" : @"b"}, NO);
+  FSTDocument *doc2New = FSTTestDoc("foo/baz", 1, @{@"a" : @"c"}, NO);
+
+  FSTDocumentSet *oldDocuments = FSTTestDocSet(FSTDocumentComparatorByKey, @[ doc1Old, doc2Old ]);
+  FSTDocumentSet *newDocuments = FSTTestDocSet(FSTDocumentComparatorByKey, @[ doc2New, doc2New ]);
+  NSArray<FSTDocumentViewChange *> *documentChanges = @[
+    [FSTDocumentViewChange changeWithDocument:doc1New type:FSTDocumentViewChangeTypeMetadata],
+    [FSTDocumentViewChange changeWithDocument:doc2New type:FSTDocumentViewChangeTypeModified],
+  ];
+
+  FIRFirestore *firestore = FSTTestFirestore();
+  FSTQuery *query = FSTTestQuery("foo");
+  FSTViewSnapshot *viewSnapshot = [[FSTViewSnapshot alloc] initWithQuery:query
+                                                               documents:newDocuments
+                                                            oldDocuments:oldDocuments
+                                                         documentChanges:documentChanges
+                                                               fromCache:NO
+                                                        hasPendingWrites:NO
+                                                        syncStateChanged:YES];
+  FIRSnapshotMetadata *metadata =
+      [FIRSnapshotMetadata snapshotMetadataWithPendingWrites:NO fromCache:NO];
+  FIRQuerySnapshot *snapshot = [FIRQuerySnapshot snapshotWithFirestore:firestore
+                                                         originalQuery:query
+                                                              snapshot:viewSnapshot
+                                                              metadata:metadata];
+
+  FIRQueryDocumentSnapshot *doc1Snap = [FIRQueryDocumentSnapshot snapshotWithFirestore:firestore
+                                                                           documentKey:doc1New.key
+                                                                              document:doc1New
+                                                                             fromCache:NO];
+  FIRQueryDocumentSnapshot *doc2Snap = [FIRQueryDocumentSnapshot snapshotWithFirestore:firestore
+                                                                           documentKey:doc2New.key
+                                                                              document:doc2New
+                                                                             fromCache:NO];
+
+  NSArray<FIRDocumentChange *> *changesWithoutMetadata = @[
+    [[FIRDocumentChange alloc] initWithType:FIRDocumentChangeTypeModified
+                                   document:doc2Snap
+                                   oldIndex:1
+                                   newIndex:1],
+  ];
+  XCTAssertEqualObjects(snapshot.documentChanges, changesWithoutMetadata);
+
+  NSArray<FIRDocumentChange *> *changesWithMetadata = @[
+    [[FIRDocumentChange alloc] initWithType:FIRDocumentChangeTypeModified
+                                   document:doc1Snap
+                                   oldIndex:0
+                                   newIndex:0],
+    [[FIRDocumentChange alloc] initWithType:FIRDocumentChangeTypeModified
+                                   document:doc2Snap
+                                   oldIndex:1
+                                   newIndex:1],
+  ];
+  XCTAssertEqualObjects([snapshot documentChangesWithIncludeMetadataChanges:YES],
+                        changesWithMetadata);
+}
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/Firestore/Example/Tests/Integration/API/FIRQueryTests.mm b/Firestore/Example/Tests/Integration/API/FIRQueryTests.mm
index 32d746e..d1c0d75 100644
--- a/Firestore/Example/Tests/Integration/API/FIRQueryTests.mm
+++ b/Firestore/Example/Tests/Integration/API/FIRQueryTests.mm
@@ -221,16 +221,14 @@
 
   FIRFirestore *firestore = collectionRef.firestore;
 
-  FIRQueryListenOptions *options = [[[FIRQueryListenOptions options]
-      includeDocumentMetadataChanges:YES] includeQueryMetadataChanges:YES];
-
-  [collectionRef addSnapshotListenerWithOptions:options
-                                       listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
-                                         XCTAssertNil(error);
-                                         if (!snapshot.empty && !snapshot.metadata.fromCache) {
-                                           [testExpectiation fulfill];
-                                         }
-                                       }];
+  [collectionRef
+      addSnapshotListenerWithIncludeMetadataChanges:YES
+                                           listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
+                                             XCTAssertNil(error);
+                                             if (!snapshot.empty && !snapshot.metadata.fromCache) {
+                                               [testExpectiation fulfill];
+                                             }
+                                           }];
 
   [firestore disableNetworkWithCompletion:^(NSError *error) {
     XCTAssertNil(error);
@@ -249,11 +247,9 @@
   };
   FIRCollectionReference *collection = [self collectionRefWithDocuments:testDocs];
 
-  FIRQueryListenOptions *options = [[[FIRQueryListenOptions options]
-      includeDocumentMetadataChanges:YES] includeQueryMetadataChanges:YES];
-  id<FIRListenerRegistration> registration =
-      [collection addSnapshotListenerWithOptions:options
-                                        listener:self.eventAccumulator.valueEventHandler];
+  id<FIRListenerRegistration> registration = [collection
+      addSnapshotListenerWithIncludeMetadataChanges:YES
+                                           listener:self.eventAccumulator.valueEventHandler];
 
   FIRQuerySnapshot *querySnap = [self.eventAccumulator awaitEventWithName:@"initial event"];
   XCTAssertEqualObjects(FIRQuerySnapshotGetData(querySnap), @[ @{ @"foo" : @1 } ]);
diff --git a/Firestore/Example/Tests/Integration/API/FIRWriteBatchTests.mm b/Firestore/Example/Tests/Integration/API/FIRWriteBatchTests.mm
index 3f2d64b..5340873 100644
--- a/Firestore/Example/Tests/Integration/API/FIRWriteBatchTests.mm
+++ b/Firestore/Example/Tests/Integration/API/FIRWriteBatchTests.mm
@@ -147,9 +147,8 @@
   FIRDocumentReference *docA = [collection documentWithPath:@"a"];
   FIRDocumentReference *docB = [collection documentWithPath:@"b"];
   FSTEventAccumulator *accumulator = [FSTEventAccumulator accumulatorForTest:self];
-  [collection addSnapshotListenerWithOptions:[[FIRQueryListenOptions options]
-                                                 includeQueryMetadataChanges:YES]
-                                    listener:accumulator.valueEventHandler];
+  [collection addSnapshotListenerWithIncludeMetadataChanges:YES
+                                                   listener:accumulator.valueEventHandler];
   FIRQuerySnapshot *initialSnap = [accumulator awaitEventWithName:@"initial event"];
   XCTAssertEqual(initialSnap.count, 0);
 
@@ -177,9 +176,8 @@
   FIRDocumentReference *docA = [collection documentWithPath:@"a"];
   FIRDocumentReference *docB = [collection documentWithPath:@"b"];
   FSTEventAccumulator *accumulator = [FSTEventAccumulator accumulatorForTest:self];
-  [collection addSnapshotListenerWithOptions:[[FIRQueryListenOptions options]
-                                                 includeQueryMetadataChanges:YES]
-                                    listener:accumulator.valueEventHandler];
+  [collection addSnapshotListenerWithIncludeMetadataChanges:YES
+                                                   listener:accumulator.valueEventHandler];
   FIRQuerySnapshot *initialSnap = [accumulator awaitEventWithName:@"initial event"];
   XCTAssertEqual(initialSnap.count, 0);
 
@@ -211,9 +209,8 @@
   FIRDocumentReference *docA = [collection documentWithPath:@"a"];
   FIRDocumentReference *docB = [collection documentWithPath:@"b"];
   FSTEventAccumulator *accumulator = [FSTEventAccumulator accumulatorForTest:self];
-  [collection addSnapshotListenerWithOptions:[[FIRQueryListenOptions options]
-                                                 includeQueryMetadataChanges:YES]
-                                    listener:accumulator.valueEventHandler];
+  [collection addSnapshotListenerWithIncludeMetadataChanges:YES
+                                                   listener:accumulator.valueEventHandler];
   FIRQuerySnapshot *initialSnap = [accumulator awaitEventWithName:@"initial event"];
   XCTAssertEqual(initialSnap.count, 0);
 
diff --git a/Firestore/Source/API/FIRDocumentChange+Internal.h b/Firestore/Source/API/FIRDocumentChange+Internal.h
index 7c9723c..2aaced1 100644
--- a/Firestore/Source/API/FIRDocumentChange+Internal.h
+++ b/Firestore/Source/API/FIRDocumentChange+Internal.h
@@ -26,6 +26,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 /** Calculates the array of FIRDocumentChange's based on the given FSTViewSnapshot. */
 + (NSArray<FIRDocumentChange *> *)documentChangesForSnapshot:(FSTViewSnapshot *)snapshot
+                                      includeMetadataChanges:(BOOL)includeMetadataChanges
                                                    firestore:(FIRFirestore *)firestore;
 
 @end
diff --git a/Firestore/Source/API/FIRDocumentChange.mm b/Firestore/Source/API/FIRDocumentChange.mm
index d1d9999..7bb24d2 100644
--- a/Firestore/Source/API/FIRDocumentChange.mm
+++ b/Firestore/Source/API/FIRDocumentChange.mm
@@ -50,9 +50,11 @@ NS_ASSUME_NONNULL_BEGIN
 }
 
 + (NSArray<FIRDocumentChange *> *)documentChangesForSnapshot:(FSTViewSnapshot *)snapshot
+                                      includeMetadataChanges:(BOOL)includeMetadataChanges
                                                    firestore:(FIRFirestore *)firestore {
   if (snapshot.oldDocuments.isEmpty) {
-    // Special case the first snapshot because index calculation is easy and fast
+    // Special case the first snapshot because index calculation is easy and fast. Also all changes
+    // on the first snapshot are adds so there are also no metadata-only changes to filter out.
     FSTDocument *_Nullable lastDocument = nil;
     NSUInteger index = 0;
     NSMutableArray<FIRDocumentChange *> *changes = [NSMutableArray array];
@@ -79,6 +81,10 @@ NS_ASSUME_NONNULL_BEGIN
     FSTDocumentSet *indexTracker = snapshot.oldDocuments;
     NSMutableArray<FIRDocumentChange *> *changes = [NSMutableArray array];
     for (FSTDocumentViewChange *change in snapshot.documentChanges) {
+      if (!includeMetadataChanges && change.type == FSTDocumentViewChangeTypeMetadata) {
+        continue;
+      }
+
       FIRQueryDocumentSnapshot *document =
           [FIRQueryDocumentSnapshot snapshotWithFirestore:firestore
                                               documentKey:change.document.key
@@ -124,6 +130,23 @@ NS_ASSUME_NONNULL_BEGIN
   return self;
 }
 
+- (BOOL)isEqual:(nullable id)other {
+  if (other == self) return YES;
+  if (![other isKindOfClass:[FIRDocumentChange class]]) return NO;
+
+  FIRDocumentChange *change = (FIRDocumentChange *)other;
+  return self.type == change.type && [self.document isEqual:change.document] &&
+         self.oldIndex == change.oldIndex && self.newIndex == change.newIndex;
+}
+
+- (NSUInteger)hash {
+  NSUInteger result = (NSUInteger)self.type;
+  result = result * 31u + [self.document hash];
+  result = result * 31u + (NSUInteger)self.oldIndex;
+  result = result * 31u + (NSUInteger)self.newIndex;
+  return result;
+}
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/Firestore/Source/API/FIRQuery.mm b/Firestore/Source/API/FIRQuery.mm
index 9cdc572..14dcaef 100644
--- a/Firestore/Source/API/FIRQuery.mm
+++ b/Firestore/Source/API/FIRQuery.mm
@@ -48,47 +48,6 @@ using firebase::firestore::model::ResourcePath;
 
 NS_ASSUME_NONNULL_BEGIN
 
-@interface FIRQueryListenOptions ()
-
-- (instancetype)initWithIncludeQueryMetadataChanges:(BOOL)includeQueryMetadataChanges
-                     includeDocumentMetadataChanges:(BOOL)includeDocumentMetadataChanges
-    NS_DESIGNATED_INITIALIZER;
-
-@end
-
-@implementation FIRQueryListenOptions
-
-+ (instancetype)options {
-  return [[FIRQueryListenOptions alloc] init];
-}
-
-- (instancetype)initWithIncludeQueryMetadataChanges:(BOOL)includeQueryMetadataChanges
-                     includeDocumentMetadataChanges:(BOOL)includeDocumentMetadataChanges {
-  if (self = [super init]) {
-    _includeQueryMetadataChanges = includeQueryMetadataChanges;
-    _includeDocumentMetadataChanges = includeDocumentMetadataChanges;
-  }
-  return self;
-}
-
-- (instancetype)init {
-  return [self initWithIncludeQueryMetadataChanges:NO includeDocumentMetadataChanges:NO];
-}
-
-- (instancetype)includeQueryMetadataChanges:(BOOL)includeQueryMetadataChanges {
-  return [[FIRQueryListenOptions alloc]
-      initWithIncludeQueryMetadataChanges:includeQueryMetadataChanges
-           includeDocumentMetadataChanges:_includeDocumentMetadataChanges];
-}
-
-- (instancetype)includeDocumentMetadataChanges:(BOOL)includeDocumentMetadataChanges {
-  return [[FIRQueryListenOptions alloc]
-      initWithIncludeQueryMetadataChanges:_includeQueryMetadataChanges
-           includeDocumentMetadataChanges:includeDocumentMetadataChanges];
-}
-
-@end
-
 @interface FIRQuery ()
 @property(nonatomic, strong, readonly) FSTQuery *query;
 @end
@@ -162,14 +121,14 @@ NS_ASSUME_NONNULL_BEGIN
 }
 
 - (id<FIRListenerRegistration>)addSnapshotListener:(FIRQuerySnapshotBlock)listener {
-  return [self addSnapshotListenerWithOptions:nil listener:listener];
+  return [self addSnapshotListenerWithIncludeMetadataChanges:NO listener:listener];
 }
 
-- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:
-                                   (nullable FIRQueryListenOptions *)options
-                                                     listener:(FIRQuerySnapshotBlock)listener {
-  return [self addSnapshotListenerInternalWithOptions:[self internalOptions:options]
-                                             listener:listener];
+- (id<FIRListenerRegistration>)
+addSnapshotListenerWithIncludeMetadataChanges:(BOOL)includeMetadataChanges
+                                     listener:(FIRQuerySnapshotBlock)listener {
+  auto options = [self internalOptionsForIncludeMetadataChanges:includeMetadataChanges];
+  return [self addSnapshotListenerInternalWithOptions:options listener:listener];
 }
 
 - (id<FIRListenerRegistration>)
@@ -629,11 +588,10 @@ addSnapshotListenerInternalWithOptions:(FSTListenOptions *)internalOptions
 }
 
 /** Converts the public API options object to the internal options object. */
-- (FSTListenOptions *)internalOptions:(nullable FIRQueryListenOptions *)options {
-  return [[FSTListenOptions alloc]
-      initWithIncludeQueryMetadataChanges:options.includeQueryMetadataChanges
-           includeDocumentMetadataChanges:options.includeDocumentMetadataChanges
-                    waitForSyncWhenOnline:NO];
+- (FSTListenOptions *)internalOptionsForIncludeMetadataChanges:(BOOL)includeMetadataChanges {
+  return [[FSTListenOptions alloc] initWithIncludeQueryMetadataChanges:includeMetadataChanges
+                                        includeDocumentMetadataChanges:includeMetadataChanges
+                                                 waitForSyncWhenOnline:NO];
 }
 
 @end
diff --git a/Firestore/Source/API/FIRQuerySnapshot.mm b/Firestore/Source/API/FIRQuerySnapshot.mm
index abee84c..fb7a849 100644
--- a/Firestore/Source/API/FIRQuerySnapshot.mm
+++ b/Firestore/Source/API/FIRQuerySnapshot.mm
@@ -62,6 +62,7 @@ NS_ASSUME_NONNULL_BEGIN
 
   // Cached value of the documentChanges property.
   NSArray<FIRDocumentChange *> *_documentChanges;
+  BOOL _documentChangesIncludeMetadataChanges;
 }
 
 - (instancetype)initWithFirestore:(FIRFirestore *)firestore
@@ -73,6 +74,7 @@ NS_ASSUME_NONNULL_BEGIN
     _originalQuery = query;
     _snapshot = snapshot;
     _metadata = metadata;
+    _documentChangesIncludeMetadataChanges = NO;
   }
   return self;
 }
@@ -139,9 +141,16 @@ NS_ASSUME_NONNULL_BEGIN
 }
 
 - (NSArray<FIRDocumentChange *> *)documentChanges {
-  if (!_documentChanges) {
-    _documentChanges =
-        [FIRDocumentChange documentChangesForSnapshot:self.snapshot firestore:self.firestore];
+  return [self documentChangesWithIncludeMetadataChanges:NO];
+}
+
+- (NSArray<FIRDocumentChange *> *)documentChangesWithIncludeMetadataChanges:
+    (BOOL)includeMetadataChanges {
+  if (!_documentChanges || _documentChangesIncludeMetadataChanges != includeMetadataChanges) {
+    _documentChanges = [FIRDocumentChange documentChangesForSnapshot:self.snapshot
+                                              includeMetadataChanges:includeMetadataChanges
+                                                           firestore:self.firestore];
+    _documentChangesIncludeMetadataChanges = includeMetadataChanges;
   }
   return _documentChanges;
 }
diff --git a/Firestore/Source/Public/FIRQuery.h b/Firestore/Source/Public/FIRQuery.h
index ff15ac6..a28af39 100644
--- a/Firestore/Source/Public/FIRQuery.h
+++ b/Firestore/Source/Public/FIRQuery.h
@@ -25,46 +25,6 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/**
- * Options for use with `[FIRQuery addSnapshotListener]` to control the behavior of the snapshot
- * listener.
- */
-NS_SWIFT_NAME(QueryListenOptions)
-@interface FIRQueryListenOptions : NSObject
-
-+ (instancetype)options NS_SWIFT_UNAVAILABLE("Use initializer");
-
-- (instancetype)init;
-
-@property(nonatomic, assign, readonly) BOOL includeQueryMetadataChanges;
-
-/**
- * Sets the includeQueryMetadataChanges option which controls whether metadata-only changes on the
- * query (i.e. only `FIRQuerySnapshot.metadata` changed) should trigger snapshot events. Default is
- * NO.
- *
- * @param includeQueryMetadataChanges Whether to raise events for metadata-only changes on the
- *     query.
- * @return The receiver is returned for optional method chaining.
- */
-- (instancetype)includeQueryMetadataChanges:(BOOL)includeQueryMetadataChanges
-    NS_SWIFT_NAME(includeQueryMetadataChanges(_:));
-
-@property(nonatomic, assign, readonly) BOOL includeDocumentMetadataChanges;
-
-/**
- * Sets the includeDocumentMetadataChanges option which controls whether document metadata-only
- * changes (i.e. only `FIRDocumentSnapshot.metadata` on a document contained in the query
- * changed) should trigger snapshot events. Default is NO.
- *
- * @param includeDocumentMetadataChanges Whether to raise events for document metadata-only changes.
- * @return The receiver is returned for optional method chaining.
- */
-- (instancetype)includeDocumentMetadataChanges:(BOOL)includeDocumentMetadataChanges
-    NS_SWIFT_NAME(includeDocumentMetadataChanges(_:));
-
-@end
-
 typedef void (^FIRQuerySnapshotBlock)(FIRQuerySnapshot *_Nullable snapshot,
                                       NSError *_Nullable error);
 
@@ -103,16 +63,17 @@ NS_SWIFT_NAME(Query)
 /**
  * Attaches a listener for QuerySnapshot events.
  *
- * @param options Options controlling the listener behavior.
+ * @param includeMetadataChanges Whether metadata-only changes (i.e. only
+ *     `FIRDocumentSnapshot.metadata` changed) should trigger snapshot events.
  * @param listener The listener to attach.
  *
  * @return A FIRListenerRegistration that can be used to remove this listener.
  */
 // clang-format off
-- (id<FIRListenerRegistration>)addSnapshotListenerWithOptions:
-                                   (nullable FIRQueryListenOptions *)options
-                                                     listener:(FIRQuerySnapshotBlock)listener
-    NS_SWIFT_NAME(addSnapshotListener(options:listener:));
+- (id<FIRListenerRegistration>)
+addSnapshotListenerWithIncludeMetadataChanges:(BOOL)includeMetadataChanges
+                                     listener:(FIRQuerySnapshotBlock)listener
+    NS_SWIFT_NAME(addSnapshotListener(includeMetadataChanges:listener:));
 // clang-format on
 
 #pragma mark - Filtering Data
diff --git a/Firestore/Source/Public/FIRQuerySnapshot.h b/Firestore/Source/Public/FIRQuerySnapshot.h
index 1266832..6a7e60d 100644
--- a/Firestore/Source/Public/FIRQuerySnapshot.h
+++ b/Firestore/Source/Public/FIRQuerySnapshot.h
@@ -58,6 +58,16 @@ NS_SWIFT_NAME(QuerySnapshot)
  */
 @property(nonatomic, strong, readonly) NSArray<FIRDocumentChange *> *documentChanges;
 
+/**
+ * Returns an array of the documents that changed since the last snapshot. If this is the first
+ * snapshot, all documents will be in the list as Added changes.
+ *
+ * @param includeMetadataChanges Whether metadata-only changes (i.e. only
+ *     `FIRDocumentSnapshot.metadata` changed) should be included.
+ */
+- (NSArray<FIRDocumentChange *> *)documentChangesWithIncludeMetadataChanges:
+    (BOOL)includeMetadataChanges NS_SWIFT_NAME(documentChanges(includeMetadataChanges:));
+
 @end
 
 NS_ASSUME_NONNULL_END