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.