Right now, it is difficult for a user to determine whether a key is present and set to nil, or not in the document at all. They need to check if it is contained in the keys array, which is not very intuitive and also not very performant as it iterates the entire document.
We should consider how we can make it more obvious to users that there is a difference between a key not being present and a key being present and set to nil.
One interesting option for this is using a double-optional (BsonValue??) as the Document value type rather than a BsonValue?. This would allow us to return a true nil in the case of a missing key, and an Optional(nil) in the case of a key that is present and set to nil. This is the behavior that a dictionary of [String: BsonValue?] has. Our current behavior more aligns with that of a [String: BsonValue]. See this blog post for some discussion... A downside of that would be that users basically have to double unwrap values all the time.
Alternatively, we can just better document how all this works, and add some optimized helper method(s) for checking if a key is present and set to nil. There is a bson_has_field method on bson_t that would be useful.