FieldValue and DocumentReference codable support. (#3231)

* working serverTimestamp

* working FieldValue. Still need: document ref and ability to Eq of FieldValue

* DocumentReference implemented and testing works

* clean up header search path

* improving FieldValue enum comments

* run through formatting

* addressing comments

* formatted with swiftformat 0.35.7

* add missing bool->BOOL change

* undo unintended swift version change

* remove unwanted proj file change

Author: Hui-Wu

Firestore/Example/Firestore.xcodeproj/project.pbxproj

@@ -60,11 +60,14 @@
 		113190791F42202FDE1ABC14 /* FIRQuerySnapshotTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E04F202154AA00B64F25 /* FIRQuerySnapshotTests.mm */; };
 		11F8EE69182C9699E90A9E3D /* database_info_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = AB38D92E20235D22000A432D /* database_info_test.cc */; };
 		12158DFCEE09D24B7988A340 /* maybe_document.pb.cc in Sources */ = {isa = PBXBuildFile; fileRef = 618BBE7E20B89AAC00B5BCE7 /* maybe_document.pb.cc */; };
+		1235769322B7E99F007DDFA9 /* EncodableFieldValueTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1235769122B7E915007DDFA9 /* EncodableFieldValueTests.swift */; };
 		1235769522B86E65007DDFA9 /* FirestoreEncoderTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1235769422B86E65007DDFA9 /* FirestoreEncoderTests.swift */; };
 		127CC0D222B3ADDC00A3E42A /* CodableTimestampTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7B65C996438B84DBC7616640 /* CodableTimestampTests.swift */; };
 		1291D9F5300AFACD1FBD262D /* array_sorted_map_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = 54EB764C202277B30088B8F3 /* array_sorted_map_test.cc */; };
 		12BB9ED1CA98AA52B92F497B /* log_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = 54C2294E1FECABAE007D065B /* log_test.cc */; };
 		12DB753599571E24DCED0C2C /* FIRValidationTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E06D202154D600B64F25 /* FIRValidationTests.mm */; };
+		12E62D5722BBC41A0074F412 /* FSTAPIHelpers.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E04E202154AA00B64F25 /* FSTAPIHelpers.mm */; };
+		12E62D5822BBC6EF0074F412 /* FSTHelpers.mm in Sources */ = {isa = PBXBuildFile; fileRef = 5492E03A2021401F00B64F25 /* FSTHelpers.mm */; };
 		132E3483789344640A52F223 /* reference_set_test.cc in Sources */ = {isa = PBXBuildFile; fileRef = 132E32997D781B896672D30A /* reference_set_test.cc */; };
 		132E3E53179DE287D875F3F2 /* FSTLevelDBTransactionTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 132E36BB104830BD806351AC /* FSTLevelDBTransactionTests.mm */; };
 		132E3EE56C143B2C9ACB6187 /* FSTLevelDBBenchmarkTests.mm in Sources */ = {isa = PBXBuildFile; fileRef = 132E3BB3D5C42282B4ACFB20 /* FSTLevelDBBenchmarkTests.mm */; };
@@ -753,6 +756,7 @@
 		0473AFFF5567E667A125347B /* ordered_code_benchmark.cc */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = sourcecode.cpp.cpp; path = ordered_code_benchmark.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>"; };
+		1235769122B7E915007DDFA9 /* EncodableFieldValueTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = EncodableFieldValueTests.swift; sourceTree = "<group>"; };
 		1235769422B86E65007DDFA9 /* FirestoreEncoderTests.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = FirestoreEncoderTests.swift; sourceTree = "<group>"; };
 		1277F98C20D2DF0867496976 /* Pods-Firestore_IntegrationTests_iOS.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Firestore_IntegrationTests_iOS.debug.xcconfig"; path = "Pods/Target Support Files/Pods-Firestore_IntegrationTests_iOS/Pods-Firestore_IntegrationTests_iOS.debug.xcconfig"; sourceTree = "<group>"; };
 		12F4357299652983A615F886 /* LICENSE */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text; name = LICENSE; path = ../LICENSE; sourceTree = "<group>"; };
@@ -1354,6 +1358,7 @@
 			children = (
 				5495EB022040E90200EBA509 /* CodableGeoPointTests.swift */,
 				7B65C996438B84DBC7616640 /* CodableTimestampTests.swift */,
+				1235769122B7E915007DDFA9 /* EncodableFieldValueTests.swift */,
 				1235769422B86E65007DDFA9 /* FirestoreEncoderTests.swift */,
 			);
 			path = Codable;
@@ -3394,6 +3399,9 @@
 				544A20EE20F6C10C004E52CD /* BasicCompileTests.swift in Sources */,
 				5495EB032040E90200EBA509 /* CodableGeoPointTests.swift in Sources */,
 				127CC0D222B3ADDC00A3E42A /* CodableTimestampTests.swift in Sources */,
+				1235769322B7E99F007DDFA9 /* EncodableFieldValueTests.swift in Sources */,
+				12E62D5722BBC41A0074F412 /* FSTAPIHelpers.mm in Sources */,
+				12E62D5822BBC6EF0074F412 /* FSTHelpers.mm in Sources */,
 				1235769522B86E65007DDFA9 /* FirestoreEncoderTests.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -4381,13 +4389,19 @@
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				GCC_C_LANGUAGE_STANDARD = c99;
 				GCC_NO_COMMON_BLOCKS = YES;
+				HEADER_SEARCH_PATHS = (
+					"$(inherited)",
+					"\"${PODS_ROOT}/../../..\"",
+					"\"${PODS_ROOT}/../../../Firestore/third_party/abseil-cpp\"",
+				);
 				INFOPLIST_FILE = ../Swift/Tests/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = 11.2;
 				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks @loader_path/Frameworks";
 				MTL_ENABLE_DEBUG_INFO = YES;
 				PRODUCT_BUNDLE_IDENTIFIER = "com.google.Firestore-SwiftTests-iOS";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
+				SWIFT_OBJC_BRIDGING_HEADER = ../Swift/Tests/BridgingHeader.h;
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 				SWIFT_VERSION = 4.0;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -4420,12 +4434,18 @@
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				GCC_C_LANGUAGE_STANDARD = c99;
 				GCC_NO_COMMON_BLOCKS = YES;
+				HEADER_SEARCH_PATHS = (
+					"$(inherited)",
+					"\"${PODS_ROOT}/../../..\"",
+					"\"${PODS_ROOT}/../../../Firestore/third_party/abseil-cpp\"",
+				);
 				INFOPLIST_FILE = ../Swift/Tests/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = 11.2;
 				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks @loader_path/Frameworks";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				PRODUCT_BUNDLE_IDENTIFIER = "com.google.Firestore-SwiftTests-iOS";
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_OBJC_BRIDGING_HEADER = ../Swift/Tests/BridgingHeader.h;
 				SWIFT_OPTIMIZATION_LEVEL = "-Owholemodule";
 				SWIFT_VERSION = 4.0;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -4694,6 +4714,7 @@
 			baseConfigurationReference = 3C81DE3772628FE297055662 /* Pods-Firestore_Example_iOS.debug.xcconfig */;
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CLANG_ENABLE_MODULES = YES;
 				GCC_PRECOMPILE_PREFIX_HEADER = YES;
 				GCC_PREFIX_HEADER = "";
 				HEADER_SEARCH_PATHS = (
@@ -4709,6 +4730,8 @@
 				);
 				PRODUCT_BUNDLE_IDENTIFIER = "org.cocoapods.demo.${PRODUCT_NAME:rfc1034identifier}";
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+				SWIFT_VERSION = 4.0;
 				WRAPPER_EXTENSION = app;
 			};
 			name = Debug;
@@ -4718,6 +4741,7 @@
 			baseConfigurationReference = 3F0992A4B83C60841C52E960 /* Pods-Firestore_Example_iOS.release.xcconfig */;
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CLANG_ENABLE_MODULES = YES;
 				GCC_PRECOMPILE_PREFIX_HEADER = YES;
 				GCC_PREFIX_HEADER = "";
 				HEADER_SEARCH_PATHS = (
@@ -4726,13 +4750,15 @@
 					"\"${PODS_ROOT}/leveldb-library/include\"",
 				);
 				INFOPLIST_FILE = "App/iOS/Firestore-Info.plist";
+				LD_RUNPATH_SEARCH_PATHS = "$(inherited) @executable_path/Frameworks";
 				MODULE_NAME = ExampleApp;
 				OTHER_LDFLAGS = (
 					"$(inherited)",
 					"-all_load",
 				);
 				PRODUCT_BUNDLE_IDENTIFIER = "org.cocoapods.demo.${PRODUCT_NAME:rfc1034identifier}";
 				PRODUCT_NAME = "$(TARGET_NAME)";
+				SWIFT_VERSION = 4.0;
 				WRAPPER_EXTENSION = app;
 			};
 			name = Release;

Firestore/Example/Tests/API/FIRQueryTests.mm

@@ -23,6 +23,7 @@
 #import "Firestore/Source/Core/FSTQuery.h"
 
 #import "Firestore/Example/Tests/API/FSTAPIHelpers.h"
+#import "Firestore/Example/Tests/Util/FSTHelpers.h"
 
 namespace api = firebase::firestore::api;
 

Firestore/Example/Tests/API/FSTAPIHelpers.h

@@ -13,19 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 #import <Foundation/Foundation.h>
 
-#import "Firestore/Example/Tests/Util/FSTHelpers.h"
-
-#include "absl/strings/string_view.h"
-
 @class FIRCollectionReference;
 @class FIRDocumentReference;
 @class FIRDocumentSnapshot;
 @class FIRFirestore;
 @class FIRQuerySnapshot;
 
+/** Allow tests to just use an int literal for versions. */
+typedef int64_t FSTTestSnapshotVersion;
+
 NS_ASSUME_NONNULL_BEGIN
 
 #if __cplusplus
@@ -36,17 +34,17 @@ extern "C" {
 FIRFirestore *FSTTestFirestore();
 
 /** A convenience method for creating a doc snapshot for tests. */
-FIRDocumentSnapshot *FSTTestDocSnapshot(const absl::string_view path,
+FIRDocumentSnapshot *FSTTestDocSnapshot(const char *path,
                                         FSTTestSnapshotVersion version,
                                         NSDictionary<NSString *, id> *_Nullable data,
                                         BOOL hasMutations,
                                         BOOL fromCache);
 
 /** A convenience method for creating a collection reference from a path string. */
-FIRCollectionReference *FSTTestCollectionRef(const absl::string_view path);
+FIRCollectionReference *FSTTestCollectionRef(const char *path);
 
 /** A convenience method for creating a document reference from a path string. */
-FIRDocumentReference *FSTTestDocRef(const absl::string_view path);
+FIRDocumentReference *FSTTestDocRef(const char *path);
 
 /**
  * A convenience method for creating a particular query snapshot for tests.
@@ -63,11 +61,11 @@ FIRDocumentReference *FSTTestDocRef(const absl::string_view path);
  * @returns A query snapshot that consists of both sets of documents.
  */
 FIRQuerySnapshot *FSTTestQuerySnapshot(
-    const absl::string_view path,
+    const char *path,
     NSDictionary<NSString *, NSDictionary<NSString *, id> *> *oldDocs,
     NSDictionary<NSString *, NSDictionary<NSString *, id> *> *docsToAdd,
-    bool hasPendingWrites,
-    bool fromCache);
+    BOOL hasPendingWrites,
+    BOOL fromCache);
 
 #if __cplusplus
 }  // extern "C"

Firestore/Example/Tests/API/FSTAPIHelpers.mm

@@ -24,6 +24,7 @@
 #include <utility>
 #include <vector>
 
+#import "Firestore/Example/Tests/Util/FSTHelpers.h"
 #import "Firestore/Source/API/FIRCollectionReference+Internal.h"
 #import "Firestore/Source/API/FIRDocumentReference+Internal.h"
 #import "Firestore/Source/API/FIRDocumentSnapshot+Internal.h"
@@ -69,7 +70,7 @@
   return sharedInstance;
 }
 
-FIRDocumentSnapshot *FSTTestDocSnapshot(const absl::string_view path,
+FIRDocumentSnapshot *FSTTestDocSnapshot(const char *path,
                                         FSTTestSnapshotVersion version,
                                         NSDictionary<NSString *, id> *_Nullable data,
                                         BOOL hasMutations,
@@ -85,23 +86,23 @@
                                        hasPendingWrites:hasMutations];
 }
 
-FIRCollectionReference *FSTTestCollectionRef(const absl::string_view path) {
+FIRCollectionReference *FSTTestCollectionRef(const char *path) {
   return [[FIRCollectionReference alloc] initWithPath:testutil::Resource(path)
                                             firestore:FSTTestFirestore().wrapped];
 }
 
-FIRDocumentReference *FSTTestDocRef(const absl::string_view path) {
+FIRDocumentReference *FSTTestDocRef(const char *path) {
   return [[FIRDocumentReference alloc] initWithPath:testutil::Resource(path)
                                           firestore:FSTTestFirestore().wrapped];
 }
 
 /** A convenience method for creating a query snapshots for tests. */
 FIRQuerySnapshot *FSTTestQuerySnapshot(
-    const absl::string_view path,
+    const char *path,
     NSDictionary<NSString *, NSDictionary<NSString *, id> *> *oldDocs,
     NSDictionary<NSString *, NSDictionary<NSString *, id> *> *docsToAdd,
-    bool hasPendingWrites,
-    bool fromCache) {
+    BOOL hasPendingWrites,
+    BOOL fromCache) {
   SnapshotMetadata metadata(hasPendingWrites, fromCache);
   DocumentSet oldDocuments = FSTTestDocSet(DocumentComparator::ByKey(), @[]);
   DocumentKeySet mutatedKeys;
@@ -132,7 +133,7 @@
                             oldDocuments,
                             std::move(documentChanges),
                             mutatedKeys,
-                            fromCache,
+                            static_cast<bool>(fromCache),
                             /*sync_state_changed=*/true,
                             /*excludes_metadata_changes=*/false};
   return [[FIRQuerySnapshot alloc] initWithFirestore:FSTTestFirestore().wrapped

Firestore/Swift/Source/Codable/CodablePassThroughTypes.swift

@@ -20,5 +20,7 @@ import FirebaseFirestore
 internal func isFirestorePassthroughType<T: Any>(_ value: T) -> Bool {
   return
     T.self == GeoPoint.self ||
-    T.self == Timestamp.self
+    T.self == Timestamp.self ||
+    T.self == FieldValue.self ||
+    T.self == DocumentReference.self
 }

Firestore/Swift/Source/Codable/DocumentReference+Codable.swift

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2019 Google
+ *
+ * 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
+
+/** Mark DocumentReference to conform to Codable. */
+
+/**
+ * A protocol describing the encodable properties of a DocumentReference.
+ *
+ * Note: this protocol exists as a workaround for the Swift compiler: if the DocumentReference class
+ * was extended directly to conform to Codable, the methods implementing the protocol would be need
+ * to be marked required but that can't be done in an extension. Declaring the extension on the
+ * protocol sidesteps this issue.
+ */
+private protocol CodableDocumentReference: Codable {}
+
+/**
+ * DocumentReference's codable implmentation will just throw for most
+ * encoder/decoder however. It is only meant to be encoded by FirestoreEncoder/FirestoreDecoder.
+ */
+extension CodableDocumentReference {
+  public init(from decoder: Decoder) throws {
+    throw FirestoreDecodingError.decodingIsNotSupported
+  }
+
+  public func encode(to encoder: Encoder) throws {
+    throw FirestoreEncodingError.encodingIsNotSupported
+  }
+}
+
+extension DocumentReference: CodableDocumentReference {}

Firestore/Swift/Source/Codable/FieldValue+Encodable.swift

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2019 Google
+ *
+ * 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
+
+/** Extends FieldValue to conform to Encodable. */
+extension FieldValue: Encodable {
+  /// Encoding a FieldValue will throw by default unless the encoder implementation
+  /// explicitly handles it, which is what FirestoreEncoder does.
+  public func encode(to encoder: Encoder) throws {
+    throw FirestoreEncodingError.encodingIsNotSupported
+  }
+}
+
+/** Swift enums providing alternatives to direct usages of FieldValue. */
+
+/// Wraps around Timestamp and FieldValue.serverTimestamp to support modeling
+/// timestamps in custom classes.
+///
+/// Example:
+/// struct CustomModel {
+///   var ts: ServerTimestamp
+/// }
+/// Then `CustomModel(ts: .pending)` will tell server to fill `ts` with current
+/// timestamp.
+public enum ServerTimestamp: Codable, Equatable {
+  /// When being read (decoded) from Firestore, NSNull values will be mapped to `pending`.
+  /// When being written (encoded) to Firestore, `pending` means requesting server to
+  /// set timestamp on the field (essentially setting value
+  /// to FieldValue.serverTimestamp()).
+  case pending
+
+  /// When being read (decoded) from Firestore, non-nil Timestamp will be mapped to
+  /// `resolved`.
+  /// When being written (encoded) to Firestore, `resolved(stamp)` will set the field
+  /// value to `stamp`.
+  case resolved(Timestamp)
+
+  public init(from decoder: Decoder) throws {
+    let container = try decoder.singleValueContainer()
+    if container.decodeNil() {
+      self = .pending
+    } else {
+      let value = try container.decode(Timestamp.self)
+      self = .resolved(value)
+    }
+  }
+
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case .pending:
+      try container.encode(FieldValue.serverTimestamp())
+    case let .resolved(value: value):
+      try container.encode(value)
+    }
+  }
+}

Firestore/Swift/Source/Codable/third_party/FirestoreDecoder.swift

@@ -1033,7 +1033,7 @@ extension _FirestoreDecoder {
       }
     }
 
-    // Decoding an embeded container, this requires expanding the storage stack and
+    // Decoding an embedded container, this requires expanding the storage stack and
     // then restore after decoding.
     storage.push(container: value)
     let decoded = try T(from: self)

Firestore/Swift/Source/Codable/third_party/FirestoreEncoder.swift

@@ -35,6 +35,10 @@ extension Firestore {
     /// - Returns: A Map keyed by String representing a document Firestore
     ///            API can work with.
     public func encode<T: Encodable>(_ value: T) throws -> [String: Any] {
+      // DocumentReference and FieldValue cannot be encoded directly.
+      guard T.self != DocumentReference.self && T.self != FieldValue.self else {
+        throw FirestoreEncodingError.encodingIsNotSupported
+      }
       guard let topLevel = try _FirestoreEncoder().box_(value) else {
         throw EncodingError.invalidValue(value,
                                          EncodingError.Context(codingPath: [],
@@ -495,7 +499,7 @@ extension _FirestoreEncoder: SingleValueEncodingContainer {
 }
 
 /// Special subclass of `_FirestoreEncoder` used by `superEncoder`.
-/// It inherits the codingPath from the referencing `_FirestoreEncoder` but uses it's own
+/// It inherits the codingPath from the referencing `_FirestoreEncoder` but uses its own
 /// storage. The encoded result will be written back to the referencing encoder's storage
 /// when it is `deinit`-ed.
 private class _FirestoreReferencingEncoder: _FirestoreEncoder {