Releases: mongodb/js-bson
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.
v5.0.0
The MongoDB Node.js team is pleased to announce version 5.0.0 of the bson package!
Release Highlights
BSON v5 is out and ready to rumble!
The focus of this release was to modernize our library's approach to delivering a unified cross-platform JavaScript experience.
We no longer support EOL Node.js versions, so the new minimum requirement for the library is v14.20.1 or later.
With ES modules no longer experimental and top-level await available, BSON now offers a native ESM bundle that works in Node.js and the browser in addition to the existing CommonJS format.
Remove reliance on Node.js Buffer
Our main improvement centers around the code's use of Uint8Array on the web and Buffer in Node.js.
By pulling out all the byte-by-byte helpers needed to parse and create BSON documents we were able to accomplish the original vision of the Node.js project: true isomorphism (almost!). Our ES module build of the library is runnable in Node.js and the browser, without shims or polyfills. We are so excited for this "write once, run everywhere" future!
The Remove reliance on Node.js Buffer section in the migration guide provides more detail.
Use BigInt with BSON and EJSON
Speaking of modernization, we are delighted to announce support for BigInt as a native way to represent and interact with BSON int64s!
JavaScript introduced an infinite precision integer type called BigInt in 2018. BSON 5.0 supports Nodejs 14+, which enables us to use it as an alternate numeric representation for BSON Longs. You can start sending BigInts down into BSON right away: BSON.serialize and EJSON.stringify understand how to convert them into BSON Long and EJSON's $numberLong format.
Returning BigInts is not enabled by default, however this can be accomplished by adding the useBigInt64: true flag in BSON.deserialize or EJSON.parse. For more information on how we transform BigInt’s to 64-bit Integers see the abstract ToBigInt64 operation.
Note: Full support for this feature is not going to be available in the driver v5.0.0 release, we are intending to make it available in the first feature release after 5.0.0
Upgrade today!
We have a detailed migration guide that provides more context on the changes listed below.
We hope you love BSON as much as we do. 💚 🧑💻
⚠ BREAKING CHANGES
- NODE-4892: error on bson types not from this version (#543)
- NODE-4890: make all thrown errors into BSONErrors (#545)
- NODE-4713: modernize bundling (#534)
- NODE-1921: validate serializer root input (#537)
- NODE-4711: remove evalFunctions option (#539)
- NODE-4706: validate Timestamp ctor argument (#536)
- NODE-4710: remove capital D ObjectID export (#528)
- NODE-4862: add BSONType enum and remove internal constants from export (#532)
- NODE-4410: only enumerate own properties (#527)
- NODE-4850: serialize negative zero to double (#529)
- NODE-4704: remove deprecated ObjectId methods (#525)
- NODE-4461: remove Decimal128 toObject transformer (#526)
- NODE-4712: remove unused Map polyfill (#523)
- NODE-4440: bump TS target version to es2020 (#520)
- NODE-4802: Refactor BSON to work with cross platform JS APIs (#518)
- NODE-4435: drop support for nodejs versions below 14 (#517)
Features
Use BigInt with BSON and EJSON
- NODE-4870: Support BigInt serialization (#541) (e9e40a2)
- NODE-4871: Add support for int64 deserialization to BigInt (#542) (9ff60ba)
- NODE-4873: support EJSON stringify from BigInt to $numberLong (#547) (37e8690)
- NODE-4874: support EJSON parse for BigInt from $numberLong (#552) (854aa70)
Other Features
- NODE-4862: add BSONType enum and remove internal constants from export (#532) (196f9f8)
- NODE-4850: serialize negative zero to double (#529) (be74b30)
- NODE-4464: stringify and parse negative zero to and from $numberDouble: -0.0 (#531) (a469e91)
Removals and Breaking Fixes
- NODE-1921: validate serializer root input (#537) (95d5edf)
- NODE-4711: remove evalFunctions option (#539) (0427eb5)
- NODE-4713: modernize bundling (#534) (28ce4d5)
- NODE-4890: make all thrown errors into BSONErrors (#545) (5b837a9)
- NODE-4892: error on bson types not from this version (#543) (d9f0eaa)
- NODE-4927: exports in package.json for react native and document how to polyfill for BSON (#550) (3b4b61e)
- NODE-4706: validate Timestamp ctor argument (#536) (f90bcc3)
- NODE-4710: remove capital D ObjectID export (#528) (8511225)
- NODE-4410: only enumerate own properties (#527) (5103e4d)
- NODE-4704: remove deprecated ObjectId methods (#525) (f1cccf2)
- NODE-4461: remove Decimal128 toObject transformer (#526) (14a7473)
- NODE-4712: remove unused Map polyfill (#523) (1fb6dc6)
- NODE-4440: bump TS target version to es2020 (#520) (491d8b7)
- NODE-4802: Refactor BSON to work with cross platform JS APIs (#518) (3d3d0dc)
- NODE-4435: drop support for nodejs versions below 14 (#517) (027ffb7)
Bug Fixes
- NODE-4771: serializeFunctions breaks function names outside of basic latin (#538) (35a9234)
- NODE-4887: serializeInto does not check for the presence of a toBSON method for values in Map entries (#555) (ebc1c76)
- NODE-4905: double precision accuracy in canonical EJSON (#548) (e0dbb17)
- NODE-4932: remove .0 suffix from double extended json values (#554) (946866d)
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 and report any issues to the NODE project.
v5.0.0-alpha.3
🚧 Testing Build Only
This alpha build is intended for internal testing only. Adopt at your own risk.
Changes listed in HISTORY.md.
5.0.0-alpha.2 diff v5.0.0-alpha.3 (2023-01-20)
v5.0.0-alpha.2
🚧 Testing Build Only
This alpha build is intended for internal testing only. Adopt at your own risk.
Changes listed in HISTORY.md.
5.0.0-alpha.1 diff v5.0.0-alpha.2 (2023-01-10)