bson 7.0.0 → 7.1.0

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -48,7 +48,7 @@
     "magic-string": "^0.30.11",
     "mocha": "^11.7.1",
     "node-fetch": "^3.3.2",
-    "nyc": "^15.1.0",
+    "nyc": "^17.1.0",
     "prettier": "^3.5.3",
     "rollup": "^4.40.1",
     "sinon": "^21.0.0",

package/src/bson.ts

@@ -48,7 +48,9 @@ export {
   MinKey,
   MaxKey,
   BSONRegExp,
-  Decimal128
+  Decimal128,
+  NumberUtils,
+  ByteUtils
 };
 export { BSONValue, bsonType, type BSONTypeTag } from './bson_value';
 export { BSONError, BSONVersionError, BSONRuntimeError, BSONOffsetError } from './error';

package/src/parser/on_demand/index.ts

@@ -1,5 +1,3 @@
-import { ByteUtils } from '../../utils/byte_utils';
-import { NumberUtils } from '../../utils/number_utils';
 import { type BSONElement, parseToElements } from './parse_to_elements';
 /**
  * @experimental
@@ -11,10 +9,6 @@ export type OnDemand = {
   parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
   // Types
   BSONElement: BSONElement;
-
-  // Utils
-  ByteUtils: ByteUtils;
-  NumberUtils: NumberUtils;
 };
 
 /**
@@ -24,8 +18,6 @@ export type OnDemand = {
 const onDemand: OnDemand = Object.create(null);
 
 onDemand.parseToElements = parseToElements;
-onDemand.ByteUtils = ByteUtils;
-onDemand.NumberUtils = NumberUtils;
 
 Object.freeze(onDemand);
 

package/src/utils/byte_utils.ts

@@ -9,18 +9,26 @@ import { webByteUtils } from './web_byte_utils';
  * ByteUtils is configured at load time to use Node.js or Web based APIs for the internal implementations.
  */
 export type ByteUtils = {
+  /** Checks if the given value is a Uint8Array. */
+  isUint8Array: (value: unknown) => value is Uint8Array;
   /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
   toLocalBufferType: (buffer: Uint8Array | ArrayBufferView | ArrayBuffer) => Uint8Array;
   /** Create empty space of size */
   allocate: (size: number) => Uint8Array;
   /** Create empty space of size, use pooled memory when available */
   allocateUnsafe: (size: number) => Uint8Array;
+  /** Compare 2 Uint8Arrays lexicographically */
+  compare: (buffer1: Uint8Array, buffer2: Uint8Array) => -1 | 0 | 1;
+  /** Concatenating all the Uint8Arrays in new Uint8Array. */
+  concat: (list: Uint8Array[]) => Uint8Array;
   /** Check if two Uint8Arrays are deep equal */
   equals: (a: Uint8Array, b: Uint8Array) => boolean;
-  /** Check if two Uint8Arrays are deep equal */
+  /** Create a Uint8Array from an array of numbers */
   fromNumberArray: (array: number[]) => Uint8Array;
   /** Create a Uint8Array from a base64 string */
   fromBase64: (base64: string) => Uint8Array;
+  /** Create a Uint8Array from a UTF8 string */
+  fromUTF8: (utf8: string) => Uint8Array;
   /** Create a base64 string from bytes */
   toBase64: (buffer: Uint8Array) => string;
   /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
@@ -58,6 +66,7 @@ const hasGlobalBuffer = typeof Buffer === 'function' && Buffer.prototype?._isBuf
  * The type annotation is important here, it asserts that each of the platform specific
  * utils implementations are compatible with the common one.
  *
- * @internal
+ * @public
+ * @experimental
  */
 export const ByteUtils: ByteUtils = hasGlobalBuffer ? nodeJsByteUtils : webByteUtils;

package/src/utils/node_byte_utils.ts

@@ -1,6 +1,7 @@
 import { BSONError } from '../error';
 import { parseUtf8 } from '../parse_utf8';
 import { tryReadBasicLatin, tryWriteBasicLatin } from './latin';
+import { isUint8Array } from '../parser/utils';
 
 type NodeJsEncoding = 'base64' | 'hex' | 'utf8' | 'binary';
 type NodeJsBuffer = ArrayBufferView &
@@ -10,6 +11,7 @@ type NodeJsBuffer = ArrayBufferView &
     toString: (this: Uint8Array, encoding: NodeJsEncoding, start?: number, end?: number) => string;
     equals: (this: Uint8Array, other: Uint8Array) => boolean;
     swap32: (this: NodeJsBuffer) => NodeJsBuffer;
+    compare: (this: Uint8Array, other: Uint8Array) => -1 | 0 | 1;
   };
 type NodeJsBufferConstructor = Omit<Uint8ArrayConstructor, 'from'> & {
   alloc: (size: number) => NodeJsBuffer;
@@ -21,6 +23,7 @@ type NodeJsBufferConstructor = Omit<Uint8ArrayConstructor, 'from'> & {
   from(base64: string, encoding: NodeJsEncoding): NodeJsBuffer;
   byteLength(input: string, encoding: 'utf8'): number;
   isBuffer(value: unknown): value is NodeJsBuffer;
+  concat(list: Uint8Array[]): NodeJsBuffer;
 };
 
 // This can be nullish, but we gate the nodejs functions on being exported whether or not this exists
@@ -51,8 +54,13 @@ const nodejsRandomBytes = (() => {
   }
 })();
 
-/** @internal */
+/**
+ * @public
+ * @experimental
+ */
 export const nodeJsByteUtils = {
+  isUint8Array: isUint8Array,
+
   toLocalBufferType(potentialBuffer: Uint8Array | NodeJsBuffer | ArrayBuffer): NodeJsBuffer {
     if (Buffer.isBuffer(potentialBuffer)) {
       return potentialBuffer;
@@ -88,6 +96,14 @@ export const nodeJsByteUtils = {
     return Buffer.allocUnsafe(size);
   },
 
+  compare(a: Uint8Array, b: Uint8Array) {
+    return nodeJsByteUtils.toLocalBufferType(a).compare(b);
+  },
+
+  concat(list: Uint8Array[]): NodeJsBuffer {
+    return Buffer.concat(list);
+  },
+
   equals(a: Uint8Array, b: Uint8Array): boolean {
     return nodeJsByteUtils.toLocalBufferType(a).equals(b);
   },
@@ -100,6 +116,10 @@ export const nodeJsByteUtils = {
     return Buffer.from(base64, 'base64');
   },
 
+  fromUTF8(utf8: string): NodeJsBuffer {
+    return Buffer.from(utf8, 'utf8');
+  },
+
   toBase64(buffer: Uint8Array): string {
     return nodeJsByteUtils.toLocalBufferType(buffer).toString('base64');
   },

package/src/utils/web_byte_utils.ts

@@ -1,6 +1,7 @@
 import { BSONError } from '../error';
 import { tryReadBasicLatin } from './latin';
 import { parseUtf8 } from '../parse_utf8';
+import { isUint8Array } from '../parser/utils';
 
 type TextDecoder = {
   readonly encoding: string;
@@ -69,8 +70,13 @@ const webRandomBytes: (byteLength: number) => Uint8Array = (() => {
 
 const HEX_DIGIT = /(\d|[a-f])/i;
 
-/** @internal */
+/**
+ * @public
+ * @experimental
+ */
 export const webByteUtils = {
+  isUint8Array: isUint8Array,
+
   toLocalBufferType(
     potentialUint8array: Uint8Array | ArrayBufferViewWithTag | ArrayBuffer
   ): Uint8Array {
@@ -114,12 +120,47 @@ export const webByteUtils = {
     return webByteUtils.allocate(size);
   },
 
-  equals(a: Uint8Array, b: Uint8Array): boolean {
-    if (a.byteLength !== b.byteLength) {
+  compare(uint8Array: Uint8Array, otherUint8Array: Uint8Array): -1 | 0 | 1 {
+    if (uint8Array === otherUint8Array) return 0;
+
+    const len = Math.min(uint8Array.length, otherUint8Array.length);
+
+    for (let i = 0; i < len; i++) {
+      if (uint8Array[i] < otherUint8Array[i]) return -1;
+      if (uint8Array[i] > otherUint8Array[i]) return 1;
+    }
+
+    if (uint8Array.length < otherUint8Array.length) return -1;
+    if (uint8Array.length > otherUint8Array.length) return 1;
+
+    return 0;
+  },
+
+  concat(uint8Arrays: Uint8Array[]): Uint8Array {
+    if (uint8Arrays.length === 0) return webByteUtils.allocate(0);
+
+    let totalLength = 0;
+    for (const uint8Array of uint8Arrays) {
+      totalLength += uint8Array.length;
+    }
+
+    const result = webByteUtils.allocate(totalLength);
+    let offset = 0;
+
+    for (const uint8Array of uint8Arrays) {
+      result.set(uint8Array, offset);
+      offset += uint8Array.length;
+    }
+
+    return result;
+  },
+
+  equals(uint8Array: Uint8Array, otherUint8Array: Uint8Array): boolean {
+    if (uint8Array.byteLength !== otherUint8Array.byteLength) {
       return false;
     }
-    for (let i = 0; i < a.byteLength; i++) {
-      if (a[i] !== b[i]) {
+    for (let i = 0; i < uint8Array.byteLength; i++) {
+      if (uint8Array[i] !== otherUint8Array[i]) {
         return false;
       }
     }
@@ -134,6 +175,10 @@ export const webByteUtils = {
     return Uint8Array.from(atob(base64), c => c.charCodeAt(0));
   },
 
+  fromUTF8(utf8: string): Uint8Array {
+    return new TextEncoder().encode(utf8);
+  },
+
   toBase64(uint8array: Uint8Array): string {
     return btoa(webByteUtils.toISO88591(uint8array));
   },