7.2.0 (2026-01-29)

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

Release Notes

EJSON now supports ignoreUndefined

serialize supports an option, ignoreUndefined, which instructs the serializer to skip any keys whose values are undefined.

This option has been added to EJSON:

> EJSON.stringify({ a: undefined }, { ignoreUndefined: true });
'{}'
> EJSON.stringify({ a: undefined }, { ignoreUndefined: false });
'{"a":null}'
> EJSON.serialize({ a: undefined }, { ignoreUndefined: true });
{}
> EJSON.serialize({ a: undefined }, { ignoreUndefined: false });
{ a: null }

This option defaults to false.

Buffer.copy() now present in ByteUtils

ByteUtils now contains a copy() method, we behaves identically to Nodejs' Buffer.copy() method.

Features

• NODE-7328: Add ignoreUndefined option to EJSON APIs (#853) (5cf00c2)
• NODE-7414: add copy method to ByteUtils (#867) (ffa77c6)

Documentation

• API
• Changelog

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

7.1.1 (2026-01-17)

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

Release Notes

Fix breaking change to onDemand namespace

This fix reverts the breaking change made as part of NODE-7334 and restores compatibility with v7.0.0 of the MongoDB Node.js Driver.

Bug Fixes

• NODE-7399: revert bson PR 859 / NODE-7334 (#861) (6511e0d)

Documentation

• API
• Changelog

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

7.1.0 (2026-01-16)

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

Release Notes

ByteUtils added as a binary utillity

ByteUtils are now public and provide set of platform-agnostic tools to manipulate binary data (using Buffer in nodejs-compatible environments and fallback to Uint8Array).

NumberUtils is now exported in the library

BSON maintains a set of utilities for reading to and from buffers of bytes. This module is now exported from the BSON package.

import { NumberUtils } from 'bson';

ByteUtils and NumberUtils removed from onDemand namespace

The experimental ByteUtils and NumberUtils helpers have been moved from the onDemand namespace to the top-level package export.

Features

• NODE-7314: export byteUtils & add missing methods (#852) (a31c90e)
• NODE-7316: export number utils (#850) (a23e788)
• NODE-7334: remove ByteUtils and NumberUtils from the onDemand ns (#859) (92bbc34)

Bug Fixes

• NODE-7397: Use type predicate for isUint8Array (#860) (89b3a2b)

Documentation

• API
• Changelog

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

7.0.0 (2025-11-05)

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

Release Notes

⚠ Breaking Changes

Minimum supported Node.js version now 20.19.0

The minimum supported Node.js version is now v20.19.0. 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. Our TypeScript target has also been updated to ES2023.

BSON now requires BigInt literal support

BSON now uses Javascript BigInt syntax and requires a JS engine with support for BigInt literal syntax.

All BSON bundles now use globalThis.crypto for random byte generation

Until [email protected], BSON has supported Node.js v16. Node.js v16 does not include crypto in the global object, which necessitated importing crypto from node:crypto. This require has caused many headaches for bundlers. We improved the situation in NODE-6074, but this release updates our Node.js bundle to rely on the global object instead and removes all requires from the bundle.

BSON no longer vendors atob, btoa, and TextEncoder for react native builds

The React Native JS engine (Hermes) now supports atob, btoa, and TextEncoder natively and polyfills are no longer needed. BSON no longer includes these polyfills for react native builds.

ObjectId constructor no longer accepts a number

If you wish to create an ObjectId from a numeric timestamp, use ObjectId.createFromTime() instead.

BSON Binary subtype 2 constant deprecated

BSON Binary subtype 2 was previously deprecated in the BSON specification, but the corresponding subtype constant remained available in the BSON library. This constant has now been deprecated to align with the specification.

Non-breaking Features

New bsonType symbol property as an alias for _bsontype

JS classes representing BSON values now have a bsonType symbol property as an alias for the existing _bsontype property. This makes it easier to distinguish between values of a specific BSON type and documents with arbitrary keys after deserializing:

import { bsonType, deserialize } from 'bson';

const doc = deserialize(...);
// will be set when doc.value is a BSON wrapper class **or** a sub-document { _bsontype: '...' } 
console.log(doc.value._bsontype); 
// will be set if and only if doc.value is a BSON wrapper class
console.log(doc.value[bsonType]);

It is safe to replace all uses of value._bsontype with value[bsonType].

All Changes

• NODE-5763: remove support for new ObjectId(<number>) (#824) (21cc3ff)
• NODE-6321: remove require('crypto') from Nodejs bundle (#825) (7ba8917)
• NODE-6625: remove support for Node 16 and 18 (#821) (f636254)
• NODE-7019: remove react native vendor polyfills (#827) (883f238)
• NODE-7098: use bigint literal syntax (#826) (94bf732)
• NODE-7099: deprecate BSON binary subtype 2 constant (#812) (f61946d)
• NODE-7255: add well-known Symbol alias for _bsontype (#829) (1e1b619)
• bump BSON_MAJOR_VERSION to 7 (#832) (3ada791)

Documentation

• API
• Changelog

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

7.0.0-alpha.2 (2025-10-24)

Bug Fixes

• NODE-7271: revert private property usage in ObjectId (#835) (79faf75)

7.0.0-alpha.1 (2025-10-21)

⚠ BREAKING CHANGES

• bump BSON_MAJOR_VERSION to 7 (#832)

Features

• bump BSON_MAJOR_VERSION to 7 (#832) (3ada791)

7.0.0-alpha (2025-10-21)

⚠ BREAKING CHANGES

• NODE-7098: use bigint literal syntax (#826)
• NODE-5763: remove support for new ObjectId() (#824)
• NODE-6625: remove support for Node 16 and 18 (#821)

Features

• NODE-5763: remove support for new ObjectId(<number>) (#824) (21cc3ff)
• NODE-6321: remove require('crypto') from Nodejs bundle (#825) (7ba8917)
• NODE-6625: remove support for Node 16 and 18 (#821) (f636254)
• NODE-7019: remove react native vendor polyfills (#827) (883f238)
• NODE-7098: use bigint literal syntax (#826) (94bf732)
• NODE-7099: deprecate BSON binary subtype 2 constant (#812) (f61946d)
• NODE-7255: add well-known Symbol alias for _bsontype (#829) (1e1b619)

6.10.4 (2025-06-02)

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

Release Notes

Top-Level Await removed from the browser BSON bundle

In versions <6.10.4, BSON uses a top-level await to asynchronously import the crypto module. This change unintentionally caused headaches for users of webpack, react native, vite and other tools bundlers and tools.

The top-level await has been removed from all BSON bundles. Thanks to @lourd for this contribution.

Prevent the creation of incorrectly sized float32 vectors

This adds validation to our BSON.serialize and EJSON.stringify methods that will prevent creating float 32 vectors that are not a multiple of 4. Previously created vectors that do not meet this validation will still be deserialized and parsed so they can be fixed.

Additionally, the toFloat32Array(), toInt8Array(), and toPackedBits() methods now perform the same validation that serialize does to prevent use of incorrectly formatted Binary vector values. (For example, a packed bits vector with more than 7 bits of padding)

Vectors of an incorrect length could only be made manually (directly constructing the bytes and calling new Binary). We recommend using toFloat32Array and fromFloat32Array when interacting with Vectors in MongoDB as they handle the proper creation and translation of this data type.

Bug Fixes

• NODE-6074: Removes top-level await in bson with separate node and browser ESM bundles (#749) (4602973)
• NODE-6735, NODE-6711: add BSON vector validation to EJSON stringification, serialization and conversion to native types (#748) (64ff6a2)

Documentation

• API
• Changelog

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

6.9.1 (2025-03-06)

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

Release Notes

⚠️ Fixed potential data corruption bug when useBigInt64 is enabled

After refactoring to improve deserialization performance in #649, we inadvertently introduced a bug that manifested when deserializing Long values with the useBigInt64 flag enabled. The bug would lead to negative Long values being deserialized as unsigned integers. This issue has been resolved here.

Thanks to @rkistner for reporting this bug!

Bug Fixes

• NODE-6830: incorrect negative bigint handling (#752) (#776) (b13d730)

Documentation

• API
• Changelog

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

6.8.1 (2025-03-06)

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

Release Notes

⚠️ Fixed potential data corruption bug when useBigInt64 is enabled

After refactoring to improve deserialization performance in #649, we inadvertently introduced a bug that manifested when deserializing Long values with the useBigInt64 flag enabled. The bug would lead to negative Long values being deserialized as unsigned integers. This issue has been resolved here.

Bug Fixes

• NODE-6829: incorrect negative bigint handling (#774) (1bf4665)

Documentation

• API
• Changelog

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