# What changed in bson

> 27 changes in bson 7 from its official release notes, upgrade guides and advisories: 7 breaking, 2 deprecations, 5 new APIs and options. Each one cited. Sources checked 2026-10-21. HTML: https://unstale.sh/npm/bson/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## bson 7

### Breaking changes

- Throws an exception when a circular reference is detected instead of hanging indefinitely. (7.3.3) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.3)
- A Code with Scope scope containing $ref, $id, and $db is returned as a plain object instead of being promoted to a DBRef instance. (7.3.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.0)
- ByteUtils and NumberUtils are no longer available from the onDemand namespace; they have moved to the top-level package export. (7.1.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.1.0)
- BSON now uses JavaScript BigInt syntax and requires a JavaScript engine that supports BigInt literal syntax. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)
- The minimum supported Node.js version is now 20.19.0; Node.js 16 and 18 are no longer supported. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)
- The ObjectId constructor no longer accepts a number; use ObjectId.createFromTime() to create an ObjectId from a numeric timestamp. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)
- BSON no longer includes atob, btoa, and TextEncoder polyfills for React Native builds because Hermes supports them natively. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)

### Deprecations

- Long methods and operations that are inapplicable to Timestamp are now marked deprecated; use the .t and .i accessors for its timestamp components. (7.3.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.0)
- The BSON Binary subtype 2 constant is now deprecated to align with the BSON specification. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)

### New APIs and options

- ByteUtils now provides a copy() method that behaves identically to Node.js Buffer.copy(). (7.2.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.2.0)
- EJSON.stringify and EJSON.serialize accept ignoreUndefined to skip keys whose values are undefined; it defaults to false. (7.2.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.2.0)
- ByteUtils is now a public top-level export providing platform-agnostic tools to manipulate binary data; it is experimental and may change. (7.1.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.1.0)
- NumberUtils is now exported from the BSON package for reading to and from buffers of bytes; it is experimental and may change. (7.1.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.1.0)
- BSON value classes now expose a bsonType symbol property as an alias for _bsontype, distinguishing wrapper instances from documents with arbitrary keys. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)

### Performance

- Stores its 12 bytes as four inline integers instead of a Uint8Array, cutting per-ObjectId memory by about 63% with no serialization slowdown. (7.3.2) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.2)

### Behavior and default changes

- All BSON bundles now use globalThis.crypto for random byte generation; the Node.js bundle no longer requires crypto. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)

### Tooling

- isUint8Array now uses a type predicate. (7.1.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.1.0)
- The TypeScript target has been updated to ES2023. (7.0.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.0.0)

### Fixes and other changes

- Returns accurate byte counts for Int32 and BSONSymbol values, correcting a previous 12-byte overcount per value. (7.3.2) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.2)
- Properly accounts for ES Map objects when calculating size; serialization was not affected. (7.3.2) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.2)
- Avoids crypto calls during module initialization, which are forbidden by Cloudflare Workers and other environments. (7.3.2) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.2)
- Uses the first instant of year 10000 as the relaxed EJSON date bound instead of a date five hours after the maximum limit. (7.3.2) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.2)
- ObjectId startup snapshot API calls now use optional chaining, preventing a TypeError in environments with a stubbed or partial process global. (7.3.1) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.1)
- The constructor coerces subtype inputs to match BSON serialization, keeping the subtype property consistent with the serialized value. (7.3.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.0)
- Serialization, deserialization, and object-size calculation use iterative algorithms, so sufficiently nested documents no longer exhaust the call stack. (7.3.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.0)
- The space parameter is no longer discarded when stringify is called with value, options, and space, enabling formatted output for that signature. (7.3.0) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.3.0)
- Reverts a breaking change to the onDemand namespace, restoring compatibility with v7.0.0 of the MongoDB Node.js Driver. (7.1.1) — [release notes](https://github.com/mongodb/js-bson/releases/tag/v7.1.1)