Skip to content

Releases: mongodb/js-bson

v6.0.0

28 Aug 15:39
@github-actions github-actions
v6.0.0
7b98403
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
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)

false

Removed deprecated UUID.cacheHexString property

This property was unused and so was removed.

⚠ BREAKING CHANGES

Bug Fixes

Documentation

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

Contributors

vanstinator
Assets 2
Loading

v5.4.0

05 Jul 18:19
@nbbeeken nbbeeken
v5.4.0
4c1db9a
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.
Compare
Choose a tag to compare
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.

Assets 2
Loading

v5.3.0

10 May 20:56
@nbbeeken nbbeeken
v5.3.0
c74d177
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
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

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

Assets 2
Loading

v5.2.0

04 Apr 16:10
@nbbeeken nbbeeken
v5.2.0
91b84ed
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
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

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

Assets 2
Loading

v5.1.0

16 Mar 20:10
@W-A-James W-A-James
v5.1.0
5d2648e
This commit was signed with the committer’s verified signature.
W-A-James Warren James
GPG key ID: E4D6840F533AA14D
Learn about vigilant mode.
Compare
Choose a tag to compare
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

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

Assets 2
Loading

v5.0.1

16 Feb 19:00
@nbbeeken nbbeeken
v5.0.1
b6a15b5
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
v5.0.1

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

Bug Fixes

Documentation

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

Assets 2
Loading

v5.0.0

31 Jan 19:26
@nbbeeken nbbeeken
v5.0.0
ddb7ec8
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
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

Features

Use BigInt with BSON and EJSON

Other Features

Removals and Breaking Fixes

Bug Fixes

Documentation

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

Assets 2
Loading

v5.0.0-alpha.3

20 Jan 15:04
@nbbeeken nbbeeken
v5.0.0-alpha.3
8bba395
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
v5.0.0-alpha.3 Pre-release
Pre-release

🚧 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)

Assets 2
Loading

v5.0.0-alpha.2

10 Jan 21:43
@nbbeeken nbbeeken
v5.0.0-alpha.2
ff249e9
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
v5.0.0-alpha.2 Pre-release
Pre-release

🚧 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)

Assets 2
Loading

v4.7.2

10 Jan 20:49
@nbbeeken nbbeeken
v4.7.2
c3fc5df
This commit was signed with the committer’s verified signature.
nbbeeken Neal Beeken
GPG key ID: 22F3C38EA1A0C076
Learn about vigilant mode.
Compare
Choose a tag to compare
v4.7.2

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

Bug Fixes

Documentation

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

Assets 2
Loading