feat(NODE-7315): Use BSON ByteUtils instead of Nodejs Buffer #4840

PavelSafronov · 2026-01-14T01:14:21Z

Description

Summary of Changes

Use BSON ByteUtils for Buffer.* operations.
This change also removes the Buffer type from multiple internal types.

What is the motivation for this change?

Eliminate the driver's hard dependency on the Node.js Buffer global, making the codebase compatible with standard Web APIs (Uint8Array) and portable to environments like Cloudflare Workers, Deno, and the Browser.

This is the next step to implementing NODE-7300 Replace Buffer with Uint8Array,

Double check the following

Lint is passing (npm run check:lint)
Self-review completed using the steps outlined here
PR title follows the correct format: type(NODE-xxxx)[!]: description
- Example: feat(NODE-1234)!: rewriting everything in coffeescript
Changes are covered by tests
New TODOs have a related JIRA ticket

src/cmap/commands.ts

1. using Uint8Array instead of Buffer in all internal code 2. enabling eslint rule to block Buffer use in src 3. using BSON's ByteUtils in places where we depended on Buffer operations 4. using ByteUtils.isUint8Array instead of Buffer.isBuffer 5. introduced writeInt32LE wrapper that uses the same order of variables, to avoid embarassing mistakes

baileympearson · 2026-01-22T18:05:11Z

src/client-side-encryption/auto_encrypter.ts

    }

-    const commandBuffer = Buffer.isBuffer(cmd) ? cmd : serialize(cmd, options);
+    const commandBuffer: Uint8Array = ByteUtils.isUint8Array(cmd) ? cmd : serialize(cmd, options);


cmd is always a document

Suggested change

const commandBuffer: Uint8Array = ByteUtils.isUint8Array(cmd) ? cmd : serialize(cmd, options);

const commandBuffer: Uint8Array = serialize(cmd, options);

baileympearson · 2026-01-22T18:06:48Z

src/client-side-encryption/client_encryption.ts

    const mongoCryptOptions: MongoCryptOptions = {
      ...options,
-      kmsProviders: !Buffer.isBuffer(this._kmsProviders)
+      kmsProviders: !ByteUtils.isUint8Array(this._kmsProviders)


_kmsProviders should never be a buffer (TS doesn't allow it) - thoughts on removing this check?

baileympearson · 2026-01-22T18:11:40Z

src/cmap/handshake/client_metadata.ts

 import * as process from 'process';

-import { BSON, type Document, Int32, NumberUtils } from '../../bson';
+import { BSON, type Document, fromUTF8, Int32, toUTF8 } from '../../bson';


It looks like we have two separate ways of importing ByteUtils:

importing the BSON object and calling BSON.ByteUtils.<method>

importing the wrapper function from the driver's bson.ts file

Can we consolidate on one or the other? One other option is to export ByteUtils and NumberUtils from bson.ts, and then use those directly.

baileympearson · 2026-01-22T18:15:05Z

src/gridfs/upload.ts

+  const chunkString = chunk as string;
+  const inputBuf = chunkString
+    ? fromUTF8(chunkString)
+    : ByteUtils.toLocalBufferType(chunk as Uint8Array);


Would this work instead?

Suggested change

const chunkString = chunk as string;

const inputBuf = chunkString

? fromUTF8(chunkString)

: ByteUtils.toLocalBufferType(chunk as Uint8Array);

const inputBuf = typeof chunk === 'string'

? fromUTF8(chunkString)

: ByteUtils.toLocalBufferType(chunk);

baileympearson · 2026-01-22T18:16:11Z

src/utils.ts

+import {
+  allocateBuffer,
+  allocateUnsafeBuffer,
+  ByteUtils as BSONByteUtils,


Still necessary, or could we just use ByteUtils now?

baileympearson · 2026-01-22T18:16:20Z

src/utils.ts


 export type AnyOptions = Document;

 export const ByteUtils = {


Can we remove this now?

That would be best, but it's public, wouldn't we be breaking users if we removed this?

baileympearson · 2026-01-22T18:18:32Z

test/tools/runner/config.ts

                  return { number: new Double(value).toExtendedJSON() };
              }
-              if (Buffer.isBuffer(value))
+              if (ByteUtils.isUint8Array(value))


If we also want to remove usages of Buffer from our tests, I think we missed some. Just searching for Buffer. returns a lot more results than are in this PR

For this PR, I was only removing Buffer usages from src, based on this comment in the issue:

Enable no-restricted-globals: ["error", "Buffer"] in ESLint configuration for the src/ directory to prevent regression.

This lead me to believe that we should be focusing on the src folder, and can leave Buffer usages in tests. If we want to remove the usages of Buffer from our tests, I'd like to do it as a follow-up task to this one.

Yes, it's not necessary to remove Buffer from tests right now, but we definitely would want that in the future.

Sergey's offline comment:

We can differentiate between source and test files so it's not necessary to rewrite all the tests right now.

Opened a task to eventually remove Buffer from tests: https://jira.mongodb.org/browse/NODE-7410

baileympearson · 2026-01-22T18:19:15Z

src/bson.ts

+
+// copyBuffer: copies from source buffer to target buffer, returns number of bytes copied
+// inputs are explicitly named to avoid confusion
+export const copyBuffer = (input: {


Is this something we would want to consider putting into BSON's ByteUtils?

Not a bad idea: copying was a bit of a pain to verify and figure out why certain spec tests were failing, would be nice to push this to a common spot. Follow-up task?

baileympearson · 2026-01-22T18:19:55Z

src/bson.ts

+// readInt32LE, reads a 32-bit integer from buffer at given offset
+// throws if offset is out of bounds
+export const readInt32LE = (buffer: Uint8Array, offset: number): number => {
+  validateBufferInputs(buffer, offset, 4);


Is this validation behavior something present in Buffers readInt32LE API and we need to preserve it? Or is it there just-in-case?

It's present in Buffer's readInt32LE and it's something we test for: https://github.com/mongodb/node-mongodb-native/blob/main/test/unit/cmap/commands.test.ts#L124-L127
Removing this check breaks this one test.

baileympearson · 2026-01-22T18:20:54Z

.eslintrc.json

            ]
          }
+        ],
+        "no-restricted-globals": [


If we are removing Buffer usages from tests as well, we'd probably want to enable this lint rule for TS and JS test files too, right?

Addressed above: I think we should remove Buffer from tests in a follow-up task.

addaleax · 2026-01-23T10:11:46Z

src/bson.ts

+export const getFloat64LE = BSON.NumberUtils.getFloat64LE;
+export const getBigInt64LE = BSON.NumberUtils.getBigInt64LE;
+export const toUTF8 = BSON.ByteUtils.toUTF8;
+export const fromUTF8 = BSON.ByteUtils.fromUTF8;


I guess it's too late to change but this PR made me realize that the names toUTF8 and fromUTF8 are reversed semantically – fromUTF8 encodes a string into UTF-8 and toUTF8 decodes a string from UTF-8 😢

oh, great spotted! I feel like we can only change that in future major version, I will create ticket for this

ByteUtils is experimental - we can make changes outside of semver if we want to fix it now

As the driver already rely on toUTF8 method (this one is old, fromUTF8 has been added just recently) , so if we change its' behaviour I believe it will break existing driver functionality, npm install will downloaded newer version of bson.

.eslintrc.json

Co-authored-by: Anna Henningsen <github@addaleax.net>

PavelSafronov added 2 commits January 13, 2026 17:13

using bson for buffer calls

24daacd

removing unnecessary code

51efd36

tadjik1 reviewed Jan 14, 2026

View reviewed changes

src/cmap/commands.ts Outdated Show resolved Hide resolved

PavelSafronov added 7 commits January 14, 2026 11:52

test fixes

74fc9e3

remove onDemand accessors

732b12e

update based on isUint8Array signature change

0ee1a17

remove unnecessary toLocalBufferType calls

5ddfae4

point to bson PR mongodb/js-bson#860

45ebf1e

use bson 7.1.0

79d0d19

PavelSafronov changed the title ~~wip: using bson for buffer calls~~ feat(NODE-7315): Use BSON ByteUtils instead of Nodejs Buffer Jan 16, 2026

PavelSafronov and others added 6 commits January 20, 2026 09:59

pick up BSON 7.1.1

82a34bb

Merge branch 'main' into NODE-7315

fbb742e

resolve conflicts

cbc488c

Merge branch 'main' into NODE-7315

e649b6f

add an easy-to-use copyBuffer method

12ff51f

minor fix: create copy of data

983571b

PavelSafronov marked this pull request as ready for review January 21, 2026 19:10

PavelSafronov requested a review from a team as a code owner January 21, 2026 19:10

PavelSafronov and others added 2 commits January 22, 2026 09:25

remove unnecessary ByteUtils.toLocalBufferType calls

e637852

Merge branch 'main' into NODE-7315

6c9d928

baileympearson self-assigned this Jan 22, 2026

baileympearson added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Jan 22, 2026

baileympearson requested changes Jan 22, 2026

View reviewed changes

PavelSafronov added 2 commits January 22, 2026 13:21

pr feedback

736ba62

lint fix

722379a

addaleax reviewed Jan 23, 2026

View reviewed changes

Apply suggestion from @addaleax

45c9875

Co-authored-by: Anna Henningsen <github@addaleax.net>

	const commandBuffer: Uint8Array = ByteUtils.isUint8Array(cmd) ? cmd : serialize(cmd, options);
	const commandBuffer: Uint8Array = serialize(cmd, options);


		export type AnyOptions = Document;

		export const ByteUtils = {

feat(NODE-7315): Use BSON ByteUtils instead of Nodejs Buffer #4840

Are you sure you want to change the base?

feat(NODE-7315): Use BSON ByteUtils instead of Nodejs Buffer #4840

Conversation

PavelSafronov commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary of Changes

What is the motivation for this change?

Double check the following

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

addaleax Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tadjik1 Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PavelSafronov commented Jan 14, 2026 •

edited

Loading

addaleax Jan 23, 2026 •

edited

Loading

tadjik1 Jan 23, 2026 •

edited

Loading