|
16 | 16 |
|
17 | 17 | import FirebaseFirestore |
18 | 18 | import FirebaseSharedSwift |
| 19 | +@_implementationOnly import FirebaseCoreExtension |
19 | 20 |
|
20 | 21 | extension CodingUserInfoKey { |
21 | 22 | static let documentRefUserInfoKey = |
@@ -65,57 +66,114 @@ internal protocol DocumentIDProtocol { |
65 | 66 | init(from documentReference: DocumentReference?) throws |
66 | 67 | } |
67 | 68 |
|
68 | | -/// A value that is populated in Codable objects with the `DocumentReference` |
69 | | -/// of the current document by the Firestore.Decoder when a document is read. |
| 69 | +/// A property wrapper type that marks a `DocumentReference?` or `String?` field to |
| 70 | +/// be populated with a document identifier when it is read. |
70 | 71 | /// |
71 | | -/// If the field name used for this type conflicts with a read document field, |
72 | | -/// an error is thrown. For example, if a custom object has a field `firstName` |
73 | | -/// annotated with `@DocumentID`, and there is a property from the document |
74 | | -/// named `firstName` as well, an error is thrown when you try to read the |
75 | | -/// document. |
| 72 | +/// Apply the `@DocumentID` annotation to a `DocumentReference?` or `String?` |
| 73 | +/// property in a `Codable` object to have it populated with the document |
| 74 | +/// identifier when it is read and decoded from Firestore. |
76 | 75 | /// |
77 | | -/// When writing a Codable object containing an `@DocumentID` annotated field, |
78 | | -/// its value is ignored. This allows you to read a document from one path and |
79 | | -/// write it into another without adjusting the value here. |
| 76 | +/// - Important: The name of the property annotated with `@DocumentID` must not |
| 77 | +/// match the name of any fields in the Firestore document being read or else |
| 78 | +/// an error will be thrown. For example, if the `Codable` object has a |
| 79 | +/// property named `firstName` annotated with `@DocumentID`, and the Firestore |
| 80 | +/// document contains a field named `firstName`, an error will be thrown when |
| 81 | +/// attempting to decode the document. |
80 | 82 | /// |
81 | | -/// NOTE: Trying to encode/decode this type using encoders/decoders other than |
82 | | -/// Firestore.Encoder leads to an error. |
| 83 | +/// - Example Read: |
| 84 | +/// ```` |
| 85 | +/// struct Player: Codable { |
| 86 | +/// @DocumentID var playerID: String? |
| 87 | +/// var health: Int64 |
| 88 | +/// } |
| 89 | +/// |
| 90 | +/// let p = try! await Firestore.firestore() |
| 91 | +/// .collection("players") |
| 92 | +/// .document("player-1") |
| 93 | +/// .getDocument(as: Player.self) |
| 94 | +/// print("\(p.playerID!) Health: \(p.health)") |
| 95 | +/// |
| 96 | +/// // Prints: "Player: player-1, Health: 95" |
| 97 | +/// ```` |
| 98 | +/// |
| 99 | +/// - Important: Trying to encode/decode this type using encoders/decoders other than |
| 100 | +/// Firestore.Encoder throws an error. |
| 101 | +/// |
| 102 | +/// - Important: When writing a Codable object containing an `@DocumentID` annotated field, |
| 103 | +/// its value is ignored. This allows you to read a document from one path and |
| 104 | +/// write it into another without adjusting the value here. |
83 | 105 | @propertyWrapper |
84 | 106 | public struct DocumentID<Value: DocumentIDWrappable & Codable>: |
85 | | - DocumentIDProtocol, Codable, StructureCodingUncodedUnkeyed { |
86 | | - var value: Value? |
| 107 | + StructureCodingUncodedUnkeyed { |
| 108 | + private var value: Value? = nil |
87 | 109 |
|
88 | 110 | public init(wrappedValue value: Value?) { |
| 111 | + if let value = value { |
| 112 | + logWarning(for: value) |
| 113 | + } |
89 | 114 | self.value = value |
90 | 115 | } |
91 | 116 |
|
92 | 117 | public var wrappedValue: Value? { |
93 | 118 | get { value } |
94 | | - set { value = newValue } |
| 119 | + set { |
| 120 | + if let someNewValue = newValue { |
| 121 | + logWarning(for: someNewValue) |
| 122 | + } |
| 123 | + value = newValue |
| 124 | + } |
95 | 125 | } |
96 | 126 |
|
97 | | - // MARK: - `DocumentIDProtocol` conformance |
| 127 | + private func logWarning(for value: Value) { |
| 128 | + FIRLogWarningSwift( |
| 129 | + "[FirebaseFirestoreSwift]", |
| 130 | + "I-FST000002", |
| 131 | + """ |
| 132 | + Attempting to initialize or set a @DocumentID property with a non-nil |
| 133 | + value: \(value). The document ID is managed by Firestore and any |
| 134 | + initialized or set value will be ignored. The ID is automatically set |
| 135 | + when reading from Firestore." |
| 136 | + """ |
| 137 | + ) |
| 138 | + } |
| 139 | +} |
98 | 140 |
|
99 | | - public init(from documentReference: DocumentReference?) throws { |
| 141 | +extension DocumentID: DocumentIDProtocol { |
| 142 | + internal init(from documentReference: DocumentReference?) throws { |
100 | 143 | if let documentReference = documentReference { |
101 | 144 | value = try Value.wrap(documentReference) |
102 | 145 | } else { |
103 | 146 | value = nil |
104 | 147 | } |
105 | 148 | } |
| 149 | +} |
106 | 150 |
|
107 | | - // MARK: - `Codable` implementation. |
108 | | - |
| 151 | +extension DocumentID: Codable { |
| 152 | + /// A `Codable` object containing an `@DocumentID` annotated field should |
| 153 | + /// only be decoded with `Firestore.Decoder`; this initializer throws if an |
| 154 | + /// unsupported decoder is used. |
| 155 | + /// |
| 156 | + /// - Parameter decoder: A decoder. |
| 157 | + /// - Throws: ``FirestoreDecodingError`` |
109 | 158 | public init(from decoder: Decoder) throws { |
110 | 159 | guard let reference = decoder |
111 | 160 | .userInfo[CodingUserInfoKey.documentRefUserInfoKey] as? DocumentReference else { |
112 | 161 | throw FirestoreDecodingError.decodingIsNotSupported( |
113 | | - "Could not find DocumentReference for user info key: \(CodingUserInfoKey.documentRefUserInfoKey)" |
| 162 | + """ |
| 163 | + Could not find DocumentReference for user info key: \(CodingUserInfoKey |
| 164 | + .documentRefUserInfoKey). |
| 165 | + DocumentID values can only be decoded with Firestore.Decoder |
| 166 | + """ |
114 | 167 | ) |
115 | 168 | } |
116 | 169 | try self.init(from: reference) |
117 | 170 | } |
118 | 171 |
|
| 172 | + /// A `Codable` object containing an `@DocumentID` annotated field can only |
| 173 | + /// be encoded with `Firestore.Encoder`; this initializer always throws. |
| 174 | + /// |
| 175 | + /// - Parameter encoder: An invalid encoder. |
| 176 | + /// - Throws: ``FirestoreEncodingError`` |
119 | 177 | public func encode(to encoder: Encoder) throws { |
120 | 178 | throw FirestoreEncodingError.encodingIsNotSupported( |
121 | 179 | "DocumentID values can only be encoded with Firestore.Encoder" |
|
0 commit comments