bson 5.0.0-alpha.1 → 5.0.0-alpha.3

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.3",
   "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,9 +1,10 @@
 import { bufferToUuidHexString, uuidHexStringToBuffer, uuidValidateString } from './uuid_utils';
 import { isUint8Array } from './parser/utils';
 import type { EJSONOptions } from './extended_json';
-import { BSONError, BSONTypeError } from './error';
-import { BSON_BINARY_SUBTYPE_UUID_NEW, BSON_MAJOR_VERSION } from './constants';
+import { BSONError } from './error';
+import { BSON_BINARY_SUBTYPE_UUID_NEW } from './constants';
 import { ByteUtils } from './utils/byte_utils';
+import { BSONValue } from './bson_value';
 
 /** @public */
 export type BinarySequence = Uint8Array | number[];
@@ -27,14 +28,10 @@ export interface BinaryExtended {
  * @public
  * @category BSONType
  */
-export class Binary {
+export class Binary extends BSONValue {
   get _bsontype(): 'Binary' {
     return 'Binary';
   }
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
 
   /**
    * Binary default subtype
@@ -79,6 +76,7 @@ export class Binary {
    * @param subType - the option binary type.
    */
   constructor(buffer?: string | BinarySequence, subType?: number) {
+    super();
     if (
       !(buffer == null) &&
       !(typeof buffer === 'string') &&
@@ -86,7 +84,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 +119,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 +134,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 +281,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);
   }
@@ -309,11 +307,6 @@ const UUID_BYTE_LENGTH = 16;
  * @public
  */
 export class UUID extends Binary {
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
-
   static cacheHexString: boolean;
 
   /** UUID hexString cache @internal */
@@ -337,7 +330,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,8 @@ export {
   BSONRegExp,
   Decimal128
 };
-export { BSONError, BSONTypeError } from './error';
+export { BSONValue } from './bson_value';
+export { BSONError, BSONVersionError } from './error';
 export { BSONType } from './constants';
 export { EJSON } from './extended_json';
 

package/src/bson_value.ts

@@ -0,0 +1,18 @@
+import { BSON_MAJOR_VERSION } from './constants';
+
+/** @public */
+export abstract class BSONValue {
+  /** @public */
+  public abstract get _bsontype(): string;
+
+  /** @internal */
+  get [Symbol.for('@@mdb.bson.version')](): typeof BSON_MAJOR_VERSION {
+    return BSON_MAJOR_VERSION;
+  }
+
+  /** @public */
+  public abstract inspect(): string;
+
+  /** @internal */
+  abstract toExtendedJSON(): unknown;
+}

package/src/code.ts

@@ -1,5 +1,5 @@
 import type { Document } from './bson';
-import { BSON_MAJOR_VERSION } from './constants';
+import { BSONValue } from './bson_value';
 
 /** @public */
 export interface CodeExtended {
@@ -12,14 +12,10 @@ export interface CodeExtended {
  * @public
  * @category BSONType
  */
-export class Code {
+export class Code extends BSONValue {
   get _bsontype(): 'Code' {
     return 'Code';
   }
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
 
   code: string;
 
@@ -32,6 +28,7 @@ export class Code {
    * @param scope - an optional scope for the function.
    */
   constructor(code: string | Function, scope?: Document | null) {
+    super();
     this.code = code.toString();
     this.scope = scope ?? null;
   }

package/src/constants.ts

@@ -1,7 +1,5 @@
 /** @internal */
-export type BSON_MAJOR_VERSION = 5;
-/** @internal */
-export const BSON_MAJOR_VERSION: BSON_MAJOR_VERSION = 5;
+export const BSON_MAJOR_VERSION = 5 as const;
 
 /** @internal */
 export const BSON_INT32_MAX = 0x7fffffff;

package/src/db_ref.ts

@@ -1,5 +1,5 @@
 import type { Document } from './bson';
-import { BSON_MAJOR_VERSION } from './constants';
+import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 import type { ObjectId } from './objectid';
 
@@ -29,14 +29,10 @@ export function isDBRefLike(value: unknown): value is DBRefLike {
  * @public
  * @category BSONType
  */
-export class DBRef {
+export class DBRef extends BSONValue {
   get _bsontype(): 'DBRef' {
     return 'DBRef';
   }
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
 
   collection!: string;
   oid!: ObjectId;
@@ -49,6 +45,7 @@ export class DBRef {
    * @param db - optional db name, if omitted the reference is local to the current db.
    */
   constructor(collection: string, oid: ObjectId, db?: string, fields?: Document) {
+    super();
     // check if namespace has been provided
     const parts = collection.split('.');
     if (parts.length === 2) {

package/src/decimal128.ts

@@ -1,5 +1,5 @@
-import { BSON_MAJOR_VERSION } from './constants';
-import { BSONTypeError } from './error';
+import { BSONValue } from './bson_value';
+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 */
@@ -127,14 +127,10 @@ export interface Decimal128Extended {
  * @public
  * @category BSONType
  */
-export class Decimal128 {
+export class Decimal128 extends BSONValue {
   get _bsontype(): 'Decimal128' {
     return 'Decimal128';
   }
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
 
   readonly bytes!: Uint8Array;
 
@@ -143,15 +139,16 @@ export class Decimal128 {
    *                or a string representation as returned by .toString()
    */
   constructor(bytes: Uint8Array | string) {
+    super();
     if (typeof bytes === 'string') {
       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 +203,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 +213,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 +285,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

@@ -1,4 +1,4 @@
-import { BSON_MAJOR_VERSION } from './constants';
+import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 
 /** @public */
@@ -11,14 +11,10 @@ export interface DoubleExtended {
  * @public
  * @category BSONType
  */
-export class Double {
+export class Double extends BSONValue {
   get _bsontype(): 'Double' {
     return 'Double';
   }
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
 
   value!: number;
   /**
@@ -27,6 +23,7 @@ export class Double {
    * @param value - the number we want to represent as a double.
    */
   constructor(value: number) {
+    super();
     if ((value as unknown) instanceof Number) {
       value = value.valueOf();
     }
@@ -57,23 +54,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)}` };
-    }
-
-    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();
+      // 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' };
     }
 
-    return { $numberDouble };
+    return {
+      $numberDouble: Number.isInteger(this.value) ? this.value.toFixed(1) : this.value.toString()
+    };
   }
 
   /** @internal */

package/src/error.ts

@@ -1,21 +1,60 @@
-/** @public */
+import { BSON_MAJOR_VERSION } from './constants';
+
+/**
+ * @public
+ * `BSONError` objects are thrown when runtime errors occur.
+ */
 export class BSONError extends Error {
+  /**
+   * @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;
+  }
+
+  override get name(): string {
+    return 'BSONError';
+  }
+
   constructor(message: string) {
     super(message);
   }
 
-  get name(): string {
-    return 'BSONError';
+  /**
+   * @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
+    );
   }
 }
 
 /** @public */
-export class BSONTypeError extends TypeError {
-  constructor(message: string) {
-    super(message);
+export class BSONVersionError extends BSONError {
+  get name(): 'BSONVersionError' {
+    return 'BSONVersionError';
   }
 
-  get name(): string {
-    return 'BSONTypeError';
+  constructor() {
+    super(
+      `Unsupported BSON version, bson types must be from bson ${BSON_MAJOR_VERSION}.0 or later`
+    );
   }
 }

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, BSONVersionError } from './error';
 import { Int32 } from './int_32';
 import { Long } from './long';
 import { MaxKey } from './max_key';
@@ -22,6 +28,8 @@ export type EJSONOptions = {
   legacy?: boolean;
   /** Enable Extended JSON's `relaxed` mode, which attempts to return native JS types where possible, rather than BSON types */
   relaxed?: boolean;
+  /** Enable native bigint support */
+  useBigInt64?: boolean;
 };
 
 /** @internal */
@@ -70,17 +78,23 @@ const keysToCodecs = {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function deserializeValue(value: any, options: EJSONOptions = {}) {
   if (typeof value === 'number') {
+    // TODO(NODE-4377): EJSON js number handling diverges from BSON
+    const in32BitRange = value <= BSON_INT32_MAX && value >= BSON_INT32_MIN;
+    const in64BitRange = value <= BSON_INT64_MAX && value >= BSON_INT64_MIN;
+
     if (options.relaxed || options.legacy) {
       return value;
     }
 
     if (Number.isInteger(value) && !Object.is(value, -0)) {
       // interpret as being of the smallest BSON integer type that can represent the number exactly
-      if (value >= BSON_INT32_MIN && value <= BSON_INT32_MAX) {
+      if (in32BitRange) {
         return new Int32(value);
       }
-      if (value >= BSON_INT64_MIN && value <= BSON_INT64_MAX) {
-        // TODO(NODE-4377): EJSON js number handling diverges from BSON
+      if (in64BitRange) {
+        if (options.useBigInt64) {
+          return BigInt(value);
+        }
         return Long.fromNumber(value);
       }
     }
@@ -192,7 +206,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}/`
@@ -234,6 +248,13 @@ function serializeValue(value: any, options: EJSONSerializeOptions): any {
     return { $numberDouble: Object.is(value, -0) ? '-0.0' : value.toString() };
   }
 
+  if (typeof value === 'bigint') {
+    if (!options.relaxed) {
+      return { $numberLong: BigInt.asIntN(64, value).toString() };
+    }
+    return Number(BigInt.asIntN(64, value));
+  }
+
   if (value instanceof RegExp || isRegExp(value)) {
     let flags = value.flags;
     if (flags === undefined) {
@@ -310,9 +331,9 @@ 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');
+    throw new BSONVersionError();
   } else if (isBSONType(doc)) {
     // the "document" is really just a BSON type object
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -324,7 +345,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);
     }
@@ -365,13 +386,18 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function parse(text: string, options?: EJSONOptions): any {
+  const ejsonOptions = {
+    useBigInt64: options?.useBigInt64 ?? false,
+    relaxed: options?.relaxed ?? true,
+    legacy: options?.legacy ?? false
+  };
   return JSON.parse(text, (key, value) => {
     if (key.indexOf('\x00') !== -1) {
       throw new BSONError(
         `BSON Document field names cannot contain null bytes, found: ${JSON.stringify(key)}`
       );
     }
-    return deserializeValue(value, { relaxed: true, legacy: false, ...options });
+    return deserializeValue(value, ejsonOptions);
   });
 }
 

package/src/int_32.ts

@@ -1,4 +1,4 @@
-import { BSON_MAJOR_VERSION } from './constants';
+import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 
 /** @public */
@@ -11,14 +11,10 @@ export interface Int32Extended {
  * @public
  * @category BSONType
  */
-export class Int32 {
+export class Int32 extends BSONValue {
   get _bsontype(): 'Int32' {
     return 'Int32';
   }
-  /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): BSON_MAJOR_VERSION {
-    return BSON_MAJOR_VERSION;
-  }
 
   value!: number;
   /**
@@ -27,6 +23,7 @@ export class Int32 {
    * @param value - the number we want to represent as an int32.
    */
   constructor(value: number | string) {
+    super();
     if ((value as unknown) instanceof Number) {
       value = value.valueOf();
     }