7.3.3 (2026-09-11)

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

Release Notes

Fixed BSON.calculateObjectSize infinite hang

Fixed a bug where BSON.calculateObjectSize would hang indefinitely on an object containing a circular reference. The method now throws an exception when a circular reference is detected.

Also a big thank you to @mcmorisi for his contribution on #912 security warning in EJSON.parse documentation!

Bug Fixes

• NODE-7696: calculateObjectSize hangs indefinitely on an object containing a circular reference (#926) (f35af5c)

Documentation

• API
• Changelog

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

7.3.2 (2026-07-31)

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

Release Notes

calculateObjectSize() now returns accurate byte counts for Int32 and BSONSymbol

Previously, each Int32 or BSONSymbol value caused a 12-byte overcount.

calculateObjectSize() now yields proper size calculations on ES Map's

This release of js-bson fixes an issue where we were incorrectly considering ES Map objects inside calculateObjectSize. This issue did not impact serialization, just size calculation.

Fixed incorrect date boundary in relaxed EJSON

This release of js-bson fixes an issue where the date boundary for relaxed EJSON was incorrectly set to a date 5 hours after the maximum limit of 10,000 AD.

Fixed an issue with ObjectId initialization in Cloudflare Workers

This release of js-bson fixes an issue where we were making crypto calls during module initialization, which is forbidden by Cloudflare Workers and other environments.

Memory optimization via smaller ObjectIds

ObjectId now stores its 12 bytes as four inline integers instead of a Uint8Array, cutting per-ObjectId memory by about 63% (and roughly 45 to 47% across large result sets) with no serialization slowdown. Deep equality and cloning are preserved (assert.deepStrictEqual, and lodash isEqual / cloneDeep).

Thanks to @spokodev for contributing their fixes! (NODE-7631 (#901), NODE-7645 (#917), NODE-7646 (#910))

Bug Fixes

• NODE-7631: count Int32 and BSONSymbol in calculateObjectSize (#901) (7f948a6)
• NODE-7645: use the first instant of year 10000 as the relaxed EJSON date bound (#917) (9272c9a)
• NODE-7646: count ES Map entries in calculateObjectSize (#910) (8d28b12)
• NODE-7667: remove early initialization from ObjectId (#916) (665286f)

Performance Improvements

• NODE-6246: store ObjectId bytes as four packed integers (#893) (a84229c)

Documentation

• API
• Changelog

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

7.3.1 (2026-06-23)

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

Release Notes

ObjectId initialization now tolerates partial process polyfills

Adds optional chaining to Node.js startup snapshot API calls in ObjectId so that environments with a stubbed or partial process global no longer throw a TypeError at startup.

Bug Fixes

• NODE-7630: make startup snapshot calls more defensive (#899) (99433cd)

Documentation

• API
• Changelog

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

7.3.0 (2026-06-17)

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

Release Notes

Deprecated inapplicable Long members on Timestamp

Timestamp inherits from Long for storage convenience, but it is semantically a (t, i) pair, not a general 64-bit integer. If you have called Long methods directly on Timestamp instances (for example toNumber(), getHighBits(), getLowBits(), or aithmetic and bitwise operations), those are now marked @deprecated with no runtime behavior changes. The .t and .i accessors provide direct, semantically consistent access to the two timestamp components.

BSON operations no longer throw on deeply nested documents

Core serialization and deserialization function (serialize, deserialize, calculateObjectSize) have been rewritten as iterative algorithms, so a sufficiently-nested document will no longer exhaust the call stack.

Behavior change: Code with Scope scopes are no longer promoted to DBRef

As a side effect of the rewrite, a Code with Scope scope that happens to carry $ref, $id, and $db keys is no longer promoted to a DBRef instance. The scope is returned as a plain object, which is the correct behavior: a scope represents JavaScript variable bindings, not a document reference.

new Binary(buffer, subType) now coerces subType to match BSON bytes

The Binary constructor now normalizes subtype inputs to match BSON serialization. Previously, passing a stringified subtype like '4' would cause a mismatch between the sub_type property (string '4') and the serialized BSON value (0x04). The constructor now converts inputs to ensure consistency.

EJSON.stringify now correctly handles all parameter combinations

Previously, calling EJSON.stringify(value, options, space) silently discarded the space parameter, producing unformatted output. This has been fixed so all documented call signatures work as expected:

// This now correctly produces indented canonical EJSON
EJSON.stringify(doc, { relaxed: false }, 2);

Thanks to @chdanielmueller for working on this problem!

ObjectId generates unique values across Node.js startup snapshot processes

ObjectId now resets its random state (process-unique bytes and counter seed) when a process restores from a Node.js startup snapshot. Previously these values were frozen into the snapshot blob, causing processes restored from the same snapshot to generate colliding ObjectIds.

Features

• NODE-7069: deprecate Long members inapplicable to Timestamp (#887) (c5d1dd8)

Bug Fixes

• NODE-5937: rewrite deserializeObject as iterative, not recursive (#886) (0231603)
• NODE-7354: eagerly make Binary sub_type into a number (#858) (5b42c5a)
• NODE-7436: EJSON.stringify type signature (#870) (c949780)
• NODE-7575: reset ObjectId state when building startup snapshot (#884) (ba29d33)

Documentation

• API
• Changelog

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

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 BSON@7.x, 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)