Releases: mongodb/js-bson
v6.2.0
6.2.0 (2023-10-16)
The MongoDB Node.js team is pleased to announce version 6.2.0 of the bson package!
Release Notes
Node.js BSON now supports inspect options, specifically visualizing in color
New Color Visualization:
Other Notable Changes
- Strings have consistent single quotes around them, other than the case of a code block that has a string within
- Code blocks with newlines will be visually printed with newlines for easier reading
Clarify BSONVersionError message
Previously, our thrown BSONVersionError stated that the "bson type must be from 6.0 or later". Our intention is to prevent cross-major BSON types from reaching the serialization logic as breaking changes to the types could lead to silent incompatibilities in the serialization process. We've updated the message to make that intention clear: "bson types must be from bson 6.x.x".
Features
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v5.5.1
5.5.1 (2023-09-28)
The MongoDB Node.js team is pleased to announce version 5.5.1 of the bson package!
Release Notes
Clarify BSONVersionError message
Previously, our thrown BSONVersionError stated that the "bson type must be from 6.0 or later". Our intention is to prevent cross-major BSON types from reaching the serialization logic as breaking changes to the types could lead to silent incompatibilities in the serialization process. We've updated the message to make that intention clear: "bson types must be from bson 6.x.x".
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v6.1.0
6.1.0 (2023-09-12)
The MongoDB Node.js team is pleased to announce version 6.1.0 of the bson package!
Release Notes
Add new Decimal128.fromStringWithRounding static method
Following the merging of the Decimal128.fromString bug fix in #613, we understand that some users may have been relying on our inexact rounding behaviour in their applications. To address this need, we have exposed the inexact rounding behaviour via a new static method, Decimal128.fromStringWithRounding.
Thank you to @hconn-riparian for reporting a related rounding bug and fix in #560 which has been included in this feature.
// 5.x
> let d = Decimal128.fromString('127341286781293491234791234667890123')
new Decimal128("1.273412867812934912347912346678901E+35")
// 6.x
> let d = Decimal128.fromString('127341286781293491234791234667890123')
Uncaught:
BSONError: "127341286781293491234791234667890123" is not a valid Decimal128 string - inexact rounding
at invalidErr (./js-bson/lib/bson.cjs:1402:11)
at Decimal128.fromStringInternal (./js-bson/lib/bson.cjs:1633:25)
at Decimal128.fromString (./js-bson/lib/bson.cjs:1424:27)
> d = Decimal128.fromStringWithRounding('127341286781293491234791234667890123')
new Decimal128("1.273412867812934912347912346678901E+35")See our driver specifications for more information on inexact rounding.
Improved ObjectId serialization performance
Thanks to @billouboq for submitting the performance fix merged in #614. When using a for-loop instead of creating a new 12 byte view before calling Uint8Array.prototype.set, our internal testing shows a 25% increase in MB/s throughput of ObjectId serialization!
Features
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
Contributors
Assets 2
v5.5.0
5.5.0 (2023-09-12)
The MongoDB Node.js team is pleased to announce version 5.5.0 of the bson package!
Release Notes
This release is focused on a bug fix and a new feature for our Decimal128 class.
Decimal128 constructor and Decimal128.fromString now throw 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 performing inexact rounding is undesirable behaviour.
New Decimal128.fromStringWithRounding static method
We understand that some of our users may have depended on the rounding behaviour of Decimal128.fromString for their applications. To support these users, we have exposed this behaviour via the Decimal128.fromStringWithRounding method. Anywhere that Decimal128.fromString was used with the expectation that rounding would occur can be replaced with a call to this new method.
We also want to express our gratitude to @hconn-riparian for reporting a related rounding bug and fix in #560 which has been included in our implementation of this feature.
// pre v5.5
> let d = Decimal128.fromString('127341286781293491234791234667890123')
new Decimal128("1.273412867812934912347912346678901E+35")
// >= v5.5
> let d = Decimal128.fromString('127341286781293491234791234667890123')
Uncaught:
BSONError: "127341286781293491234791234667890123" is not a valid Decimal128 string - inexact rounding
at invalidErr (./js-bson/lib/bson.cjs:1402:11)
at Decimal128.fromStringInternal (./js-bson/lib/bson.cjs:1633:25)
at Decimal128.fromString (./js-bson/lib/bson.cjs:1424:27)
> d = Decimal128.fromStringWithRounding('127341286781293491234791234667890123')
new Decimal128("1.273412867812934912347912346678901E+35")Read more about inexact rounding and the rationale for this change in our Decimal128 specification.
Features
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
Contributors
Assets 2
v6.0.0
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.
Important
The BSON_MAJOR_VERSION has been bumped to 6. Only BSON objects that have this major version can be serialized with this version of the library. Mismatched objects will throw a BSONVersionError when attempting to serialize.
Important
The minimum supported Node.js version is now v16.20.1. We strive to keep our minimum supported Node.js version in sync with the runtime's release cadence to keep up with the latest security updates and modern language features.
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)
falseRemoved 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
We invite you to try the bson library immediately, and report any issues to the NODE project.
Contributors
Assets 2
v5.4.0
5.4.0 (2023-07-03)
The MongoDB Node.js team is pleased to announce version 5.4.0 of the bson package!
Release Notes
Improved React Native experience
The BSON package now ships a bundle made to work on React Native without additional polyfills preconfigured. The necessary APIs (TextEncoder/TextDecoder & atob/btoa) are now vendored into the RN bundle directly. Users should still install react-native-get-random-values themselves to get securely generated UUIDs and ObjectIds. Read more in the React Native section of our readme.
Improved BSON UTF8 Decoding Performance
In the v5 major release of BSON we internally abstracted the different byte manipulation APIs used based on whether the library is running in Node.js or in a browser. This abstraction required us to create a subarray before invoking the environment's UTF8 decoding API. Creating the subarray before invoking Node.js' Buffer.prototype.toString API turns out to cause an unnecessary slow down. We have now updated the UTF8 stringification step on Node.js to invoke Buffer.prototype.toString with the start and end offsets. See #585 for our research.
Features
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v5.3.0
The MongoDB Node.js team is pleased to announce version 5.3.0 of the bson package!
Release Highlights
This release fixes a strictness issue with our UUID class. The UUID class has and will continue to generate UUID v4 bytes. However, now when reading UUIDs from MongoDB the UUID can be whatever format was inserted to the database, instead of throwing an error. This will notably help with data that has empty GUID values.
Deprecation
Bug Fix
Documentation
- API: https://github.com/mongodb/js-bson#readme
- Changelog: https://github.com/mongodb/js-bson/blob/main/HISTORY.md#change-log
We invite you to try the bson library immediately, and report any issues to the NODE project.
v5.2.0
The MongoDB Node.js team is pleased to announce version 5.2.0 of the bson package!
Release Highlights
With this release we've added APIs to create BSON Binary / UUID / ObjectId types from hex and base64 strings.
class ObjectId {
static createFromHexString(hex: string): ObjectId;
static createFromBase64(base64: string): ObjectId;
}
class Binary {
static createFromHexString(hex: string, subType? number): Binary;
static createFromBase64(base64: string, subType? number): Binary;
}
class UUID extends Binary {
static override createFromHexString(hex: string): UUID;
static override createFromBase64(base64: string): UUID;
}Features
Documentation
- API: https://github.com/mongodb/js-bson#readme
- Changelog: https://github.com/mongodb/js-bson/blob/main/HISTORY.md#change-log
We invite you to try the bson library immediately, and report any issues to the NODE project.
v5.1.0
The MongoDB Node.js team is pleased to announce version 5.1.0 of the bson package!
Release Highlights
EJSON.stringify now supports ES Map!
import { EJSON } from 'bson';
const m = new Map([
['a', new Map([['b', 1]])],
['b', 2]
]);
console.log(EJSON.stringify(m))
// '{"a":{"b":1},"b":2}'Features
Documentation
- API: https://github.com/mongodb/js-bson#readme
- Changelog: https://github.com/mongodb/js-bson/blob/main/HISTORY.md#change-log
We invite you to try the bson library immediately, and report any issues to the NODE project.
v5.0.1
The MongoDB Node.js team is pleased to announce version 5.0.1 of the bson package!
Bug Fixes
- NODE-5025: no type definitions for es module (#563) (50e90fc)
- NODE-5048: webpack unable to bundle import with leading 'node:' (#564) (3aed24a)
- NODE-5056: EJSON.parse date handling when useBigInt64=true (#562) (d5088af)
Documentation
- API: https://github.com/mongodb/js-bson#readme
- Changelog: https://github.com/mongodb/js-bson/blob/main/HISTORY.md#change-log
We invite you to try the bson library immediately, and report any issues to the NODE project.