feat(NODE-4892)!: error on bson types not from this version (#543)

Co-authored-by: Durran Jordan <[email protected]>

Author: nbbeeken

docs/upgrade-to-v5.md

@@ -288,3 +288,19 @@ try {
   throw error;
 }
 ```
+
+### Explicit cross version incompatibility
+
+Starting with v5.0.0 of the BSON library instances of types from previous versions will throw an error when passed to the serializer.
+This is to ensure that types are always serialized correctly and that there is no unexpected silent BSON serialization mistakes that could occur when mixing versions.
+It's unexpected for any applications to have more than one version of the BSON library but with nested dependencies and re-exporting, this new error will illuminate those incorrect combinations.
+
+```ts
+// npm install bson4@npm:bson@4
+// npm install bson5@npm:bson@5
+import { ObjectId } from 'bson4';
+import { serialize } from 'bson5';
+
+serialize({ _id: new ObjectId() });
+// Uncaught BSONVersionError: Unsupported BSON version, bson types must be from bson 5.0 or later
+```

src/binary.ts

@@ -4,6 +4,7 @@ import type { EJSONOptions } from './extended_json';
 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,7 +28,7 @@ export interface BinaryExtended {
  * @public
  * @category BSONType
  */
-export class Binary {
+export class Binary extends BSONValue {
   get _bsontype(): 'Binary' {
     return 'Binary';
   }
@@ -75,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') &&

src/bson.ts

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

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;
+}

src/code.ts

@@ -1,4 +1,5 @@
 import type { Document } from './bson';
+import { BSONValue } from './bson_value';
 
 /** @public */
 export interface CodeExtended {
@@ -11,7 +12,7 @@ export interface CodeExtended {
  * @public
  * @category BSONType
  */
-export class Code {
+export class Code extends BSONValue {
   get _bsontype(): 'Code' {
     return 'Code';
   }
@@ -27,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;
   }

src/constants.ts

@@ -1,3 +1,6 @@
+/** @internal */
+export const BSON_MAJOR_VERSION = 5 as const;
+
 /** @internal */
 export const BSON_INT32_MAX = 0x7fffffff;
 /** @internal */

src/db_ref.ts

@@ -1,4 +1,5 @@
 import type { Document } from './bson';
+import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 import type { ObjectId } from './objectid';
 
@@ -28,7 +29,7 @@ export function isDBRefLike(value: unknown): value is DBRefLike {
  * @public
  * @category BSONType
  */
-export class DBRef {
+export class DBRef extends BSONValue {
   get _bsontype(): 'DBRef' {
     return 'DBRef';
   }
@@ -44,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) {

src/decimal128.ts

@@ -1,3 +1,4 @@
+import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import { Long } from './long';
 import { isUint8Array } from './parser/utils';
@@ -126,7 +127,7 @@ export interface Decimal128Extended {
  * @public
  * @category BSONType
  */
-export class Decimal128 {
+export class Decimal128 extends BSONValue {
   get _bsontype(): 'Decimal128' {
     return 'Decimal128';
   }
@@ -138,6 +139,7 @@ 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)) {

src/double.ts

@@ -1,3 +1,4 @@
+import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 
 /** @public */
@@ -10,7 +11,7 @@ export interface DoubleExtended {
  * @public
  * @category BSONType
  */
-export class Double {
+export class Double extends BSONValue {
   get _bsontype(): 'Double' {
     return 'Double';
   }
@@ -22,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();
     }

src/error.ts

@@ -1,3 +1,5 @@
+import { BSON_MAJOR_VERSION } from './constants';
+
 /**
  * @public
  * `BSONError` objects are thrown when runtime errors occur.
@@ -43,3 +45,16 @@ export class BSONError extends Error {
     );
   }
 }
+
+/** @public */
+export class BSONVersionError extends BSONError {
+  get name(): 'BSONVersionError' {
+    return 'BSONVersionError';
+  }
+
+  constructor() {
+    super(
+      `Unsupported BSON version, bson types must be from bson ${BSON_MAJOR_VERSION}.0 or later`
+    );
+  }
+}