[GODRIVER-2716] Deprecate all "bsoncodec.*Codec" types Created: 23/Dec/22  Updated: 28/Oct/23  Resolved: 05/May/23

Status: Closed
Project: Go Driver
Component/s: BSON
Affects Version/s: None
Fix Version/s: 1.12.0

Type: Improvement Priority: Unknown
Reporter: Matt Dale Assignee: Matt Dale
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by GODRIVER-2706 Deprecate the "bsonoptions" package Closed
is depended on by GODRIVER-2617 Remove or un-export all currently dep... Closed
is depended on by GODRIVER-2725 Allow setting "bson.Encoder" and "bso... Closed
Epic Link: Go Driver 2.0 Prep
Quarter: FY24Q1
Documentation Changes: Not Needed
Documentation Changes Summary:

1. What would you like to communicate to the user about this feature?
2. Would you like the user to see examples of the syntax and/or executable code and its output?
3. Which versions of the driver/connector does this apply to?


 Description   

The bsoncodec package currently contains a bunch of *Codec types that define the default behavior for encoding and decoding Go values to/from either BSON or Extended JSON (depending on the ValueWriter implementation). Once the BSON packages are all merged in Go Driver 2.0, the only reason to expose those *Codec types is to access the encoder/decoder configurations. However, using those configuration options require a lot of understanding to use so very few users actually use them. The configuration options are:

  • ByteSliceCodec
    • EncodeNilAsEmpty - Encode nil Go byte slices as empty BSON binary values instead of BSON null.
  • EmptyInterfaceCodec
    • DecodeBinaryAsSlice - Decode BSON binary values as Go byte slices.
  • MapCodec
    • DecodeZerosMap - Delete all data from the target Go map value before decoding.
    • EncodeNilAsEmpty - Encode nil Go maps as empty BSON documents.
    • EncodeKeysWithStringer - Convert Go map keys to strings with fmt.Sprint() instead of the safer default string conversion logic derived from “encoding/json”.
  • SliceCodec
    • EncodeNilAsEmpty - Encode nil Go slices as empty BSON arrays.
  • StringCodec
    • DecodeObjectIDAsHex - Decode BSON ObjectID to Go string using the ObjectID hex value.
  • StructCodec
    • DecodeZeroStruct - Structs should be zeroed before decoding into them.
    • DecodeDeepZeroInline - Nested and inline structs should be zeroed before decoding into them.
    • EncodeOmitDefaultStruct - Struct zero values should be considered empty by “omitempty”.
    • AllowUnexportedFields - Unexported fields should be marshaled/unmarshaled.
    • OverwriteDuplicatedInlinedFields - Inlined struct fields can be overwritten by higher level struct fields with the same BSON key.
    • StructTagParser - Defines the behavior for parsing “bson” struct tags. The BSON library provides a DefaultStructTagParser and JSONFallbackStructTagParser.
  • UIntCodec
    • EncodeToMinSize - All Go uint values except uint64 should be encoded to the minimum size BSON type.

It would be much better to expose those configuration options via the bson.Encoder and bson.Decoder types instead. Deprecate all bsoncodec.*Codec types and define replacement configuration options on the bson.Encoder and bson.Decoder types instead.

An example Encoder API is:

func (e *Encoder) SetAllowUnexported(b bool)
func (e *Encoder) SetIntMinSize(b bool)
func (e *Encoder) SetMapKeysWithStringer(b bool)
func (e *Encoder) SetNilByteSliceAsEmpty(b bool)
func (e *Encoder) SetNilMapAsEmpty(b bool)
func (e *Encoder) SetNilSliceAsEmpty(b bool)
func (e *Encoder) SetOmitDefaultStruct(b bool)
func (e *Encoder) SetOverwriteInlineDuplicates(b bool)
func (e *Encoder) SetRegistry(r *Registry)
func (e *Encoder) SetUseJSONStructTags(b bool)

An example Decoder API is:

func (d *Decoder) DefaultDocumentD()
func (d *Decoder) DefaultDocumentM()
func (d *Decoder) SetAllowUnexported(b bool)
func (d *Decoder) SetBinaryAsSlice(b bool)
func (d *Decoder) SetObjectIDAsHexString(b bool)
func (d *Decoder) SetRegistry(r *Registry) error
func (d *Decoder) SetUseJSONStructTags(b bool)
func (d *Decoder) SetZerosMap(b bool)
func (d *Decoder) SetZerosStruct(b bool)

Definition of done:

  • Deprecate all bsoncodec.*Codec types.
  • Deprecate Decoder.Reset.
    • Recommend creating a new Decoder instead.
  • Define all behaviors configurable via the bsoncodec.*Codec types as configuration setttings on the bson.Encoder and bson.Decoder types.


 Comments   
Comment by Githook User [ 05/May/23 ]

Author:

{'name': 'Matt Dale', 'email': '9760375+matthewdale@users.noreply.github.com', 'username': 'matthewdale'}

Message: GODRIVER-2716 Introduce a new BSON Encoder and Decoder configuration API to replace the bsoncodec configurations. (#1229)

Co-authored-by: Preston Vasquez <prestonvasquez@icloud.com>
Co-authored-by: Kevin Albertson <kevin.albertson@10gen.com>
Branch: master
https://github.com/mongodb/mongo-go-driver/commit/54a3206c25f4b625c43aedbed95d83123d8bb7f7

Comment by Matt Dale [ 12/Apr/23 ]

PR: https://github.com/mongodb/mongo-go-driver/pull/1229

Generated at Thu Feb 08 08:39:13 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.