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.