Merge branch 'main' into isvalid-improvement

.evergreen/config.yml

@@ -113,6 +113,15 @@ functions:
         add_expansions_to_env: true
         args:
           - .evergreen/run-granular-benchmarks.sh
+  run custom benchmarks:
+    - command: subprocess.exec
+      type: test
+      params:
+        working_dir: src
+        binary: bash
+        add_expansions_to_env: true
+        args:
+          - .evergreen/run-custom-benchmarks.sh
   run spec benchmarks:
     - command: subprocess.exec
       type: test
@@ -246,6 +255,19 @@ tasks:
       - command: perf.send
         params:
           file: src/test/bench/etc/resultsCollectedMeans.json
+  - name: run-custom-benchmarks
+    commands:
+      - func: fetch source
+        vars:
+          # This needs to stay pinned at Node v18.16.0 for consistency across perf runs.
+          NODE_LTS_VERSION: v18.16.0
+      - func: install dependencies
+        vars:
+          NPM_VERSION: 9
+      - func: run custom benchmarks
+      - command: perf.send
+        params:
+          file: src/customBenchmarkResults.json
   - name: run-spec-benchmarks
     commands:
       - func: fetch source
@@ -300,3 +322,4 @@ buildvariants:
     tasks:
       - run-granular-benchmarks
       - run-spec-benchmarks
+      - run-custom-benchmarks

.evergreen/run-custom-benchmarks.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+source "${PROJECT_DIRECTORY}/.evergreen/init-node-and-npm-env.sh"
+set -o xtrace
+
+npm run check:custom-bench

.gitignore

@@ -33,3 +33,4 @@ docs/public
 .nvmrc
 
 benchmarks.json
+customBenchmarkResults.json

docs/upgrade-to-v5.md

@@ -10,6 +10,7 @@
 - [Other Changes](#other-changes)
   - [`serializeFunctions` bug fix](#serializefunctions-bug-fix)
   - [TS "target" set to es2020](#ts-target-set-to-es2020)
+  - [Removed SerializableTypes](#removed-serializabletypes)
 
 ## About
 
@@ -313,3 +314,15 @@ import { serialize } from 'bson5';
 serialize({ _id: new ObjectId() });
 // Uncaught BSONVersionError: Unsupported BSON version, bson types must be from bson 5.0 or later
 ```
+
+### Removed SerializableTypes
+
+```ts
+export type JSONPrimitive = string | number | boolean | null;
+export type SerializableTypes = Document | Array<JSONPrimitive | Document> | JSONPrimitive;
+```
+
+`SerializableTypes` is removed in v5 due to its inaccuracy and inconvenience when working with return type of `EJSON.parse()`.
+This type does not contain all possible outputs from this function and it cannot be conveniently related to a custom declared type.
+`EJSON.parse` and `EJSON.stringify` now accept `any` in alignment with `JSON`'s corresponding APIs.
+For users that desire type strictness it is recommended to wrap these APIs with type annotations that take/return `unknown` since that generally forces better narrowing logic than `SerializableTypes` would have prompted.

package.json

@@ -105,6 +105,7 @@
     "check:web-no-bigint": "WEB=true NO_BIGINT=true mocha test/node",
     "check:granular-bench": "npm run build:bench && node ./test/bench/etc/run_granular_benchmarks.js",
     "check:spec-bench": "npm run build:bench && node ./test/bench/lib/spec/bsonBench.js",
+    "check:custom-bench": "npm run build && node ./test/bench/custom/main.mjs",
     "build:bench": "cd test/bench && npx tsc",
     "build:ts": "node ./node_modules/typescript/bin/tsc",
     "build:dts": "npm run build:ts && api-extractor run --typescript-compiler-folder node_modules/typescript --local && node etc/clean_definition_files.cjs",

src/bson_value.ts

@@ -1,13 +1,14 @@
 import { BSON_MAJOR_VERSION } from './constants';
 import { type InspectFn } from './parser/utils';
+import { BSON_VERSION_SYMBOL } from './constants';
 
 /** @public */
 export abstract class BSONValue {
   /** @public */
   public abstract get _bsontype(): string;
 
   /** @internal */
-  get [Symbol.for('@@mdb.bson.version')](): typeof BSON_MAJOR_VERSION {
+  get [BSON_VERSION_SYMBOL](): typeof BSON_MAJOR_VERSION {
     return BSON_MAJOR_VERSION;
   }
 

src/constants.ts

@@ -1,6 +1,9 @@
 /** @internal */
 export const BSON_MAJOR_VERSION = 6;
 
+/** @internal */
+export const BSON_VERSION_SYMBOL = Symbol.for('@@mdb.bson.version');
+
 /** @internal */
 export const BSON_INT32_MAX = 0x7fffffff;
 /** @internal */

src/decimal128.ts

@@ -142,7 +142,7 @@ export class Decimal128 extends BSONValue {
     super();
     if (typeof bytes === 'string') {
       this.bytes = Decimal128.fromString(bytes).bytes;
-    } else if (isUint8Array(bytes)) {
+    } else if (bytes instanceof Uint8Array || isUint8Array(bytes)) {
       if (bytes.byteLength !== 16) {
         throw new BSONError('Decimal128 must take a Buffer of 16 bytes');
       }

src/extended_json.ts

@@ -6,7 +6,8 @@ import {
   BSON_INT32_MIN,
   BSON_INT64_MAX,
   BSON_INT64_MIN,
-  BSON_MAJOR_VERSION
+  BSON_MAJOR_VERSION,
+  BSON_VERSION_SYMBOL
 } from './constants';
 import { DBRef, isDBRefLike } from './db_ref';
 import { Decimal128 } from './decimal128';
@@ -358,7 +359,7 @@ function serializeDocument(doc: any, options: EJSONSerializeOptions) {
     doc != null &&
     typeof doc === 'object' &&
     typeof doc._bsontype === 'string' &&
-    doc[Symbol.for('@@mdb.bson.version')] !== BSON_MAJOR_VERSION
+    doc[BSON_VERSION_SYMBOL] !== BSON_MAJOR_VERSION
   ) {
     throw new BSONVersionError();
   } else if (isBSONType(doc)) {

src/parser/calculate_size.ts

@@ -81,7 +81,7 @@ function calculateElement(
       if (
         value != null &&
         typeof value._bsontype === 'string' &&
-        value[Symbol.for('@@mdb.bson.version')] !== constants.BSON_MAJOR_VERSION
+        value[constants.BSON_VERSION_SYMBOL] !== constants.BSON_MAJOR_VERSION
       ) {
         throw new BSONVersionError();
       } else if (value == null || value._bsontype === 'MinKey' || value._bsontype === 'MaxKey') {