Add DocumentSnapshot.data(as:with:decoder:) (#6334)

This adds support for specifying alternative server timestamp behaviors
when decoding snapshots.

Fixes #6328.

Author: wilhuff

Firestore/Example/Tests/Util/XCTestCase+Await.h

@@ -44,6 +44,12 @@ typedef void (^FSTVoidErrorBlock)(NSError *_Nullable error);
  */
 - (void)awaitExpectation:(XCTestExpectation *)expectation;
 
+/**
+ * Await specific expectations with a reasonable timeout. If the expectation fails, XCTFail the
+ * test.
+ */
+- (void)awaitExpectations:(NSArray<XCTestExpectation *> *)expectations;
+
 /**
  * Returns a reasonable timeout for testing against Firestore.
  */

Firestore/Example/Tests/Util/XCTestCase+Await.mm

@@ -40,6 +40,10 @@ - (void)awaitExpectation:(XCTestExpectation *)expectation {
   [self waitForExpectations:@[ expectation ] timeout:kExpectationWaitSeconds];
 }
 
+- (void)awaitExpectations:(NSArray<XCTestExpectation *> *)expectations {
+  [self waitForExpectations:expectations timeout:kExpectationWaitSeconds];
+}
+
 - (double)defaultExpectationWaitSeconds {
   return kExpectationWaitSeconds;
 }

Firestore/Swift/CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+- [feature] Added support for specifying `ServerTimestampBehavior` when
+  decoding a `DocumentSnapshot`.
+
 # v0.4
 - [feature] Added conditional conformance to the `Hashable` protocol for the
   `@DocumentID`, `@ExplicitNull`, and `@ServerTimestamp` property wrappers.

Firestore/Swift/Source/Codable/DocumentSnapshot+ReadDecodable.swift

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Google
+ * Copyright 2019 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,20 +21,24 @@ extension DocumentSnapshot {
   /// Retrieves all fields in a document and converts them to an instance of
   /// caller-specified type. Returns `nil` if the document does not exist.
   ///
+  /// By default, server-provided timestamps that have not yet been set to their
+  /// final value will be returned as `NSNull`. Pass `serverTimestampBehavior`
+  /// configure this behavior.
+  ///
   /// See `Firestore.Decoder` for more details about the decoding process.
   ///
   /// - Parameters
   ///   - type: The type to convert the document fields to.
+  ///   - serverTimestampBehavior: Configures how server timestamps that have
+  ///     not yet been set to their final value are returned from the snapshot.
   ///   - decoder: The decoder to use to convert the document. `nil` to use
-  ///              default decoder.
+  ///     default decoder.
   public func data<T: Decodable>(as type: T.Type,
+                                 with serverTimestampBehavior: ServerTimestampBehavior = .none,
                                  decoder: Firestore.Decoder? = nil) throws -> T? {
-    var d = decoder
-    if d == nil {
-      d = Firestore.Decoder()
-    }
-    if let data = data() {
-      return try d?.decode(T.self, from: data, in: reference)
+    let d = decoder ?? Firestore.Decoder()
+    if let data = data(with: serverTimestampBehavior) {
+      return try d.decode(T.self, from: data, in: reference)
     }
     return nil
   }

Firestore/Swift/Tests/Integration/CodableIntegrationTests.swift

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019 Google
+ * Copyright 2019 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -122,6 +122,45 @@ class CodableIntegrationTests: FSTIntegrationTestCase {
         }
       }
     }
+
+    func testServerTimestampBehavior() throws {
+      struct Model: Codable, Equatable {
+        var name: String
+        @ServerTimestamp var ts: Timestamp? = nil
+      }
+
+      disableNetwork()
+      let docToWrite = documentRef()
+      let now = Int64(Date().timeIntervalSince1970)
+      let pastTimestamp = Timestamp(seconds: 807_940_800, nanoseconds: 0)
+
+      // Write a document with a current value to enable testing with .previous.
+      let originalModel = Model(name: "name", ts: pastTimestamp)
+      let completion1 = completionForExpectation(withName: "setData")
+      try docToWrite.setData(from: originalModel, completion: completion1)
+
+      // Overwrite with a nil server timestamp so that ServerTimestampBehavior is testable.
+      let newModel = Model(name: "name")
+      let completion2 = completionForExpectation(withName: "setData")
+      try docToWrite.setData(from: newModel, completion: completion2)
+
+      let snapshot = readDocument(forRef: docToWrite)
+      var decoded = try snapshot.data(as: Model.self, with: .none)
+      XCTAssertNil(decoded?.ts)
+
+      decoded = try snapshot.data(as: Model.self, with: .estimate)
+      XCTAssertNotNil(decoded?.ts)
+      XCTAssertNotNil(decoded?.ts?.seconds)
+      XCTAssertGreaterThanOrEqual(decoded!.ts!.seconds, now)
+
+      decoded = try snapshot.data(as: Model.self, with: .previous)
+      XCTAssertNotNil(decoded?.ts)
+      XCTAssertNotNil(decoded?.ts?.seconds)
+      XCTAssertEqual(decoded!.ts!.seconds, pastTimestamp.seconds)
+
+      enableNetwork()
+      awaitExpectations()
+    }
   #endif // swift(>=5.1)
 
   @available(swift, deprecated: 5.1)