bson 6.9.0 → 6.10.1

package/package.json

@@ -14,7 +14,7 @@
     "vendor"
   ],
   "types": "bson.d.ts",
-  "version": "6.9.0",
+  "version": "6.10.1",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -55,7 +55,6 @@
     "sinon": "^18.0.0",
     "sinon-chai": "^3.7.0",
     "source-map-support": "^0.5.21",
-    "standard-version": "^9.5.0",
     "tar": "^7.4.3",
     "ts-node": "^10.9.2",
     "tsd": "^0.31.1",

package/src/binary.ts

@@ -4,6 +4,7 @@ import { BSONError } from './error';
 import { BSON_BINARY_SUBTYPE_UUID_NEW } from './constants';
 import { ByteUtils } from './utils/byte_utils';
 import { BSONValue } from './bson_value';
+import { NumberUtils } from './utils/number_utils';
 
 /** @public */
 export type BinarySequence = Uint8Array | number[];
@@ -58,12 +59,60 @@ export class Binary extends BSONValue {
   static readonly SUBTYPE_COLUMN = 7;
   /** Sensitive BSON type */
   static readonly SUBTYPE_SENSITIVE = 8;
+  /** Vector BSON type */
+  static readonly SUBTYPE_VECTOR = 9;
   /** User BSON type */
   static readonly SUBTYPE_USER_DEFINED = 128;
 
-  buffer!: Uint8Array;
-  sub_type!: number;
-  position!: number;
+  /** datatype of a Binary Vector (subtype: 9) */
+  static readonly VECTOR_TYPE = Object.freeze({
+    Int8: 0x03,
+    Float32: 0x27,
+    PackedBit: 0x10
+  } as const);
+
+  /**
+   * The bytes of the Binary value.
+   *
+   * The format of a Binary value in BSON is defined as:
+   * ```txt
+   * binary	::= int32 subtype (byte*)
+   * ```
+   *
+   * This `buffer` is the "(byte*)" segment.
+   *
+   * Unless the value is subtype 2, then deserialize will read the first 4 bytes as an int32 and set this to the remaining bytes.
+   *
+   * ```txt
+   * binary	::= int32 unsigned_byte(2) int32 (byte*)
+   * ```
+   *
+   * @see https://bsonspec.org/spec.html
+   */
+  public buffer: Uint8Array;
+  /**
+   * The binary subtype.
+   *
+   * Current defined values are:
+   *
+   * - `unsigned_byte(0)` Generic binary subtype
+   * - `unsigned_byte(1)` Function
+   * - `unsigned_byte(2)` Binary (Deprecated)
+   * - `unsigned_byte(3)` UUID (Deprecated)
+   * - `unsigned_byte(4)` UUID
+   * - `unsigned_byte(5)` MD5
+   * - `unsigned_byte(6)` Encrypted BSON value
+   * - `unsigned_byte(7)` Compressed BSON column
+   * - `unsigned_byte(8)` Sensitive
+   * - `unsigned_byte(9)` Vector
+   * - `unsigned_byte(128)` - `unsigned_byte(255)` User defined
+   */
+  public sub_type: number;
+  /**
+   * The Binary's `buffer` can be larger than the Binary's content.
+   * This property is used to determine where the content ends in the buffer.
+   */
+  public position: number;
 
   /**
    * Create a new Binary instance.
@@ -160,16 +209,15 @@ export class Binary extends BSONValue {
   }
 
   /**
-   * Reads **length** bytes starting at **position**.
+   * Returns a view of **length** bytes starting at **position**.
    *
    * @param position - read from the given position in the Binary.
    * @param length - the number of bytes to read.
    */
-  read(position: number, length: number): BinarySequence {
+  read(position: number, length: number): Uint8Array {
     length = length && length > 0 ? length : this.position;
-
-    // Let's return the data based on the type we have
-    return this.buffer.slice(position, position + length);
+    const end = position + length;
+    return this.buffer.subarray(position, end > this.position ? this.position : end);
   }
 
   /** returns a view of the binary value as a Uint8Array */
@@ -200,6 +248,11 @@ export class Binary extends BSONValue {
   /** @internal */
   toExtendedJSON(options?: EJSONOptions): BinaryExtendedLegacy | BinaryExtended {
     options = options || {};
+
+    if (this.sub_type === Binary.SUBTYPE_VECTOR) {
+      validateBinaryVector(this);
+    }
+
     const base64String = ByteUtils.toBase64(this.buffer);
 
     const subType = Number(this.sub_type).toString(16);
@@ -219,7 +272,7 @@ export class Binary extends BSONValue {
 
   toUUID(): UUID {
     if (this.sub_type === Binary.SUBTYPE_UUID) {
-      return new UUID(this.buffer.slice(0, this.position));
+      return new UUID(this.buffer.subarray(0, this.position));
     }
 
     throw new BSONError(
@@ -272,6 +325,209 @@ export class Binary extends BSONValue {
     const subTypeArg = inspect(this.sub_type, options);
     return `Binary.createFromBase64(${base64Arg}, ${subTypeArg})`;
   }
+
+  /**
+   * If this Binary represents a Int8 Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.Int8`),
+   * returns a copy of the bytes in a new Int8Array.
+   *
+   * If the Binary is not a Vector, or the datatype is not Int8, an error is thrown.
+   */
+  public toInt8Array(): Int8Array {
+    if (this.sub_type !== Binary.SUBTYPE_VECTOR) {
+      throw new BSONError('Binary sub_type is not Vector');
+    }
+
+    if (this.buffer[0] !== Binary.VECTOR_TYPE.Int8) {
+      throw new BSONError('Binary datatype field is not Int8');
+    }
+
+    return new Int8Array(
+      this.buffer.buffer.slice(this.buffer.byteOffset + 2, this.buffer.byteOffset + this.position)
+    );
+  }
+
+  /**
+   * If this Binary represents a Float32 Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.Float32`),
+   * returns a copy of the bytes in a new Float32Array.
+   *
+   * If the Binary is not a Vector, or the datatype is not Float32, an error is thrown.
+   */
+  public toFloat32Array(): Float32Array {
+    if (this.sub_type !== Binary.SUBTYPE_VECTOR) {
+      throw new BSONError('Binary sub_type is not Vector');
+    }
+
+    if (this.buffer[0] !== Binary.VECTOR_TYPE.Float32) {
+      throw new BSONError('Binary datatype field is not Float32');
+    }
+
+    const floatBytes = new Uint8Array(
+      this.buffer.buffer.slice(this.buffer.byteOffset + 2, this.buffer.byteOffset + this.position)
+    );
+
+    if (NumberUtils.isBigEndian) ByteUtils.swap32(floatBytes);
+
+    return new Float32Array(floatBytes.buffer);
+  }
+
+  /**
+   * If this Binary represents packed bit Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.PackedBit`),
+   * returns a copy of the bytes that are packed bits.
+   *
+   * Use `toBits` to get the unpacked bits.
+   *
+   * If the Binary is not a Vector, or the datatype is not PackedBit, an error is thrown.
+   */
+  public toPackedBits(): Uint8Array {
+    if (this.sub_type !== Binary.SUBTYPE_VECTOR) {
+      throw new BSONError('Binary sub_type is not Vector');
+    }
+
+    if (this.buffer[0] !== Binary.VECTOR_TYPE.PackedBit) {
+      throw new BSONError('Binary datatype field is not packed bit');
+    }
+
+    return new Uint8Array(
+      this.buffer.buffer.slice(this.buffer.byteOffset + 2, this.buffer.byteOffset + this.position)
+    );
+  }
+
+  /**
+   * If this Binary represents a Packed bit Vector (`binary.buffer[0] === Binary.VECTOR_TYPE.PackedBit`),
+   * returns a copy of the bit unpacked into a new Int8Array.
+   *
+   * Use `toPackedBits` to get the bits still in packed form.
+   *
+   * If the Binary is not a Vector, or the datatype is not PackedBit, an error is thrown.
+   */
+  public toBits(): Int8Array {
+    if (this.sub_type !== Binary.SUBTYPE_VECTOR) {
+      throw new BSONError('Binary sub_type is not Vector');
+    }
+
+    if (this.buffer[0] !== Binary.VECTOR_TYPE.PackedBit) {
+      throw new BSONError('Binary datatype field is not packed bit');
+    }
+
+    const byteCount = this.length() - 2;
+    const bitCount = byteCount * 8 - this.buffer[1];
+    const bits = new Int8Array(bitCount);
+
+    for (let bitOffset = 0; bitOffset < bits.length; bitOffset++) {
+      const byteOffset = (bitOffset / 8) | 0;
+      const byte = this.buffer[byteOffset + 2];
+      const shift = 7 - (bitOffset % 8);
+      const bit = (byte >> shift) & 1;
+      bits[bitOffset] = bit;
+    }
+
+    return bits;
+  }
+
+  /**
+   * Constructs a Binary representing an Int8 Vector.
+   * @param array - The array to store as a view on the Binary class
+   */
+  public static fromInt8Array(array: Int8Array): Binary {
+    const buffer = ByteUtils.allocate(array.byteLength + 2);
+    buffer[0] = Binary.VECTOR_TYPE.Int8;
+    buffer[1] = 0;
+    const intBytes = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+    buffer.set(intBytes, 2);
+    return new this(buffer, this.SUBTYPE_VECTOR);
+  }
+
+  /** Constructs a Binary representing an Float32 Vector. */
+  public static fromFloat32Array(array: Float32Array): Binary {
+    const binaryBytes = ByteUtils.allocate(array.byteLength + 2);
+    binaryBytes[0] = Binary.VECTOR_TYPE.Float32;
+    binaryBytes[1] = 0;
+
+    const floatBytes = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+    binaryBytes.set(floatBytes, 2);
+
+    if (NumberUtils.isBigEndian) ByteUtils.swap32(new Uint8Array(binaryBytes.buffer, 2));
+
+    return new this(binaryBytes, this.SUBTYPE_VECTOR);
+  }
+
+  /**
+   * Constructs a Binary representing a packed bit Vector.
+   *
+   * Use `fromBits` to pack an array of 1s and 0s.
+   */
+  public static fromPackedBits(array: Uint8Array, padding = 0): Binary {
+    const buffer = ByteUtils.allocate(array.byteLength + 2);
+    buffer[0] = Binary.VECTOR_TYPE.PackedBit;
+    buffer[1] = padding;
+    buffer.set(array, 2);
+    return new this(buffer, this.SUBTYPE_VECTOR);
+  }
+
+  /**
+   * Constructs a Binary representing an Packed Bit Vector.
+   * @param array - The array of 1s and 0s to pack into the Binary instance
+   */
+  public static fromBits(bits: ArrayLike<number>): Binary {
+    const byteLength = (bits.length + 7) >>> 3; // ceil(bits.length / 8)
+    const bytes = new Uint8Array(byteLength + 2);
+    bytes[0] = Binary.VECTOR_TYPE.PackedBit;
+
+    const remainder = bits.length % 8;
+    bytes[1] = remainder === 0 ? 0 : 8 - remainder;
+
+    for (let bitOffset = 0; bitOffset < bits.length; bitOffset++) {
+      const byteOffset = bitOffset >>> 3; // floor(bitOffset / 8)
+      const bit = bits[bitOffset];
+
+      if (bit !== 0 && bit !== 1) {
+        throw new BSONError(
+          `Invalid bit value at ${bitOffset}: must be 0 or 1, found ${bits[bitOffset]}`
+        );
+      }
+
+      if (bit === 0) continue;
+
+      const shift = 7 - (bitOffset % 8);
+      bytes[byteOffset + 2] |= bit << shift;
+    }
+
+    return new this(bytes, Binary.SUBTYPE_VECTOR);
+  }
+}
+
+export function validateBinaryVector(vector: Binary): void {
+  if (vector.sub_type !== Binary.SUBTYPE_VECTOR) return;
+
+  const size = vector.position;
+
+  // NOTE: Validation is only applied to **KNOWN** vector types
+  // If a new datatype is introduced, a future version of the library will need to add validation
+  const datatype = vector.buffer[0];
+
+  // NOTE: We do not enable noUncheckedIndexedAccess so TS believes this is always number
+  // a Binary vector may be empty, in which case the padding is undefined
+  // this possible value is tolerable for our validation checks
+  const padding: number | undefined = vector.buffer[1];
+
+  if (
+    (datatype === Binary.VECTOR_TYPE.Float32 || datatype === Binary.VECTOR_TYPE.Int8) &&
+    padding !== 0
+  ) {
+    throw new BSONError('Invalid Vector: padding must be zero for int8 and float32 vectors');
+  }
+
+  if (datatype === Binary.VECTOR_TYPE.PackedBit && padding !== 0 && size === 2) {
+    throw new BSONError(
+      'Invalid Vector: padding must be zero for packed bit vectors that are empty'
+    );
+  }
+
+  if (datatype === Binary.VECTOR_TYPE.PackedBit && padding > 7) {
+    throw new BSONError(
+      `Invalid Vector: padding must be a value between 0 and 7. found: ${padding}`
+    );
+  }
 }
 
 /** @public */

package/src/objectid.ts

@@ -7,6 +7,9 @@ import { NumberUtils } from './utils/number_utils';
 // Unique sequence for the current process (initialized on first use)
 let PROCESS_UNIQUE: Uint8Array | null = null;
 
+/** ObjectId hexString cache @internal */
+const __idCache = new WeakMap(); // TODO(NODE-6549): convert this to #__id private field when target updated to ES2022
+
 /** @public */
 export interface ObjectIdLike {
   id: string | Uint8Array;
@@ -36,8 +39,6 @@ export class ObjectId extends BSONValue {
 
   /** ObjectId Bytes @internal */
   private buffer!: Uint8Array;
-  /** ObjectId hexString cache @internal */
-  private __id?: string;
 
   /**
    * Create ObjectId from a number.
@@ -111,6 +112,10 @@ export class ObjectId extends BSONValue {
     } else if (typeof workingId === 'string') {
       if (ObjectId.validateHexString(workingId)) {
         this.buffer = ByteUtils.fromHex(workingId);
+        // If we are caching the hex string
+        if (ObjectId.cacheHexString) {
+          __idCache.set(this, workingId);
+        }
       } else {
         throw new BSONError(
           'input must be a 24 character hex string, 12 byte Uint8Array, or an integer'
@@ -119,10 +124,6 @@ export class ObjectId extends BSONValue {
     } else {
       throw new BSONError('Argument passed in does not match the accepted types');
     }
-    // If we are caching the hex string
-    if (ObjectId.cacheHexString) {
-      this.__id = ByteUtils.toHex(this.id);
-    }
   }
 
   /**
@@ -136,7 +137,7 @@ export class ObjectId extends BSONValue {
   set id(value: Uint8Array) {
     this.buffer = value;
     if (ObjectId.cacheHexString) {
-      this.__id = ByteUtils.toHex(value);
+      __idCache.set(this, ByteUtils.toHex(value));
     }
   }
 
@@ -165,14 +166,15 @@ export class ObjectId extends BSONValue {
 
   /** Returns the ObjectId id as a 24 lowercase character hex string representation */
   toHexString(): string {
-    if (ObjectId.cacheHexString && this.__id) {
-      return this.__id;
+    if (ObjectId.cacheHexString) {
+      const __id = __idCache.get(this);
+      if (__id) return __id;
     }
 
     const hexString = ByteUtils.toHex(this.id);
 
-    if (ObjectId.cacheHexString && !this.__id) {
-      this.__id = hexString;
+    if (ObjectId.cacheHexString) {
+      __idCache.set(this, hexString);
     }
 
     return hexString;
@@ -370,6 +372,11 @@ export class ObjectId extends BSONValue {
     return new ObjectId(doc.$oid);
   }
 
+  /** @internal */
+  private isCached(): boolean {
+    return ObjectId.cacheHexString && __idCache.has(this);
+  }
+
   /**
    * Converts to a string representation of this Id.
    *

package/src/parser/deserializer.ts

@@ -296,7 +296,7 @@ function deserializeObject(
 
       // We have a raw value
       if (raw) {
-        value = buffer.slice(index, index + objectSize);
+        value = buffer.subarray(index, index + objectSize);
       } else {
         let objectOptions = options;
         if (!globalUTFValidation) {
@@ -374,52 +374,24 @@ function deserializeObject(
       if (binarySize > buffer.byteLength)
         throw new BSONError('Binary type size larger than document size');
 
-      // Decode as raw Buffer object if options specifies it
-      if (buffer['slice'] != null) {
-        // If we have subtype 2 skip the 4 bytes for the size
-        if (subType === Binary.SUBTYPE_BYTE_ARRAY) {
-          binarySize = NumberUtils.getInt32LE(buffer, index);
-          index += 4;
-          if (binarySize < 0)
-            throw new BSONError('Negative binary type element size found for subtype 0x02');
-          if (binarySize > totalBinarySize - 4)
-            throw new BSONError('Binary type with subtype 0x02 contains too long binary size');
-          if (binarySize < totalBinarySize - 4)
-            throw new BSONError('Binary type with subtype 0x02 contains too short binary size');
-        }
+      // If we have subtype 2 skip the 4 bytes for the size
+      if (subType === Binary.SUBTYPE_BYTE_ARRAY) {
+        binarySize = NumberUtils.getInt32LE(buffer, index);
+        index += 4;
+        if (binarySize < 0)
+          throw new BSONError('Negative binary type element size found for subtype 0x02');
+        if (binarySize > totalBinarySize - 4)
+          throw new BSONError('Binary type with subtype 0x02 contains too long binary size');
+        if (binarySize < totalBinarySize - 4)
+          throw new BSONError('Binary type with subtype 0x02 contains too short binary size');
+      }
 
-        if (promoteBuffers && promoteValues) {
-          value = ByteUtils.toLocalBufferType(buffer.slice(index, index + binarySize));
-        } else {
-          value = new Binary(buffer.slice(index, index + binarySize), subType);
-          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
-            value = value.toUUID();
-          }
-        }
+      if (promoteBuffers && promoteValues) {
+        value = ByteUtils.toLocalBufferType(buffer.subarray(index, index + binarySize));
       } else {
-        // If we have subtype 2 skip the 4 bytes for the size
-        if (subType === Binary.SUBTYPE_BYTE_ARRAY) {
-          binarySize = NumberUtils.getInt32LE(buffer, index);
-          index += 4;
-          if (binarySize < 0)
-            throw new BSONError('Negative binary type element size found for subtype 0x02');
-          if (binarySize > totalBinarySize - 4)
-            throw new BSONError('Binary type with subtype 0x02 contains too long binary size');
-          if (binarySize < totalBinarySize - 4)
-            throw new BSONError('Binary type with subtype 0x02 contains too short binary size');
-        }
-
-        if (promoteBuffers && promoteValues) {
-          value = ByteUtils.allocateUnsafe(binarySize);
-          // Copy the data
-          for (i = 0; i < binarySize; i++) {
-            value[i] = buffer[index + i];
-          }
-        } else {
-          value = new Binary(buffer.slice(index, index + binarySize), subType);
-          if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
-            value = value.toUUID();
-          }
+        value = new Binary(buffer.subarray(index, index + binarySize), subType);
+        if (subType === constants.BSON_BINARY_SUBTYPE_UUID_NEW && UUID.isValid(value)) {
+          value = value.toUUID();
         }
       }
 

package/src/parser/serializer.ts

@@ -1,4 +1,4 @@
-import { Binary } from '../binary';
+import { Binary, validateBinaryVector } from '../binary';
 import type { BSONSymbol, DBRef, Document, MaxKey } from '../bson';
 import type { Code } from '../code';
 import * as constants from '../constants';
@@ -495,6 +495,10 @@ function serializeBinary(buffer: Uint8Array, key: string, value: Binary, index:
     index += NumberUtils.setInt32LE(buffer, index, size);
   }
 
+  if (value.sub_type === Binary.SUBTYPE_VECTOR) {
+    validateBinaryVector(value);
+  }
+
   if (size <= 16) {
     for (let i = 0; i < size; i++) buffer[index + i] = data[i];
   } else {

package/src/parser/utils.ts

@@ -1,65 +1,44 @@
-const map = new WeakMap<object, string>();
+const TypedArrayPrototypeGetSymbolToStringTag = (() => {
+  // Type check system lovingly referenced from:
+  // https://github.com/nodejs/node/blob/7450332339ed40481f470df2a3014e2ec355d8d8/lib/internal/util/types.js#L13-L15
+  // eslint-disable-next-line @typescript-eslint/unbound-method -- the intention is to call this method with a bound value
+  const g = Object.getOwnPropertyDescriptor(
+    Object.getPrototypeOf(Uint8Array.prototype),
+    Symbol.toStringTag
+  )!.get!;
 
-const TYPES = {
-  ArrayBuffer: '[object ArrayBuffer]',
-  SharedArrayBuffer: '[object SharedArrayBuffer]',
-  Uint8Array: '[object Uint8Array]',
-  BigInt64Array: '[object BigInt64Array]',
-  BigUint64Array: '[object BigUint64Array]',
-  RegExp: '[object RegExp]',
-  Map: '[object Map]',
-  Date: '[object Date]'
-};
-
-/**
- * Retrieves the prototype.toString() of a value.
- * If the value is an object, it will cache the result in a WeakMap for future use.
- */
-function getPrototypeString(value: unknown): string {
-  let str = map.get(value as object);
-
-  if (!str) {
-    str = Object.prototype.toString.call(value);
-    if (value !== null && typeof value === 'object') {
-      map.set(value, str);
-    }
-  }
-  return str;
-}
-
-export function isAnyArrayBuffer(value: unknown): value is ArrayBuffer {
-  const type = getPrototypeString(value);
-  return type === TYPES.ArrayBuffer || type === TYPES.SharedArrayBuffer;
-}
+  return (value: unknown) => g.call(value);
+})();
 
 export function isUint8Array(value: unknown): value is Uint8Array {
-  const type = getPrototypeString(value);
-  return type === TYPES.Uint8Array;
+  return TypedArrayPrototypeGetSymbolToStringTag(value) === 'Uint8Array';
 }
 
-export function isBigInt64Array(value: unknown): value is BigInt64Array {
-  const type = getPrototypeString(value);
-  return type === TYPES.BigInt64Array;
-}
-
-export function isBigUInt64Array(value: unknown): value is BigUint64Array {
-  const type = getPrototypeString(value);
-  return type === TYPES.BigUint64Array;
+export function isAnyArrayBuffer(value: unknown): value is ArrayBuffer {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    Symbol.toStringTag in value &&
+    (value[Symbol.toStringTag] === 'ArrayBuffer' ||
+      value[Symbol.toStringTag] === 'SharedArrayBuffer')
+  );
 }
 
-export function isRegExp(d: unknown): d is RegExp {
-  const type = getPrototypeString(d);
-  return type === TYPES.RegExp;
+export function isRegExp(regexp: unknown): regexp is RegExp {
+  return regexp instanceof RegExp || Object.prototype.toString.call(regexp) === '[object RegExp]';
 }
 
-export function isMap(d: unknown): d is Map<unknown, unknown> {
-  const type = getPrototypeString(d);
-  return type === TYPES.Map;
+export function isMap(value: unknown): value is Map<unknown, unknown> {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    Symbol.toStringTag in value &&
+    value[Symbol.toStringTag] === 'Map'
+  );
 }
 
-export function isDate(d: unknown): d is Date {
-  const type = getPrototypeString(d);
-  return type === TYPES.Date;
+export function isDate(date: unknown): date is Date {
+  return date instanceof Date || Object.prototype.toString.call(date) === '[object Date]';
 }
 
 export type InspectFn = (x: unknown, options?: unknown) => string;

package/src/utils/byte_utils.ts

@@ -39,6 +39,8 @@ export type ByteUtils = {
   encodeUTF8Into: (destination: Uint8Array, source: string, byteOffset: number) => number;
   /** Generate a Uint8Array filled with random bytes with byteLength */
   randomBytes: (byteLength: number) => Uint8Array;
+  /** Interprets `buffer` as an array of 32-bit values and swaps the byte order in-place. */
+  swap32: (buffer: Uint8Array) => Uint8Array;
 };
 
 declare const Buffer: { new (): unknown; prototype?: { _isBuffer?: boolean } } | undefined;

package/src/utils/node_byte_utils.ts

@@ -9,6 +9,7 @@ type NodeJsBuffer = ArrayBufferView &
     copy(target: Uint8Array, targetStart: number, sourceStart: number, sourceEnd: number): number;
     toString: (this: Uint8Array, encoding: NodeJsEncoding, start?: number, end?: number) => string;
     equals: (this: Uint8Array, other: Uint8Array) => boolean;
+    swap32: (this: NodeJsBuffer) => NodeJsBuffer;
   };
 type NodeJsBufferConstructor = Omit<Uint8ArrayConstructor, 'from'> & {
   alloc: (size: number) => NodeJsBuffer;
@@ -83,7 +84,7 @@ export const nodeJsByteUtils = {
       return Buffer.from(potentialBuffer);
     }
 
-    throw new BSONError(`Cannot create Buffer from ${String(potentialBuffer)}`);
+    throw new BSONError(`Cannot create Buffer from the passed potentialBuffer.`);
   },
 
   allocate(size: number): NodeJsBuffer {
@@ -159,5 +160,9 @@ export const nodeJsByteUtils = {
     return nodeJsByteUtils.toLocalBufferType(buffer).write(source, byteOffset, undefined, 'utf8');
   },
 
-  randomBytes: nodejsRandomBytes
+  randomBytes: nodejsRandomBytes,
+
+  swap32(buffer: Uint8Array): NodeJsBuffer {
+    return nodeJsByteUtils.toLocalBufferType(buffer).swap32();
+  }
 };

package/src/utils/number_utils.ts

@@ -13,6 +13,8 @@ const isBigEndian = FLOAT_BYTES[7] === 0;
  * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
  */
 export type NumberUtils = {
+  /** Is true if the current system is big endian. */
+  isBigEndian: boolean;
   /**
    * Parses a signed int32 at offset. Throws a `RangeError` if value is negative.
    */
@@ -35,6 +37,8 @@ export type NumberUtils = {
  * @public
  */
 export const NumberUtils: NumberUtils = {
+  isBigEndian,
+
   getNonnegativeInt32LE(source: Uint8Array, offset: number): number {
     if (source[offset + 3] > 127) {
       throw new RangeError(`Size cannot be negative at offset: ${offset}`);