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/CodableErrors.swift

@@ -16,6 +16,7 @@
 
 public enum FirestoreDecodingError: Error {
   case decodingIsNotSupported
+  case fieldNameConfict(String)
 }
 
 public enum FirestoreEncodingError: Error {

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

@@ -34,7 +34,7 @@ extension DocumentSnapshot {
       d = Firestore.Decoder()
     }
     if let data = data() {
-      return try d?.decode(T.self, from: data)
+      return try d?.decode(T.self, from: data, in: reference)
     }
     return nil
   }

Firestore/Swift/Source/Codable/SelfDocumentId.swift

@@ -0,0 +1,72 @@
+/*
+ * 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
+
+/// A value that is populated in Codable objects with a `DocumentReference` by
+/// the FirestoreDecoder when a document is read.
+///
+/// Note that limitations in Swift compiler-generated Codable implementations
+/// prevent using this type wrapped in an Optional. Optional SelfDocumentIDs
+/// are possible if you write a custom `init(from: Decoder)` method.
+///
+/// If the field name used for this type conflicts with a read document field,
+/// an error is thrown. For example, if a custom object has a field `firstName`
+/// with type `SelfDocumentID`, and there is a property from the document named
+/// `firstName` as well, an error is thrown when you try to read the document.
+///
+/// When writing a Codable object containing a `SelfDocumentID`, its value is
+/// ignored. This allows you to read a document from one path and write it into
+/// another without adjusting the value here.
+///
+/// NOTE: Trying to encode/decode this type using encoders/decoders other than
+/// FirestoreEncoder leads to an error.
+public final class SelfDocumentID: Equatable, Codable {
+  // MARK: - Initializers
+
+  public init() {
+    reference = nil
+  }
+
+  public init(from ref: DocumentReference?) {
+    reference = ref
+  }
+
+  // MARK: - `Codable` implemention.
+
+  public init(from decoder: Decoder) throws {
+    throw FirestoreDecodingError.decodingIsNotSupported
+  }
+
+  public func encode(to encoder: Encoder) throws {
+    throw FirestoreEncodingError.encodingIsNotSupported
+  }
+
+  // MARK: - Properties
+
+  public var id: String? {
+    return reference?.documentID
+  }
+
+  public let reference: DocumentReference?
+
+  // MARK: - `Equatable` implementation
+
+  public static func == (lhs: SelfDocumentID,
+                         rhs: SelfDocumentID) -> Bool {
+    return lhs.reference == rhs.reference
+  }
+}

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)

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/Swift/Tests/Codable/FirestoreEncoderTests.swift

@@ -605,4 +605,69 @@ class FirestoreEncoderTests: XCTestCase {
     decoded = try Firestore.Decoder().decode(Model.self, from: encoded)
     XCTAssertEqual(decoded, fieldIsNotNull)
   }
+
+  func testAutomaticallyPopulatesSelfDocumentIDField() throws {
+    struct Model: Codable, Equatable {
+      var name: String
+      var docId: SelfDocumentID
+    }
+
+    let decoded = try Firestore.Decoder().decode(Model.self, from: ["name": "abc"], in: FSTTestDocRef("abc/123"))
+    XCTAssertEqual(decoded, Model(name: "abc", docId: SelfDocumentID(from: FSTTestDocRef("abc/123"))))
+  }
+
+  func testSelfDocumentIDIgnoredInEncoding() throws {
+    struct Model: Codable, Equatable {
+      var name: String
+      var docId: SelfDocumentID
+    }
+
+    let model = Model(name: "abc", docId: SelfDocumentID(from: FSTTestDocRef("abc/123")))
+    _ = assertEncodes(model, to: ["name": "abc"])
+  }
+
+  func testEncodingSelfDocumentIDNotEmbeddedThrows() {
+    let doc = SelfDocumentID(from: FSTTestDocRef("abc/xyz"))
+    do {
+      _ = try Firestore.Encoder().encode(doc)
+      XCTFail("Failed to throw")
+    } catch FirestoreEncodingError.encodingIsNotSupported {
+      return
+    } catch {
+      XCTFail("Unrecognized error: \(error)")
+    }
+  }
+
+  func testSelfDocumentIDWithJsonEncoderThrows() {
+    let doc = SelfDocumentID(from: FSTTestDocRef("abc/xyz"))
+    do {
+      _ = try JSONEncoder().encode(doc)
+      XCTFail("Failed to throw")
+    } catch FirestoreEncodingError.encodingIsNotSupported {
+      return
+    } catch {
+      XCTFail("Unrecognized error: \(error)")
+    }
+  }
+
+  func testDecodingSelfDocumentIDWithConfictingFieldsThrows() throws {
+    struct Model: Codable, Equatable {
+      var name: String
+      var docId: SelfDocumentID
+    }
+
+    do {
+      _ = try Firestore.Decoder().decode(
+        Model.self,
+        from: ["name": "abc", "docId": "Causing conflict"],
+        in: FSTTestDocRef("abc/123")
+      )
+      XCTFail("Failed to throw")
+    } catch let FirestoreDecodingError.fieldNameConfict(msg) {
+      XCTAssertEqual(msg, "Field name [\"docId\"] was found from document \"abc/123\"," + " cannot assign the document reference to this field.")
+      return
+    } catch {
+      XCTFail("Unrecognized error: \(error)")
+    }
+  }
 }

Firestore/Swift/Tests/Integration/CodableIntegrationTests.swift

@@ -169,6 +169,30 @@ class CodableIntegrationTests: FSTIntegrationTestCase {
     }
   }
 
+  func testSelfDocumentID() throws {
+    struct Model: Codable, Equatable {
+      var name: String
+      var docId: SelfDocumentID
+    }
+
+    let docToWrite = documentRef()
+    let model = Model(
+      name: "name",
+      docId: SelfDocumentID()
+    )
+
+    try setData(from: model, forDocument: docToWrite, withFlavor: .docRef)
+    let data = readDocument(forRef: docToWrite).data()
+
+    // "docId" is ignored during encoding
+    XCTAssertEqual(data! as! [String: String], ["name": "name"])
+
+    // Decoded result has "docId" auto-populated.
+    let decoded = try readDocument(forRef: docToWrite).data(as: Model.self)
+    XCTAssertEqual(decoded!, Model(name: "name",
+                                   docId: SelfDocumentID(from: docToWrite)))
+  }
+
   func testSetThenMerge() throws {
     struct Model: Codable, Equatable {
       var name: String? = nil