Add a flag to control whether DocumentSnapshots return Dates or Timestamps for timestamp fields (#831)

* add a new property `timestampsInSnapshotsEnabled` to `FirestoreSettings`, `false` by default;
* add a verbose warning message urging users to opt into the new behavior;
* set `timestampsInSnapshotsEnabled` to true in the integration tests to reduce the verbose console
spam during the test run and make sure the flag won't break anything once it's flipped.

2 files changed, 18 insertions, 1 deletions

diff --git a/Firestore/Source/Public/FIRFirestoreSettings.h b/Firestore/Source/Public/FIRFirestoreSettings.h
index 7a1f2a3..cd3f91c 100644
--- a/Firestore/Source/Public/FIRFirestoreSettings.h
+++ b/Firestore/Source/Public/FIRFirestoreSettings.h
@@ -44,6 +44,23 @@ NS_SWIFT_NAME(FirestoreSettings)
 /** Set to false to disable local persistent storage. */
 @property(nonatomic, getter=isPersistenceEnabled) BOOL persistenceEnabled;
 
+/**
+ * Enables the use of FIRTimestamps for timestamp fields in FIRDocumentSnapshots.
+ *
+ * Currently, Firestore returns timestamp fields as an NSDate but NSDate is implemented as a double
+ * which loses precision and causes unexpected behavior when using a timestamp from a snapshot as
+ * a part of a subsequent query.
+ *
+ * Setting timestampsInSnapshotsEnabled to true will cause Firestore to return FIRTimestamp values
+ * instead of NSDate, avoiding this kind of problem. To make this work you must also change any code
+ * that uses NSDate to use FIRTimestamp instead.
+ *
+ * NOTE: in the future timestampsInSnapshotsEnabled = true will become the default and this option
+ * will be removed so you should change your code to use FIRTimestamp now and opt-in to this new
+ * behavior as soon as you can.
+ */
+@property(nonatomic, getter=areTimestampsInSnapshotsEnabled) BOOL timestampsInSnapshotsEnabled;
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/Firestore/Source/Public/FIRTimestamp.h b/Firestore/Source/Public/FIRTimestamp.h
index d0a77f3..bf4aff4 100644
--- a/Firestore/Source/Public/FIRTimestamp.h
+++ b/Firestore/Source/Public/FIRTimestamp.h
@@ -60,7 +60,7 @@ NS_SWIFT_NAME(Timestamp)
 + (instancetype)timestamp;
 
 /** Returns a new NSDate corresponding to this timestamp. This may lose precision. */
-- (NSDate *)approximateDateValue;
+- (NSDate *)dateValue;
 
 - (NSComparisonResult)compare:(FIRTimestamp *)other;