bson 5.0.0-alpha.1 → 5.0.0-alpha.2

package/package.json

@@ -13,7 +13,7 @@
     "etc/prepare.js"
   ],
   "types": "bson.d.ts",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.2",
   "author": {
     "name": "The MongoDB NodeJS Team",
     "email": "dbx-node@mongodb.com"
@@ -75,11 +75,11 @@
   },
   "main": "./lib/bson.cjs",
   "module": "./lib/bson.mjs",
-  "browser": "./lib/bson.mjs",
   "exports": {
-    "browser": "./lib/bson.mjs",
     "import": "./lib/bson.mjs",
-    "require": "./lib/bson.cjs"
+    "require": "./lib/bson.cjs",
+    "react-native": "./lib/bson.cjs",
+    "browser": "./lib/bson.mjs"
   },
   "engines": {
     "node": ">=14.20.1"

package/src/binary.ts

@@ -1,7 +1,7 @@
 import { bufferToUuidHexString, uuidHexStringToBuffer, uuidValidateString } from './uuid_utils';
 import { isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
-import { BSONError, BSONTypeError } from './error';
+import { BSONError } from './error';
 import { BSON_BINARY_SUBTYPE_UUID_NEW, BSON_MAJOR_VERSION } from './constants';
 import { ByteUtils } from './utils/byte_utils';
 
@@ -86,7 +86,7 @@ export class Binary {
       !(buffer instanceof ArrayBuffer) &&
       !Array.isArray(buffer)
     ) {
-      throw new BSONTypeError(
+      throw new BSONError(
         'Binary can only be constructed from string, Buffer, TypedArray, or Array<number>'
       );
     }
@@ -121,9 +121,9 @@ export class Binary {
   put(byteValue: string | number | Uint8Array | number[]): void {
     // If it's a string and a has more than one character throw an error
     if (typeof byteValue === 'string' && byteValue.length !== 1) {
-      throw new BSONTypeError('only accepts single character String');
+      throw new BSONError('only accepts single character String');
     } else if (typeof byteValue !== 'number' && byteValue.length !== 1)
-      throw new BSONTypeError('only accepts single character Uint8Array or Array');
+      throw new BSONError('only accepts single character Uint8Array or Array');
 
     // Decode the byte value once
     let decodedByte: number;
@@ -136,7 +136,7 @@ export class Binary {
     }
 
     if (decodedByte < 0 || decodedByte > 255) {
-      throw new BSONTypeError('only accepts number in a valid unsigned byte range 0-255');
+      throw new BSONError('only accepts number in a valid unsigned byte range 0-255');
     }
 
     if (this.buffer.byteLength > this.position) {
@@ -283,7 +283,7 @@ export class Binary {
       data = uuidHexStringToBuffer(doc.$uuid);
     }
     if (!data) {
-      throw new BSONTypeError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
+      throw new BSONError(`Unexpected Binary Extended JSON format ${JSON.stringify(doc)}`);
     }
     return type === BSON_BINARY_SUBTYPE_UUID_NEW ? new UUID(data) : new Binary(data, type);
   }
@@ -337,7 +337,7 @@ export class UUID extends Binary {
     } else if (typeof input === 'string') {
       bytes = uuidHexStringToBuffer(input);
     } else {
-      throw new BSONTypeError(
+      throw new BSONError(
         'Argument passed in UUID constructor must be a UUID, a 16 byte Buffer or a 32/36 character hex string (dashes excluded/included, format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).'
       );
     }

package/src/bson.ts

@@ -49,7 +49,7 @@ export {
   BSONRegExp,
   Decimal128
 };
-export { BSONError, BSONTypeError } from './error';
+export { BSONError } from './error';
 export { BSONType } from './constants';
 export { EJSON } from './extended_json';
 

package/src/decimal128.ts

@@ -1,5 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
-import { BSONTypeError } from './error';
+import { BSONError } from './error';
 import { Long } from './long';
 import { isUint8Array } from './parser/utils';
 import { ByteUtils } from './utils/byte_utils';
@@ -114,7 +114,7 @@ function lessThan(left: Long, right: Long): boolean {
 }
 
 function invalidErr(string: string, message: string) {
-  throw new BSONTypeError(`"${string}" is not a valid Decimal128 string - ${message}`);
+  throw new BSONError(`"${string}" is not a valid Decimal128 string - ${message}`);
 }
 
 /** @public */
@@ -147,11 +147,11 @@ export class Decimal128 {
       this.bytes = Decimal128.fromString(bytes).bytes;
     } else if (isUint8Array(bytes)) {
       if (bytes.byteLength !== 16) {
-        throw new BSONTypeError('Decimal128 must take a Buffer of 16 bytes');
+        throw new BSONError('Decimal128 must take a Buffer of 16 bytes');
       }
       this.bytes = bytes;
     } else {
-      throw new BSONTypeError('Decimal128 must take a Buffer or string');
+      throw new BSONError('Decimal128 must take a Buffer or string');
     }
   }
 
@@ -206,7 +206,7 @@ export class Decimal128 {
     // TODO: implementing a custom parsing for this, or refactoring the regex would yield
     //       further gains.
     if (representation.length >= 7000) {
-      throw new BSONTypeError('' + representation + ' not a valid Decimal128 string');
+      throw new BSONError('' + representation + ' not a valid Decimal128 string');
     }
 
     // Results
@@ -216,7 +216,7 @@ export class Decimal128 {
 
     // Validate the string
     if ((!stringMatch && !infMatch && !nanMatch) || representation.length === 0) {
-      throw new BSONTypeError('' + representation + ' not a valid Decimal128 string');
+      throw new BSONError('' + representation + ' not a valid Decimal128 string');
     }
 
     if (stringMatch) {
@@ -288,7 +288,7 @@ export class Decimal128 {
     }
 
     if (sawRadix && !nDigitsRead)
-      throw new BSONTypeError('' + representation + ' not a valid Decimal128 string');
+      throw new BSONError('' + representation + ' not a valid Decimal128 string');
 
     // Read exponent if exists
     if (representation[index] === 'e' || representation[index] === 'E') {

package/src/double.ts

@@ -57,23 +57,15 @@ export class Double {
       return this.value;
     }
 
-    // NOTE: JavaScript has +0 and -0, apparently to model limit calculations. If a user
-    // explicitly provided `-0` then we need to ensure the sign makes it into the output
     if (Object.is(Math.sign(this.value), -0)) {
-      return { $numberDouble: `-${this.value.toFixed(1)}` };
+      // NOTE: JavaScript has +0 and -0, apparently to model limit calculations. If a user
+      // explicitly provided `-0` then we need to ensure the sign makes it into the output
+      return { $numberDouble: '-0.0' };
     }
 
-    let $numberDouble: string;
-    if (Number.isInteger(this.value)) {
-      $numberDouble = this.value.toFixed(1);
-      if ($numberDouble.length >= 13) {
-        $numberDouble = this.value.toExponential(13).toUpperCase();
-      }
-    } else {
-      $numberDouble = this.value.toString();
-    }
-
-    return { $numberDouble };
+    return {
+      $numberDouble: Number.isInteger(this.value) ? this.value.toFixed(1) : this.value.toString()
+    };
   }
 
   /** @internal */

package/src/error.ts

@@ -1,21 +1,45 @@
-/** @public */
+/**
+ * @public
+ * `BSONError` objects are thrown when runtime errors occur.
+ */
 export class BSONError extends Error {
-  constructor(message: string) {
-    super(message);
+  /**
+   * @internal
+   * The underlying algorithm for isBSONError may change to improve how strict it is
+   * about determining if an input is a BSONError. But it must remain backwards compatible
+   * with previous minors & patches of the current major version.
+   */
+  protected get bsonError(): true {
+    return true;
   }
 
-  get name(): string {
+  override get name(): string {
     return 'BSONError';
   }
-}
 
-/** @public */
-export class BSONTypeError extends TypeError {
   constructor(message: string) {
     super(message);
   }
 
-  get name(): string {
-    return 'BSONTypeError';
+  /**
+   * @public
+   *
+   * All errors thrown from the BSON library inherit from `BSONError`.
+   * This method can assist with determining if an error originates from the BSON library
+   * even if it does not pass an `instanceof` check against this class' constructor.
+   *
+   * @param value - any javascript value that needs type checking
+   */
+  public static isBSONError(value: unknown): value is BSONError {
+    return (
+      value != null &&
+      typeof value === 'object' &&
+      'bsonError' in value &&
+      value.bsonError === true &&
+      // Do not access the following properties, just check existence
+      'name' in value &&
+      'message' in value &&
+      'stack' in value
+    );
   }
 }

package/src/extended_json.ts

@@ -1,11 +1,17 @@
 import { Binary } from './binary';
 import type { Document } from './bson';
 import { Code } from './code';
-import { BSON_INT32_MAX, BSON_INT32_MIN, BSON_INT64_MAX, BSON_INT64_MIN } from './constants';
+import {
+  BSON_INT32_MAX,
+  BSON_INT32_MIN,
+  BSON_INT64_MAX,
+  BSON_INT64_MIN,
+  BSON_MAJOR_VERSION
+} from './constants';
 import { DBRef, isDBRefLike } from './db_ref';
 import { Decimal128 } from './decimal128';
 import { Double } from './double';
-import { BSONError, BSONTypeError } from './error';
+import { BSONError } from './error';
 import { Int32 } from './int_32';
 import { Long } from './long';
 import { MaxKey } from './max_key';
@@ -192,7 +198,7 @@ function serializeValue(value: any, options: EJSONSerializeOptions): any {
         circularPart.length + (alreadySeen.length + current.length) / 2 - 1
       );
 
-      throw new BSONTypeError(
+      throw new BSONError(
         'Converting circular structure to EJSON:\n' +
           `    ${leadingPart}${alreadySeen}${circularPart}${current}\n` +
           `    ${leadingSpace}\\${dashes}/`
@@ -310,7 +316,7 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
     doc != null &&
     typeof doc === 'object' &&
     typeof doc._bsontype === 'string' &&
-    doc[Symbol.for('@@mdb.bson.version')] == null
+    doc[Symbol.for('@@mdb.bson.version')] !== BSON_MAJOR_VERSION
   ) {
     throw new BSONError('Unsupported BSON version, bson types must be from bson 5.0 or later');
   } else if (isBSONType(doc)) {
@@ -324,7 +330,7 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
       // Copy the object into this library's version of that type.
       const mapper = BSON_TYPE_MAPPINGS[doc._bsontype];
       if (!mapper) {
-        throw new BSONTypeError('Unrecognized or invalid _bsontype: ' + doc._bsontype);
+        throw new BSONError('Unrecognized or invalid _bsontype: ' + doc._bsontype);
       }
       outDoc = mapper(outDoc);
     }

package/src/long.ts

@@ -1,4 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
+import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
 import type { Timestamp } from './timestamp';
 
@@ -250,7 +251,7 @@ export class Long {
    * @returns The corresponding Long value
    */
   static fromString(str: string, unsigned?: boolean, radix?: number): Long {
-    if (str.length === 0) throw Error('empty string');
+    if (str.length === 0) throw new BSONError('empty string');
     if (str === 'NaN' || str === 'Infinity' || str === '+Infinity' || str === '-Infinity')
       return Long.ZERO;
     if (typeof unsigned === 'number') {
@@ -260,10 +261,10 @@ export class Long {
       unsigned = !!unsigned;
     }
     radix = radix || 10;
-    if (radix < 2 || 36 < radix) throw RangeError('radix');
+    if (radix < 2 || 36 < radix) throw new BSONError('radix');
 
     let p;
-    if ((p = str.indexOf('-')) > 0) throw Error('interior hyphen');
+    if ((p = str.indexOf('-')) > 0) throw new BSONError('interior hyphen');
     else if (p === 0) {
       return Long.fromString(str.substring(1), unsigned, radix).neg();
     }
@@ -431,7 +432,7 @@ export class Long {
    */
   divide(divisor: string | number | Long | Timestamp): Long {
     if (!Long.isLong(divisor)) divisor = Long.fromValue(divisor);
-    if (divisor.isZero()) throw Error('division by zero');
+    if (divisor.isZero()) throw new BSONError('division by zero');
 
     // use wasm support if present
     if (wasm) {
@@ -959,7 +960,7 @@ export class Long {
    */
   toString(radix?: number): string {
     radix = radix || 10;
-    if (radix < 2 || 36 < radix) throw RangeError('radix');
+    if (radix < 2 || 36 < radix) throw new BSONError('radix');
     if (this.isZero()) return '0';
     if (this.isNegative()) {
       // Unsigned Longs are never negative

package/src/objectid.ts

@@ -1,5 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
-import { BSONTypeError } from './error';
+import { BSONError } from './error';
 import { isUint8Array } from './parser/utils';
 import { BSONDataView, ByteUtils } from './utils/byte_utils';
 
@@ -57,9 +57,7 @@ export class ObjectId {
     let workingId;
     if (typeof inputId === 'object' && inputId && 'id' in inputId) {
       if (typeof inputId.id !== 'string' && !ArrayBuffer.isView(inputId.id)) {
-        throw new BSONTypeError(
-          'Argument passed in must have an id that is of type string or Buffer'
-        );
+        throw new BSONError('Argument passed in must have an id that is of type string or Buffer');
       }
       if ('toHexString' in inputId && typeof inputId.toHexString === 'function') {
         workingId = ByteUtils.fromHex(inputId.toHexString());
@@ -85,17 +83,17 @@ export class ObjectId {
         if (bytes.byteLength === 12) {
           this[kId] = bytes;
         } else {
-          throw new BSONTypeError('Argument passed in must be a string of 12 bytes');
+          throw new BSONError('Argument passed in must be a string of 12 bytes');
         }
       } else if (workingId.length === 24 && checkForHexRegExp.test(workingId)) {
         this[kId] = ByteUtils.fromHex(workingId);
       } else {
-        throw new BSONTypeError(
+        throw new BSONError(
           'Argument passed in must be a string of 12 bytes or a string of 24 hex characters or an integer'
         );
       }
     } else {
-      throw new BSONTypeError('Argument passed in does not match the accepted types');
+      throw new BSONError('Argument passed in does not match the accepted types');
     }
     // If we are caching the hex string
     if (ObjectId.cacheHexString) {
@@ -271,7 +269,7 @@ export class ObjectId {
   static createFromHexString(hexString: string): ObjectId {
     // Throw an error if it's not a valid setup
     if (typeof hexString === 'undefined' || (hexString != null && hexString.length !== 24)) {
-      throw new BSONTypeError(
+      throw new BSONError(
         'Argument passed in must be a single String of 12 bytes or a string of 24 hex characters'
       );
     }

package/src/parser/calculate_size.ts

@@ -1,5 +1,6 @@
 import { Binary } from '../binary';
 import type { Document } from '../bson';
+import { BSONError } from '../error';
 import * as constants from '../constants';
 import { ByteUtils } from '../utils/byte_utils';
 import { isAnyArrayBuffer, isDate, isRegExp } from './utils';
@@ -77,7 +78,17 @@ function calculateElement(
     case 'boolean':
       return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (1 + 1);
     case 'object':
-      if (value == null || value['_bsontype'] === 'MinKey' || value['_bsontype'] === 'MaxKey') {
+      if (
+        value != null &&
+        typeof value._bsontype === 'string' &&
+        value[Symbol.for('@@mdb.bson.version')] !== constants.BSON_MAJOR_VERSION
+      ) {
+        throw new BSONError('Unsupported BSON version, bson types must be from bson 5.0 or later');
+      } else if (
+        value == null ||
+        value['_bsontype'] === 'MinKey' ||
+        value['_bsontype'] === 'MaxKey'
+      ) {
         return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + 1;
       } else if (value['_bsontype'] === 'ObjectId') {
         return (name != null ? ByteUtils.utf8ByteLength(name) + 1 : 0) + (12 + 1);

package/src/parser/deserializer.ts

@@ -14,12 +14,14 @@ import { ObjectId } from '../objectid';
 import { BSONRegExp } from '../regexp';
 import { BSONSymbol } from '../symbol';
 import { Timestamp } from '../timestamp';
-import { ByteUtils } from '../utils/byte_utils';
+import { BSONDataView, ByteUtils } from '../utils/byte_utils';
 import { validateUtf8 } from '../validate_utf8';
 
 /** @public */
 export interface DeserializeOptions {
-  /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits */
+  /** when deserializing a Long will return as a BigInt. */
+  useBigInt64?: boolean;
+  /** when deserializing a Long will fit it into a Number if it's smaller than 53 bits. */
   promoteLongs?: boolean;
   /** when deserializing a Binary will return it as a node.js Buffer instance. */
   promoteBuffers?: boolean;
@@ -29,7 +31,7 @@ export interface DeserializeOptions {
   fieldsAsRaw?: Document;
   /** return BSON regular expressions as BSONRegExp instances. */
   bsonRegExp?: boolean;
-  /** allows the buffer to be larger than the parsed BSON object */
+  /** allows the buffer to be larger than the parsed BSON object. */
   allowObjectSmallerThanBufferSize?: boolean;
   /** Offset into buffer to begin reading document from */
   index?: number;
@@ -96,7 +98,7 @@ export function internalDeserialize(
     );
   }
 
-  // Start deserializtion
+  // Start deserialization
   return deserializeObject(buffer, index, options, isArray);
 }
 
@@ -117,9 +119,18 @@ function deserializeObject(
   const bsonRegExp = typeof options['bsonRegExp'] === 'boolean' ? options['bsonRegExp'] : false;
 
   // Controls the promotion of values vs wrapper classes
-  const promoteBuffers = options['promoteBuffers'] == null ? false : options['promoteBuffers'];
-  const promoteLongs = options['promoteLongs'] == null ? true : options['promoteLongs'];
-  const promoteValues = options['promoteValues'] == null ? true : options['promoteValues'];
+  const promoteBuffers = options.promoteBuffers ?? false;
+  const promoteLongs = options.promoteLongs ?? true;
+  const promoteValues = options.promoteValues ?? true;
+  const useBigInt64 = options.useBigInt64 ?? false;
+
+  if (useBigInt64 && !promoteValues) {
+    throw new BSONError('Must either request bigint or Long for int64 deserialization');
+  }
+
+  if (useBigInt64 && !promoteLongs) {
+    throw new BSONError('Must either request bigint or Long for int64 deserialization');
+  }
 
   // Ensures default validation option if none given
   const validation = options.validation == null ? { utf8: true } : options.validation;
@@ -323,6 +334,8 @@ function deserializeObject(
       value = null;
     } else if (elementType === constants.BSON_DATA_LONG) {
       // Unpack the low and high bits
+      const dataview = BSONDataView.fromUint8Array(buffer.subarray(index, index + 8));
+
       const lowBits =
         buffer[index++] |
         (buffer[index++] << 8) |
@@ -334,8 +347,10 @@ function deserializeObject(
         (buffer[index++] << 16) |
         (buffer[index++] << 24);
       const long = new Long(lowBits, highBits);
-      // Promote the long if possible
-      if (promoteLongs && promoteValues === true) {
+      if (useBigInt64) {
+        value = dataview.getBigInt64(0, true);
+      } else if (promoteLongs && promoteValues === true) {
+        // Promote the long if possible
         value =
           long.lessThanOrEqual(JS_INT_MAX_LONG) && long.greaterThanOrEqual(JS_INT_MIN_LONG)
             ? long.toNumber()