Releases: mongodb/js-bson
v6.8.0
6.8.0 (2024-06-27)
The MongoDB Node.js team is pleased to announce version 6.8.0 of the bson package!
Release Notes
Add Signature to Github Releases
The Github release for js-bson now contains a detached signature file for the NPM package (named
bson-X.Y.Z.tgz.sig), on every major and patch release to 6.x and 5.x. To verify the signature, follow the instructions in the 'Release Integrity' section of the README.md file.
Optimize performance of Long.fromBigInt
Internally fromBigInt was originally implemented using toString of the bigint value. Now, Long.fromBigInt has been refactored to use bitwise operations greatly improving performance.
Features
Performance Improvements
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v6.7.0
6.7.0 (2024-05-01)
The MongoDB Node.js team is pleased to announce version 6.7.0 of the bson package!
Release Notes
Add Long.fromStringStrict method
The Long.fromStringStrict method is almost identical to the Long.fromString method, except it throws a BSONError if any of the following are true:
- input string has invalid characters, for the given radix
- the string contains whitespace
- the value the input parameters represent is too large or too small to be a 64-bit Long
Unlike Long.fromString, this method does not coerce the inputs '+/-Infinity' and 'NaN' to Long.ZERO, in any case.
Examples:
Long.fromStringStrict('1234xxx5'); // throws BSONError
Long.fromString('1234xxx5'); // coerces input and returns new Long(123400)
// when writing in radix 10, 'n' and 'a' are both invalid characters
Long.fromStringStrict('NaN'); // throws BSONError
Long.fromString('NaN'); // coerces input and returns Long.ZERONote
Long.fromStringStrict's functionality will be present in Long.fromString in the V7 BSON release.
Add static Double.fromString method
This method attempts to create an Double type from a string, and will throw a BSONError on any string input that is not representable as a IEEE-754 64-bit double.
Notably, this method will also throw on the following string formats:
- Strings in non-decimal and non-exponential formats (binary, hex, or octal digits)
- Strings with characters other than sign, numeric, floating point, or slash characters (Note:
'Infinity','-Infinity', and'NaN'input strings are still allowed) - Strings with leading and/or trailing whitespace
Strings with leading zeros, however, are also allowed.
Add static Int32.fromString method
This method attempts to create an Int32 type from string, and will throw a BSONError on any string input that is not representable as an Int32.
Notably, this method will also throw on the following string formats:
- Strings in non-decimal formats (exponent notation, binary, hex, or octal digits)
- Strings with non-numeric and non-leading sign characters (ex: '2.0', '24,000')
- Strings with leading and/or trailing whitespace
Strings with leading zeros, however, are allowed
UTF-8 validation now throws a BSONError on overlong encodings in Node.js
Specifically, this affects deserialize when utf8 validation is enabled, which is the default.
An overlong encoding is when the number of bytes in an encoding is inflated by padding the code point with leading 0s (see here for more information).
Long.fromString takes radix into account before coercing '+/-Infinity' and 'NaN' to Long.ZERO
Long.fromString no longer coerces the following cases to Long.ZERO when the provided radix supports all characters in the string:
'+Infinity','-Infinity', or'Infinity'when 35 <= radix <= 36'NaN'when 24 <= radix <= 36
// when writing in radix 27, 'n' and 'a' are valid characters, so 'NaN' represents the decimal number 17060
Long.fromString('NaN', 27); // new Long(17060)
Long.fromString('NaN', 10); // new Long(0) <-- Since 'NaN' is not a valid input in base 10, it gets coerced to Long.ZEROFeatures
- NODE-5648: add Long.fromStringStrict() (#675) (9d5a5df)
- NODE-6086: add Double.fromString() method (#671) (e943cdb)
- NODE-6087: add Int32.fromString method (#670) (5a21889)
Bug Fixes
- NODE-6123: utf8 validation is insufficiently strict (#676) (ae8bac7)
- NODE-6144: Long.fromString incorrectly coerces valid inputs to Long.ZERO in special cases (#677) (208f7e8)
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v6.6.0
6.6.0 (2024-04-01)
The MongoDB Node.js team is pleased to announce version 6.6.0 of the bson package!
Release Notes
Binary.toString and Binary.toJSON align with BSON serialization
When BSON serializes a Binary instance it uses the bytes between 0 and binary.position since Binary supports pre-allocating empty space and writing segments of data using .put()/.write(). Erroneously, the toString() and toJSON() methods did not use the position property to limit how much of the underlying buffer to transform into the final value, potentially returning more string than relates to the actual data of the Binary instance.
In general, you may not encounter this bug if Binary instances are created from a data source (new Binary(someBuffer)) or are returned by the database because in both of these cases binary.position is equal to the length of the underlying buffer.
Fixed example creating an empty Binary:
new BSON.Binary().toString();
// old output: '\x00\x00\x00\x00...' (256 zeros)
// new output: '' Experimental APIs
This release contains experimental APIs that are not suitable for production use. As a reminder, anything marked @experimental is not a part of the stable semantically versioned API and is subject to change in any subsequent release.
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v6.5.0
6.5.0 (2024-03-12)
The MongoDB Node.js team is pleased to announce version 6.5.0 of the bson package!
Release Notes
Fixed float byte-wise handling on big-endian systems
Caution
Among the platforms BSON and the MongoDB driver support this issue impacts s390x big-endian systems. x86, ARM, and other little-endian systems are not affected. Existing versions of the driver can be upgraded to this release.
A recent change to the BSON library started parsing and serializing floats using a Float64Array. When reading the bytes from this array the ordering is dependent on the platform it is running on and we now properly account for that ordering.
Add SUBTYPE_SENSITIVE on Binary class
When a BSON.Binary object is of 'sensitive' subtype, the object's subtype will equal 0x08.
Features
- NODE-5506: add Binary subtype sensitive (#657) (748ca60)
- NODE-5957: add BSON indexing API (#654) (2ac17ec)
Bug Fixes
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
v6.4.0
6.4.0 (2024-02-29)
The MongoDB Node.js team is pleased to announce version 6.4.0 of the bson package!
Release Notes
BSON short basic latin string writing performance improved!
The BSON library's string encoding logic now attempts to optimize for basic latin (ASCII) characters. This will apply to both BSON keys and BSON values that are or contain strings. If strings are less than 6 bytes we observed approximately 100% increase in speed while around 24 bytes the performance was about 33% better. For any non-basic latin bytes or at 25 bytes or greater the BSON library will continue to use Node.js' Buffer.toString API.
The intent is to generally target the serialization of BSON keys which are often short and only use basic latin.
Fixed objectId symbol property not defined on instances from cross cjs and mjs
We do recommend that users of the driver use the BSON APIs exported from the driver. One reason for this is at this time the driver is only shipped in commonjs format and as a result it will only import the commonjs BSON bundle. If in your application you use import syntax then there will be a commonjs and an es module instance in the current process which prevents things like instanceof from working.
Also, private symbols defined in one package will not be equal to symbols defined in the other. This caused an issue on ObjectId's private symbol property preventing the .equals method from one package from operating on an ObjectId created from another.
Thanks to @dot-i's contribution we've changed the private symbol to a private string property so that the .equals() method works across module types.
Deserialization performance increased
If BSON data does not contain Doubles and UTF8 validation is disabled the deserializer is careful to not allocate data structures needed to support that functionality. This has shown to greatly increase (2x-1.3x) the performance of the deserializer.
Thank you @billouboq for this contribution!
Improve the performance of small byte copies
When serializing ObjectIds, Decimal128, and UUID values we can get better performance by writing the byte-copying logic in Javascript for loops rather than using the TypedArray.set API. ObjectId serialization performance is 1.5x-2x faster.
Improved the performance of serializing and deserializing doubles and bigints
We now use bit shifting and multiplication operators in place of DataView getX/setX calls to parse and serialize bigints and a Float64Array to convert a double to bytes. This change has been shown to increase deserializing performance ~1.3x and serializing performance ~1.75x.
Use allocUnsafe for ObjectIds and Decimal128
For small allocations Node.js performance can be improved by using pre-allocated pooled memory. ObjectIds and Decimal128 instance will now use allocUnsafe on Node.js.
Features
Bug Fixes
- NODE-5873: objectId symbol property not defined on instances from cross cjs and mjs (#643) (4d9884d)
Performance Improvements
- NODE-5557: move DataView and Set allocation used for double parsing and utf8 validation to nested path (#611) (9a150e1)
- NODE-5910: optimize small byte copies (#651) (24d035e)
- NODE-5934: replace DataView uses with bit math (#649) (6d343ab)
- NODE-5955: use pooled memory when possible (#653) (78c4264)
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
Contributors
Assets 2
v6.3.0
6.3.0 (2024-01-31)
The MongoDB Node.js team is pleased to announce version 6.3.0 of the bson package!
Release Notes
BSON short basic latin string parsing performance improved! 🐎
The BSON library's string decoding logic now attempts to optimize for basic latin (ASCII) characters. This will apply to both BSON keys and BSON values that are or contain strings. If strings are less than 6 bytes we observed approximately ~100% increase in speed while around 15 bytes the performance was about ~30% better. For any non-basic latin bytes or at 20 bytes or greater the BSON library will continue to use Node.js' Buffer.toString API.
The intent is to generally target the deserialization of BSON keys which are often short and only use basic latin, Et tu, _id?
Using a number type as input to the ObjectId constructor is deprecated
Instead, use static createFromTime() to set a numeric value for the new ObjectId.
// previously
new ObjectId(Date.now())
// recommended
ObjectId.createFromTime(Date.now())Features
- NODE-3034: deprecate number as an input to
ObjectIdconstructor (#640) (44bec19) - NODE-5861: optimize parsing basic latin strings (#642) (cdb779b)
Documentation
We invite you to try the bson library immediately, and report any issues to the NODE project.
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.