Add @documentid equivalent to Swift Codable (#3762)

* Commit with failed optional test case.

* Integration Test and cleanup

* swiftformat

* better doc formatting

* addressing comments

* rename to SelfDocumentID

* Addressing Comments

* fix comment

Author: wu-hui

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

@@ -18,6 +18,8 @@ import Foundation
 
 extension Firestore {
   public struct Decoder {
+    fileprivate static let documentRefUserInfoKey = CodingUserInfoKey(rawValue: "DocumentRefUserInfoKey")
+
     public init() {}
     /// Returns an instance of specified type from a Firestore document.
     ///
@@ -31,9 +33,17 @@ extension Firestore {
     /// - Parameters:
     ///   - A type to decode a document to.
     ///   - container: A Map keyed of String representing a Firestore document.
+    ///   - document: A reference to the Firestore Document that is being
+    ///             decoded.
     /// - Returns: An instance of specified type by the first parameter.
-    public func decode<T: Decodable>(_: T.Type, from container: [String: Any]) throws -> T {
+    public func decode<T: Decodable>(_: T.Type,
+                                     from container: [String: Any],
+                                     in document: DocumentReference? = nil) throws -> T {
       let decoder = _FirestoreDecoder(referencing: container)
+      if let doc = document {
+        decoder.userInfo[Firestore.Decoder.documentRefUserInfoKey!] = doc
+      }
+
       guard let value = try decoder.unbox(container, as: T.self) else {
         throw DecodingError.valueNotFound(
           T.self,
@@ -323,6 +333,24 @@ private struct _FirestoreKeyedDecodingContainer<K: CodingKey>: KeyedDecodingCont
   }
 
   public func decode<T: Decodable>(_: T.Type, forKey key: Key) throws -> T {
+    if T.self == SelfDocumentID.self {
+      let docRef = decoder.userInfo[
+        Firestore.Decoder.documentRefUserInfoKey!
+      ] as! DocumentReference?
+
+      if contains(key) {
+        let docPath = (docRef != nil) ? docRef!.path : "nil"
+        var codingPathCopy = codingPath.map { key in key.stringValue }
+        codingPathCopy.append(key.stringValue)
+
+        throw FirestoreDecodingError.fieldNameConfict("Field name " +
+          "\(codingPathCopy) was found from document \"\(docPath)\", " +
+          "cannot assign the document reference to this field.")
+      }
+
+      return SelfDocumentID(from: docRef) as! T
+    }
+
     let entry = try require(key: key)
 
     decoder.codingPath.append(key)
@@ -978,6 +1006,10 @@ extension _FirestoreDecoder {
 
   func unbox(_ value: Any, as type: Date.Type) throws -> Date? {
     guard !(value is NSNull) else { return nil }
+    // Firestore returns all dates as Timestamp, converting it to Date so it can be used in custom objects.
+    if let timestamp = value as? Timestamp {
+      return timestamp.dateValue()
+    }
     guard let date = value as? Date else {
       throw DecodingError._typeMismatch(at: codingPath, expectation: type, reality: value)
     }

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

@@ -36,8 +36,11 @@ 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 {
+      // SelfDocumentID, DocumentReference and FieldValue cannot be
+      // encoded directly.
+      guard T.self != SelfDocumentID.self,
+        T.self != DocumentReference.self,
+        T.self != FieldValue.self else {
         throw FirestoreEncodingError.encodingIsNotSupported
       }
       guard let topLevel = try _FirestoreEncoder().box_(value) else {
@@ -212,6 +215,11 @@ private struct _FirestoreKeyedEncodingContainer<K: CodingKey>: KeyedEncodingCont
   public mutating func encode(_ value: Double, forKey key: Key) throws { container[key.stringValue] = encoder.box(value) }
 
   public mutating func encode<T: Encodable>(_ value: T, forKey key: Key) throws {
+    // `SelfDocumentID` is ignored during encoding.
+    if T.self == SelfDocumentID.self {
+      return
+    }
+
     encoder.codingPath.append(key)
     defer {
       encoder.codingPath.removeLast()

Firestore/third_party/FirestoreEncoder/FirestoreDecoder.swift

@@ -18,6 +18,8 @@ import Foundation
 
 extension Firestore {
   public struct Decoder {
+    fileprivate static let documentRefUserInfoKey = CodingUserInfoKey(rawValue: "DocumentRefUserInfoKey")
+
     public init() {}
     /// Returns an instance of specified type from a Firestore document.
     ///
@@ -31,9 +33,17 @@ extension Firestore {
     /// - Parameters:
     ///   - A type to decode a document to.
     ///   - container: A Map keyed of String representing a Firestore document.
+    ///   - document: A reference to the Firestore Document that is being
+    ///             decoded.
     /// - Returns: An instance of specified type by the first parameter.
-    public func decode<T: Decodable>(_: T.Type, from container: [String: Any]) throws -> T {
+    public func decode<T: Decodable>(_: T.Type,
+                                     from container: [String: Any],
+                                     in document: DocumentReference? = nil) throws -> T {
       let decoder = _FirestoreDecoder(referencing: container)
+      if let doc = document {
+        decoder.userInfo[Firestore.Decoder.documentRefUserInfoKey!] = doc
+      }
+
       guard let value = try decoder.unbox(container, as: T.self) else {
         throw DecodingError.valueNotFound(
           T.self,
@@ -323,6 +333,24 @@ private struct _FirestoreKeyedDecodingContainer<K: CodingKey>: KeyedDecodingCont
   }
 
   public func decode<T: Decodable>(_: T.Type, forKey key: Key) throws -> T {
+    if T.self == SelfDocumentID.self {
+      let docRef = decoder.userInfo[
+        Firestore.Decoder.documentRefUserInfoKey!
+      ] as! DocumentReference?
+
+      if contains(key) {
+        let docPath = (docRef != nil) ? docRef!.path : "nil"
+        var codingPathCopy = codingPath.map { key in key.stringValue }
+        codingPathCopy.append(key.stringValue)
+
+        throw FirestoreDecodingError.fieldNameConfict("Field name " +
+          "\(codingPathCopy) was found from document \"\(docPath)\", " +
+          "cannot assign the document reference to this field.")
+      }
+
+      return SelfDocumentID(from: docRef) as! T
+    }
+
     let entry = try require(key: key)
 
     decoder.codingPath.append(key)
@@ -978,6 +1006,10 @@ extension _FirestoreDecoder {
 
   func unbox(_ value: Any, as type: Date.Type) throws -> Date? {
     guard !(value is NSNull) else { return nil }
+    // Firestore returns all dates as Timestamp, converting it to Date so it can be used in custom objects.
+    if let timestamp = value as? Timestamp {
+      return timestamp.dateValue()
+    }
     guard let date = value as? Date else {
       throw DecodingError._typeMismatch(at: codingPath, expectation: type, reality: value)
     }

Firestore/third_party/FirestoreEncoder/FirestoreEncoder.swift

@@ -36,8 +36,11 @@ 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 {
+      // SelfDocumentID, DocumentReference and FieldValue cannot be
+      // encoded directly.
+      guard T.self != SelfDocumentID.self,
+        T.self != DocumentReference.self,
+        T.self != FieldValue.self else {
         throw FirestoreEncodingError.encodingIsNotSupported
       }
       guard let topLevel = try _FirestoreEncoder().box_(value) else {
@@ -212,6 +215,11 @@ private struct _FirestoreKeyedEncodingContainer<K: CodingKey>: KeyedEncodingCont
   public mutating func encode(_ value: Double, forKey key: Key) throws { container[key.stringValue] = encoder.box(value) }
 
   public mutating func encode<T: Encodable>(_ value: T, forKey key: Key) throws {
+    // `SelfDocumentID` is ignored during encoding.
+    if T.self == SelfDocumentID.self {
+      return
+    }
+
     encoder.codingPath.append(key)
     defer {
       encoder.codingPath.removeLast()