feat(firestore): add opt-in BSON document read and decoding support

[ohmayr]

…PR 2)

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

[gemini-code-assist]

Code Review

This pull request introduces support for decoding legacy BSON map representations into native BSON instances within the Firestore SDK, updating the client classes, helper functions, and DocumentSnapshot to handle the new decode_bson configuration. The review feedback highlights critical issues in the implementation: first, DocumentSnapshot fails to dynamically toggle between BSON-decoded and raw formats when raw_fields is None; second, the system tests incorrectly pass decode_bson to get() methods on document references, which will raise runtime TypeErrors; and finally, the return type annotation of decode_dict should be updated to Any to accurately reflect the potential return of native BSON instances.

[gemini-code-assist]

When raw_fields is None (which is currently the case for any DocumentSnapshot created outside of _parse_batch_get, such as query or stream results), the snapshot cannot dynamically toggle between BSON-decoded and raw dict formats because it lacks the original protobuf fields to re-decode.

In the current implementation, if raw_fields is None and self._decode_bson is True, self._data_raw is populated with the decoded BSON data. If a user then calls to_dict(decode_bson=False), it will incorrectly return the BSON-decoded data instead of the raw dict.

To fix this, we should:

1. Correctly initialize self._data_bson or self._data_raw in __init__ based on self._decode_bson when raw_fields is None.
2. Ensure that all internal paths that instantiate DocumentSnapshot (such as query and stream result processing in base_query.py / query.py) are updated to pass raw_fields so that dynamic BSON decoding works consistently across all read operations.

        if raw_fields is not None:
            if self._decode_bson:
                self._data_bson = copy.deepcopy(data)
            else:
                self._data_raw = copy.deepcopy(data)
        else:
            if self._decode_bson:
                self._data_bson = copy.deepcopy(data) if data is not None else None
            else:
                self._data_raw = copy.deepcopy(data) if data is not None else None

[gemini-code-assist]

DocumentReference.get() does not accept a decode_bson parameter. Calling doc_ref.get(decode_bson=True) will raise a TypeError at runtime.

To test BSON decoding, you should either:

1. Set decode_bson=True on the client instance.
2. Or retrieve the snapshot normally and call snapshot.to_dict(decode_bson=True) to decode on-demand.

Suggested change

	snapshot = doc_ref.get(decode_bson=True)
	assert snapshot.exists
	assert snapshot.to_dict(decode_bson=True) == bson_payload
	snapshot = doc_ref.get()
	assert snapshot.exists
	assert snapshot.to_dict(decode_bson=True) == bson_payload

[gemini-code-assist]

AsyncDocumentReference.get() does not accept a decode_bson parameter. Calling await doc_ref.get(decode_bson=True) will raise a TypeError at runtime.

To test BSON decoding, you should either:

1. Set decode_bson=True on the client instance.
2. Or retrieve the snapshot normally and call snapshot.to_dict(decode_bson=True) to decode on-demand.

Suggested change

	snapshot = await doc_ref.get(decode_bson=True)
	assert snapshot.exists
	assert snapshot.to_dict(decode_bson=True) == bson_payload
	snapshot = await doc_ref.get()
	assert snapshot.exists
	assert snapshot.to_dict(decode_bson=True) == bson_payload

[gemini-code-assist]

The return type annotation of decode_dict is currently Union[dict, Vector]. However, with the introduction of BSON decoding support, this function can now return native BSON instances (such as BSONObjectID, BSONDecimal128, etc.) when decode_bson is enabled. The type annotation should be updated to Any to accurately reflect this behavior.

Suggested change

	def decode_dict(value_fields, client, decode_bson: Optional[bool] = None) -> Union[dict, Vector]:
	def decode_dict(value_fields, client, decode_bson: Optional[bool] = None) -> Any:

References

1. When finding a precise type hint that satisfies both mypy and unit tests is not cost-effective, using a less specific type (e.g., Any) is an acceptable trade-off, especially if it improves upon the previous state.