npm / bson
bson
What changed in bson 7, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-21.
7 breaking2 deprecations5 new APIs and options1 performance1 behavior and defaults2 tooling9 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initbson 727 changes
Breaking changes 7
Throws an exception when a circular reference is detected instead of hanging indefinitely.
A Code with Scope scope containing $ref, $id, and $db is returned as a plain object instead of being promoted to a DBRef instance.
ByteUtils and NumberUtils are no longer available from the onDemand namespace; they have moved to the top-level package export.
BSON now uses JavaScript BigInt syntax and requires a JavaScript engine that supports BigInt literal syntax.
The minimum supported Node.js version is now 20.19.0; Node.js 16 and 18 are no longer supported.
The ObjectId constructor no longer accepts a number; use ObjectId.createFromTime() to create an ObjectId from a numeric timestamp.
BSON no longer includes atob, btoa, and TextEncoder polyfills for React Native builds because Hermes supports them natively.
Deprecations 2
Long methods and operations that are inapplicable to Timestamp are now marked deprecated; use the .t and .i accessors for its timestamp components.
The BSON Binary subtype 2 constant is now deprecated to align with the BSON specification.
New APIs and options 5
ByteUtils now provides a copy() method that behaves identically to Node.js Buffer.copy().
EJSON.stringify and EJSON.serialize accept ignoreUndefined to skip keys whose values are undefined; it defaults to false.
ByteUtils is now a public top-level export providing platform-agnostic tools to manipulate binary data; it is experimental and may change.
NumberUtils is now exported from the BSON package for reading to and from buffers of bytes; it is experimental and may change.
BSON value classes now expose a bsonType symbol property as an alias for _bsontype, distinguishing wrapper instances from documents with arbitrary keys.
Performance 1
Stores its 12 bytes as four inline integers instead of a Uint8Array, cutting per-ObjectId memory by about 63% with no serialization slowdown.
Behavior and default changes 1
All BSON bundles now use globalThis.crypto for random byte generation; the Node.js bundle no longer requires crypto.
Tooling 2
isUint8Array now uses a type predicate.
The TypeScript target has been updated to ES2023.
Fixes and other changes 9
Returns accurate byte counts for Int32 and BSONSymbol values, correcting a previous 12-byte overcount per value.
Properly accounts for ES Map objects when calculating size; serialization was not affected.
Avoids crypto calls during module initialization, which are forbidden by Cloudflare Workers and other environments.
Uses the first instant of year 10000 as the relaxed EJSON date bound instead of a date five hours after the maximum limit.
ObjectId startup snapshot API calls now use optional chaining, preventing a TypeError in environments with a stubbed or partial process global.
The constructor coerces subtype inputs to match BSON serialization, keeping the subtype property consistent with the serialized value.
Serialization, deserialization, and object-size calculation use iterative algorithms, so sufficiently nested documents no longer exhaust the call stack.
The space parameter is no longer discarded when stringify is called with value, options, and space, enabling formatted output for that signature.
Reverts a breaking change to the onDemand namespace, restoring compatibility with v7.0.0 of the MongoDB Node.js Driver.