bson 6.0.0

v6.0.0

on Node.js NPM

6.0.0 (2023-08-24)

The MongoDB Node.js team is pleased to announce version 6.0.0 of the bson package!

Release Notes

In this major version update, we focused on removing deprecated or otherwise difficult to use APIs and fixing impactful bugs.

Decimal128 constructor now throws when detecting loss of precision

Prior to this release, Decimal128 would round numbers with more than 34 significant digits and lose precision. Now, on detecting loss of precision, Decimal128's constructor and Decimal128.fromString will throw a BSONError. This behaviour should have been the default as the Decimal128 class was always intended to be high-precision floating point value. As such, silently rounding is undesirable behaviour as it can potentially result in data loss.

// previous behaviour
> new Decimal128('10000000000000000000000000000000001')
new Decimal128("1.000000000000000000000000000000000E+34")

// new behaviour
> new Decimal128('10000000000000000000000000000000001')
Uncaught:
BSONError: "10000000000000000000000000000000001" is not a valid Decimal128 string - inexact rounding
    at invalidErr (bson/lib/bson.cjs:1402:11)
    at Decimal128.fromString (bson/lib/bson.cjs:1555:21)
    at new Decimal128 (bson/lib/bson.cjs:1411:37)

Note a separate method with corrected rounding behaviour will be available in the next minor version of this library. Additionally a fix for this bug and the aforementioned new method with corrected rounding will be added in the next minor release of v5 of this library.

Strings of length 12 can no longer make an ObjectId

(From String.length): [The String length] property returns the number of code units in the string. JavaScript uses UTF-16 encoding, where each Unicode character may be encoded as one or two code units, so it's possible for the value returned by length to not match the actual number of Unicode characters in the string.

The ObjectId constructor erroneously interpreted a string with length of 12 as UTF8 bytes that could be converted to an ObjectId. This is unexpected for at least two reasons. The first is that a legacy approach (pre- Uint8Arrays) to handling binary data was to pass around "binary strings", where each character represents a single byte, this is not the same as interpreting a sting as UTF8, which has restrictions on how each byte can be formatted. The second is that a string of length 12 does not result in 12 bytes of data when converted to utf8 (ex. '🐶🐶🐶🐶🐶🐶'.length === 12, but as UTF8 bytes this is a 24-byte sequence).

Despite the bugginess of the behavior discussed above, the right string in the right context does create the proper byte sequence, so we are considering this a breaking change and removing it in this major release.

Removed ISO-8859-1 string format from Binary (a.k.a 'latin1', 'binary')

The Binary BSON type no longer accepts a string as a constructor argument nor can write() be invoked with a string argument. Both methods interpreted strings as binary sequences rather than UTF-8 or base64 which are much more common and expected formats. If there is a string representation of your data it is now expected that the logic that interprets the string format exists outside the Binary class to avoid misinterpreting data. Additionally, .value() only returns a Uint8Array/Buffer that is properly sized to the data. Internally Binary may maintain a .buffer property larger than the the actual data that will be written to BSON bytes. Use .value() to obtain only the bytes relevant to your Binary data.

new Binary(Buffer.from('ÿÿ', 'binary'));
// Binary.createFromBase64("//8=", 0)

new Binary(Buffer.from('ÿÿ', 'utf8'));
// Binary.createFromBase64("w7/Dvw==", 0)

new Binary(Buffer.from('AAAA', 'base64'))
// Binary.createFromBase64("AAAA", 0)

ObjectId.equals now accepts undefined and null parameters

Thanks to @vanstinator for providing this pull request fixing our ObjectId.equals signature to properly allow checking equality with nullish values.

> const oid = new ObjectId()

// Old behaviour
> oid.equals(undefined) // error TS2345: Argument of type 'undefined' is not assignable to parameter of type 'string | ObjectId | ObjectIdLike'.

// New Behaviour
> oid.equals(undefined)

false

Removed deprecated UUID.cacheHexString property

This property was unused and so was removed.

⚠ BREAKING CHANGES

• NODE-5504: bump bson major version (#605)
• NODE-4770: remove 12 length string support from ObjectId constructor (#601)
• NODE-4769: remove ISO-8859-1 string support from Binary (#602)
• NODE-5223: remove deprecated cacheHexString (#595)
• NODE-4787: bump minimum Node.js version to v16.20.1 (#590)
• NODE-5546: decimal 128 fromString performs inexact rounding (#613) (1384cee)

Bug Fixes

• NODE-5509: Allow undefined or null params in ObjectId.equals (#607) (e2674c6)
• NODE-5559: account for quotes when inspecting Code and BSONSymbol (#612) (0664840)

Documentation

• API
• Changelog

We invite you to try the bson library immediately, and report any issues to the NODE project.