Add async/await helper for CollectionReference.add()/Firestore.loadBundle() (#9130)

Author: schmidt-sebastian

Firestore/Example/Firestore.xcodeproj/project.pbxproj

@@ -34,6 +34,9 @@
 		056542AD1D0F78E29E22EFA9 /* grpc_connection_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = B6D9649021544D4F00EB9CFB /* grpc_connection_test.cc */; };
 		0575F3004B896D94456A74CE /* status_testing.cc in Sources */ = {isa = PBXBuildFile; fileRef = 3CAA33F964042646FDDAF9F9 /* status_testing.cc */; };
 		05D99904EA713414928DD920 /* query_listener_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = 7C3F995E040E9E9C5E8514BB /* query_listener_test.cc */; };
+		062072B72773A055001655D7 /* AsyncAwaitIntegrationTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 062072B62773A055001655D7 /* AsyncAwaitIntegrationTests.swift */; };
+		062072B82773A055001655D7 /* AsyncAwaitIntegrationTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 062072B62773A055001655D7 /* AsyncAwaitIntegrationTests.swift */; };
+		062072B92773A055001655D7 /* AsyncAwaitIntegrationTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 062072B62773A055001655D7 /* AsyncAwaitIntegrationTests.swift */; };
 		06485D6DA8F64757D72636E1 /* leveldb_target_cache_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = E76F0CDF28E5FA62D21DE648 /* leveldb_target_cache_test.cc */; };
 		06A3926F89C847846BE4D6BE /* http.pb.cc in Sources */ = {isa = PBXBuildFile; fileRef = 618BBE9720B89AAC00B5BCE7 /* http.pb.cc */; };
 		06BCEB9C65DFAA142F3D3F0B /* view_testing.cc in Sources */ = {isa = PBXBuildFile; fileRef = A5466E7809AD2871FFDE6C76 /* view_testing.cc */; };
@@ -1319,6 +1322,7 @@
 		01D10113ECC5B446DB35E96D /* byte_stream_cpp_test.cc */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.cpp.cpp; path = byte_stream_cpp_test.cc; sourceTree = "<group>"; };
 		045D39C4A7D52AF58264240F /* remote_document_cache_test.h */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.c.h; path = remote_document_cache_test.h; sourceTree = "<group>"; };
 		0473AFFF5567E667A125347B /* ordered_code_benchmark.cc */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.cpp.cpp; path = ordered_code_benchmark.cc; sourceTree = "<group>"; };
+		062072B62773A055001655D7 /* AsyncAwaitIntegrationTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AsyncAwaitIntegrationTests.swift; sourceTree = "<group>"; };
 		0840319686A223CC4AD3FAB1 /* leveldb_remote_document_cache_test.cc */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.cpp.cpp; path = leveldb_remote_document_cache_test.cc; sourceTree = "<group>"; };
 		0EE5300F8233D14025EF0456 /* string_apple_test.mm */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.cpp.objcpp; path = string_apple_test.mm; sourceTree = "<group>"; };
 		11984BA0A99D7A7ABA5B0D90 /* Pods-Firestore_Example_iOS-Firestore_SwiftTests_iOS.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Firestore_Example_iOS-Firestore_SwiftTests_iOS.release.xcconfig"; path = "Pods/Target Support Files/Pods-Firestore_Example_iOS-Firestore_SwiftTests_iOS/Pods-Firestore_Example_iOS-Firestore_SwiftTests_iOS.release.xcconfig"; sourceTree = "<group>"; };
@@ -1792,6 +1796,7 @@
 		124C932A22C1635300CA8C2D /* Integration */ = {
 			isa = PBXGroup;
 			children = (
+				062072B62773A055001655D7 /* AsyncAwaitIntegrationTests.swift */,
 				124C932B22C1642C00CA8C2D /* CodableIntegrationTests.swift */,
 			);
 			path = Integration;
@@ -3783,6 +3788,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				062072B92773A055001655D7 /* AsyncAwaitIntegrationTests.swift in Sources */,
 				733AFC467B600967536BD70F /* BasicCompileTests.swift in Sources */,
 				79987AF2DF1FCE799008B846 /* CodableGeoPointTests.swift in Sources */,
 				1C79AE3FBFC91800E30D092C /* CodableIntegrationTests.swift in Sources */,
@@ -3986,6 +3992,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				062072B82773A055001655D7 /* AsyncAwaitIntegrationTests.swift in Sources */,
 				B896E5DE1CC27347FAC009C3 /* BasicCompileTests.swift in Sources */,
 				722F9A798F39F7D1FE7CF270 /* CodableGeoPointTests.swift in Sources */,
 				CF5DE1ED21DD0A9783383A35 /* CodableIntegrationTests.swift in Sources */,
@@ -4408,6 +4415,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				062072B72773A055001655D7 /* AsyncAwaitIntegrationTests.swift in Sources */,
 				F731A0CCD0220B370BC1BE8B /* BasicCompileTests.swift in Sources */,
 				7C5E017689012489AAB7718D /* CodableGeoPointTests.swift in Sources */,
 				54C3242322D3B627000FE6DD /* CodableIntegrationTests.swift in Sources */,

Firestore/Swift/CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+- [added] Added async wrapper for `CollectionReference.addDocument()` and
+  `Firestore.loadBundle()`.
+
 # v8.9.0
 - [added] Added `@FirestoreQuery` property wrapper for querying data from a
   Firestore collection.

Firestore/Swift/Source/AsyncAwait/CollectionReference+AsyncAwait.swift

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import FirebaseFirestore
+import Foundation
+
+#if compiler(>=5.5) && canImport(_Concurrency)
+  @available(iOS 15, tvOS 15, macOS 12, watchOS 8, *)
+  public extension CollectionReference {
+    /// Adds a new document to this collection with the specified data, assigning it a document ID
+    /// automatically.
+    /// - Parameter data: A `Dictionary` containing the data for the new document.
+    /// - Throws: `Error` if the backend rejected the write.
+    /// - Returns: A `DocumentReference` pointing to the newly created document.
+    func addDocument(data: [String: Any]) async throws -> DocumentReference {
+      return try await withCheckedThrowingContinuation { continuation in
+        var document: DocumentReference?
+        document = self.addDocument(data: data) { error in
+          if let err = error {
+            continuation.resume(throwing: err)
+          } else {
+            // Our callbacks guarantee that we either return an error or a document.
+            continuation.resume(returning: document!)
+          }
+        }
+      }
+    }
+  }
+#endif

Firestore/Swift/Source/AsyncAwait/Firestore+AsyncAwait.swift

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import FirebaseFirestore
+import Foundation
+
+#if compiler(>=5.5) && canImport(_Concurrency)
+  @available(iOS 15, tvOS 15, macOS 12, watchOS 8, *)
+  public extension Firestore {
+    /// Loads a Firestore bundle into the local cache.
+    /// - Parameter bundleData: Data from the bundle to be loaded.
+    /// - Throws: `Error` if the bundle data cannot be parsed.
+    /// - Returns: The final `LoadBundleTaskProgress` that contains the total number of documents loaded.
+    func loadBundle(_ bundleData: Data) async throws -> LoadBundleTaskProgress {
+      return try await withCheckedThrowingContinuation { continuation in
+        self.loadBundle(bundleData) { progress, error in
+          if let err = error {
+            continuation.resume(throwing: err)
+          } else {
+            // Our callbacks guarantee that we either return an error or a progress event.
+            continuation.resume(returning: progress!)
+          }
+        }
+      }
+    }
+
+    /// Loads a Firestore bundle into the local cache.
+    /// - Parameter bundleStream: An input stream from which the bundle can be read.
+    /// - Throws: `Error` if the bundle stream cannot be parsed.
+    /// - Returns: The final `LoadBundleTaskProgress` that contains the total number of documents loaded.
+    func loadBundle(_ bundleStream: InputStream) async throws -> LoadBundleTaskProgress {
+      return try await withCheckedThrowingContinuation { continuation in
+        self.loadBundle(bundleStream) { progress, error in
+          if let err = error {
+            continuation.resume(throwing: err)
+          } else {
+            // Our callbacks guarantee that we either return an error or a progress event.
+            continuation.resume(returning: progress!)
+          }
+        }
+      }
+    }
+  }
+#endif

Firestore/Swift/Tests/API/BasicCompileTests.swift

@@ -472,3 +472,37 @@ func terminateDb(database db: Firestore) {
     }
   }
 }
+
+#if swift(>=5.5)
+  @available(iOS 15, tvOS 15, macOS 12, watchOS 8, *)
+  func testAsyncAwait(database db: Firestore) async throws {
+    try await db.enableNetwork()
+    try await db.disableNetwork()
+    try await db.waitForPendingWrites()
+    try await db.clearPersistence()
+    try await db.terminate()
+    try await db.runTransaction { _, _ in
+      0
+    }
+
+    let batch = db.batch()
+    try await batch.commit()
+
+    _ = await db.getQuery(named: "foo")
+    _ = try await db.loadBundle(Data())
+
+    let collection = db.collection("coll")
+    try await collection.getDocuments()
+    try await collection.getDocuments(source: FirestoreSource.default)
+
+    let document = try await collection.addDocument(data: [:])
+
+    try await document.setData([:])
+    try await document.setData([:], merge: true)
+    try await document.setData([:], mergeFields: [])
+    try await document.updateData([:])
+    try await document.delete()
+    try await document.getDocument()
+    try await document.getDocument(source: FirestoreSource.default)
+  }
+#endif

Firestore/Swift/Tests/Integration/AsyncAwaitIntegrationTests.swift

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import FirebaseFirestore
+import FirebaseFirestoreSwift
+import Foundation
+
+let emptyBundle = """
+{\
+   "metadata":{\
+      "id":"test",\
+      "createTime":{\
+         "seconds":0,\
+         "nanos":0\
+      },\
+      "version":1,\
+      "totalDocuments":0,\
+      "totalBytes":0\
+   }\
+}
+"""
+
+#if swift(>=5.5)
+  @available(iOS 15, tvOS 15, macOS 12, watchOS 8, *)
+  class AsyncAwaitIntegrationTests: FSTIntegrationTestCase {
+    func testAddData() async throws {
+      let collection = collectionRef()
+      let document = try await collection.addDocument(data: [:])
+      let snapshot = try await document.getDocument()
+      XCTAssertTrue(snapshot.exists)
+    }
+
+    func testLoadBundleFromData() async throws {
+      let bundle = "\(emptyBundle.count)\(emptyBundle)"
+      let bundleProgress = try await db.loadBundle(Data(bundle.utf8))
+      XCTAssertEqual(LoadBundleTaskState.success, bundleProgress.state)
+    }
+
+    func testLoadBundleFromEmptyDataFails() async throws {
+      do {
+        _ = try await db.loadBundle(Data())
+        XCTFail("Bundle loading should have failed")
+      } catch {
+        XCTAssertEqual((error as NSError).domain, FirestoreErrorDomain)
+        XCTAssertEqual((error as NSError).code, FirestoreErrorCode.unknown.rawValue)
+      }
+    }
+
+    func testLoadBundleFromStream() async throws {
+      let bundle = "\(emptyBundle.count)\(emptyBundle)"
+      let bundleProgress = try await db
+        .loadBundle(InputStream(data: bundle.data(using: String.Encoding.utf8)!))
+      XCTAssertEqual(LoadBundleTaskState.success, bundleProgress.state)
+    }
+  }
+#endif

SwiftDashboard.md

@@ -11,7 +11,7 @@ tasks for additional Swift improvements.
 |   :---                | :--- | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: | :----: |
 | **Swift Library**     | ❌   |   ✔   | ❌     |❌     | ❌     | ❌     | ❌      |  ✔     |  ✔    | 1      |  ✔     | ❌    | ❌     | ✔      | ❌     | ❌    | ✔     |
 | **API Tests**         | ❌   |  ❌    |  ✔    |❌     | ❌     | ✔       | ❌     | 3      | 2     |  ✔     | 2      | ✔      | 2     | 2      | ❌    |  ✔     | ✔    |
-| **async/await**       | ❌   |  n/a   |  ✔    |❌     | ❌     |  ✔      | ❌     | 3     | ❌     |  ✔     | ❌     | ❌    | ✔     | ❌    | ❌     |  ✔    | ✔    |
+| **async/await**       | ❌   |  n/a   |  ✔    |❌     | ❌     |  ✔      | ❌     | 3     | ✔     |  ✔     | ❌     | ❌    | ✔     | ❌    | ❌     |  ✔    | ✔    |
 | **Swift Errors**      |  ❌  |  ❌    | ❌    |❌     | 4      | ❌     | ❌     | ❌     | ❌    | ❌     | ❌     | ❌    | ❌     | ✔      | ❌     | ❌   | 5   |
 | **Codable**           | n/a  | n/a     | n/a   |n/a    | n/a     | n/a    |n/a     |  ✔     |  ✔     | 1      | n/a     | n/a   | ❌     | n/a    | n/a    |  ❌  |n/a   |
 | **SwiftUI Lifecycle** | n/a  |  ❌    | n/a    |❌     | ❌     | n/a    |n/a     | n/a    | n/a    | n/a     | n/a    | n/a   | ❌     | n/a    | n/a    | n/a   |n/a  |