v6.9.1

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.

v6.8.1

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.

v6.7.1

6.7.1 (2025-03-06)

The MongoDB Node.js team is pleased to announce version 6.7.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-6828: incorrect negative bigint handling (#773) (7ab9f7f)

Documentation

• API
• Changelog

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

v6.6.1

6.6.1 (2025-03-06)

The MongoDB Node.js team is pleased to announce version 6.6.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-6827: incorrect negative bigint handling (#771) (18e6578)

Documentation

• API
• Changelog

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

v6.5.1

6.5.1 (2025-03-06)

The MongoDB Node.js team is pleased to announce version 6.5.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-6826: incorrect negative bigint handling (#772) (66af3fe)

Documentation

• API
• Changelog

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

v6.4.1

6.4.1 (2025-03-05)

The MongoDB Node.js team is pleased to announce version 6.4.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.

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 change in BSON@6.4.0 (2024-02-29) 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.

Bug Fixes

• NODE-6812: incorrect negative bigint handling (#762) (ce3e544)
• NODE-6818: flip byte order depending on system endianness (#766) (8a55718)

Documentation

• API
• Changelog

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

v6.10.3

6.10.3 (2025-02-19)

The MongoDB Node.js team is pleased to announce version 6.10.3 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-6764: incorrect negative bigint handling (#752) (b3212b4)

Documentation

• API
• Changelog

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

v6.10.2

6.10.2 (2025-01-29)

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

Release Notes

Fix calculateObjectSize not accounting for BigInt value size

BSON.calculateObjectSize was missing a condition for BigInt values, meaning it did not account for them in the same way that it would for Long values. This has been corrected so that Bigint values contribute 8 bytes worth of size to the total count.

We also added a new default condition that will catch any new values that may be returned by typeof in the future and will throw an error rather than returning an inaccurate size.

Bug Fixes

• NODE-6608: calculateObjectSize returns the wrong value for bigint (#742) (1fed073)

Documentation

• API
• Changelog

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

v6.10.1

6.10.1 (2024-11-27)

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

Release Notes

Fix issue with the internal unbounded type cache

As an optimization, a previous performance improvement stored the type information of seen objects to avoid recalculating type information. This caused an issue in the driver under extreme load and high memory usage as the cache grew. The assumption was that garbage collection would clear it enough to sustain normal operation. The cache is now removed and other optimal type checking is used in its place.

Cache the hex string of an ObjectId lazily

When ObjectId.cacheHexString is set to true we no longer convert the buffer to a hex string in the constructor, since the cache is already being filled in any call to objectid.toHexString().

Additionally, if a string is passed into the constructor we can cache this immediately as there is no performance impact and no extra memory that needs to be allocated.

This improves the performance for situations where you are parsing ObjectIds from a string (ex. JSON) and want to avoid recalculating the hex. It also improves situations where you have ObjectIds coming from BSON and only convert some of them strings perhaps after applying some filter to eliminate some.

With cacheHexString enabled deserializing ObjectIds from BSON shows ~80% performance improvement and toString-ing ObjectIds that were constructed from a string convert ~40% faster!

Thanks to @SeanReece for contributing this improvement!

Bug Fixes

• NODE-6552: remove cache and use toStringTag in type helpers (#740) (3ede13e)

Performance Improvements

• NODE-6450: Lazy objectId hex string cache (#722) (7c37580)

Documentation

• API
• Changelog

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

v6.10.0

6.10.0 (2024-11-18)

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

Release Notes

BSON Binary Vector Support!

The Binary class has new helpers to assist with using the newly minted Vector sub_type of Binary sub_type == 9 🎉! For more on how these types can be used with MongoDB take a look at How to Ingest Quantized Vectors!

Here's a summary of the API:

class Binary {
  toInt8Array(): Int8Array;
  toFloat32Array(): Float32Array;
  toPackedBits(): Uint8Array;

  static fromInt8Array(array: Int8Array): Binary;
  static fromFloat32Array(array: Float32Array): Binary;
  static fromPackedBits(array: Uint8Array, padding: number = 0): Binary;
}

Relatively self-explanatory: each one supports converting to and constructing from a native Javascript data type that corresponds to one of the three vector types: Int8, Float32, PackedBit.

Vector Bytes Format

When a Binary is sub_type 9 the first two bytes are set to important metadata about the vector.

• binary.buffer[0] - The datatype that indicates what the following bytes are.
• binary.buffer[1] - The padding amount, a value 0-7 that indicates how many bits to ignore in a PackedBit vector.

Packed Bits 📦

static fromPackedBits(array: Uint8Array, padding: number = 0)

When handling packed bits, the last byte may not be entirely used. For example, a PackedBit vector = [0xFF, 0xF0] with padding = 4 ignores those last four 0s making the bit vector logically equal to 12 ones.

    F    F    F    0
[1111 1111 1111]   // ignored: the four 0s are padding

Important

When using the fromPackedBits method to set your padding amount to avoid inadvertently extending your bit vector.

Unpacking Bits 🧳

Packed bits get special treatment with two styles of conversion methods to suit your vector-y needs. toBits will return individually addressable bits shifted apart into an array. fromBits takes the same format in reverse and packs the bits into bytes.

Notice there is no argument to set the padding. That is because it can be determined by the array's length. Recall those 12 ones from the previous example, well, the padding has to be 4 to reach a multiple of 8.

class Binary {
  toBits(): Int8Array;
  static fromBits(bits: ArrayLike<number>): Binary;
}

Caution

We highly encourage using ONLY these methods to interact with vector data and avoid operating directly on the byte format. Other Binary class methods (put(), write() read(), and value()) and direct access of data in a Binary's buffer beyond the 1st index should only be used in exceptional circumstances and with extreme caution after closely consulting the BSON Vector specification.

Details to keep in mind

• A javascript engine's endianness is platform dependent whereas BSON is always in little-endian format so if viewing bytes as Float32s take care to re-order bytes as needed.
• Int8 vectors are signed bytes but read() always returns unsigned bytes.
• The vector data begins at offset 2.

Binary's read() returns a view of Binary.buffer

Binary's read() return type claimed it would return number[] or Uint8Array which was true in previous BSON versions that didn't always store a Uint8Array on the buffer property like Binary does today.

read()'s length parameter did not respect the position value allowing reading bytes beyond the data that is actually stored in the Binary. This has been corrected.

Additionally, this method returned a view in Node.js environments and a copy in Web environments. it has been fixed to always return a view.

Features

• NODE-6537: add support for binary vectors (#730) (d7bdcec)

Bug Fixes

• NODE-6536: Binary.read never returns number[] and reads beyond content (#727) (f99fdfd)

Documentation

• API
• Changelog

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