feat(NODE-5040): add color to BSON inspect

src/binary.ts

@@ -1,4 +1,9 @@
-import { isAnyArrayBuffer, isUint8Array } from './parser/utils';
+import {
+  type InspectParameterFn,
+  basicInspectParameterFn,
+  isAnyArrayBuffer,
+  isUint8Array
+} from './parser/utils';
 import type { EJSONOptions } from './extended_json';
 import { BSONError } from './error';
 import { BSON_BINARY_SUBTYPE_UUID_NEW } from './constants';
@@ -263,14 +268,16 @@ export class Binary extends BSONValue {
     return type === BSON_BINARY_SUBTYPE_UUID_NEW ? new UUID(data) : new Binary(data, type);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    const addQuotes = inspect ? false : true;
+    inspect ??= basicInspectParameterFn;
     const base64 = ByteUtils.toBase64(this.buffer.subarray(0, this.position));
-    return `Binary.createFromBase64("${base64}", ${this.sub_type})`;
+    const base64Arg = inspect(base64, options);
+    const subTypeArg = inspect(this.sub_type, options);
+    if (addQuotes) {
+      return `Binary.createFromBase64('${base64Arg}', ${subTypeArg})`;
+    }
+    return `Binary.createFromBase64(${base64Arg}, ${subTypeArg})`;
   }
 }
 
@@ -463,13 +470,14 @@ export class UUID extends Binary {
    * Converts to a string representation of this Id.
    *
    * @returns return the 36 character hex string representation.
-   * @internal
+   *
    */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new UUID("${this.toHexString()}")`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    const addQuotes = inspect ? false : true;
+    inspect ??= basicInspectParameterFn;
+    if (addQuotes) {
+      return `new UUID('${inspect(this.toHexString(), options)}')`;
+    }
+    return `new UUID(${inspect(this.toHexString(), options)})`;
   }
 }

src/bson_value.ts

@@ -1,4 +1,5 @@
 import { BSON_MAJOR_VERSION } from './constants';
+import { type InspectParameterFn } from './parser/utils';
 
 /** @public */
 export abstract class BSONValue {
@@ -10,8 +11,16 @@ export abstract class BSONValue {
     return BSON_MAJOR_VERSION;
   }
 
+  [Symbol.for('nodejs.util.inspect.custom')](
+    depth?: number,
+    options?: unknown,
+    inspect?: InspectParameterFn
+  ): string {
+    return this.inspect(depth, options, inspect);
+  }
+
   /** @public */
-  public abstract inspect(): string;
+  public abstract inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string;
 
   /** @internal */
   abstract toExtendedJSON(): unknown;

src/code.ts

@@ -1,5 +1,6 @@
 import type { Document } from './bson';
 import { BSONValue } from './bson_value';
+import { type InspectParameterFn, basicInspectParameterFn } from './parser/utils';
 
 /** @public */
 export interface CodeExtended {
@@ -55,15 +56,14 @@ export class Code extends BSONValue {
     return new Code(doc.$code, doc.$scope);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    const codeJson = this.toJSON();
-    return `new Code(${JSON.stringify(String(codeJson.code))}${
-      codeJson.scope != null ? `, ${JSON.stringify(codeJson.scope)}` : ''
-    })`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    inspect ??= basicInspectParameterFn;
+    let parametersString = inspect(this.code, options);
+    const multiLineFn = parametersString.includes('\n');
+    if (this.scope != null) {
+      parametersString += `,${multiLineFn ? '\n' : ' '}${inspect(this.scope, options)}`;
+    }
+    const endingNewline = multiLineFn && this.scope === null;
+    return `new Code(${multiLineFn ? '\n' : ''}${parametersString}${endingNewline ? '\n' : ''})`;
   }
 }

src/db_ref.ts

@@ -2,6 +2,7 @@ import type { Document } from './bson';
 import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
 import type { ObjectId } from './objectid';
+import { type InspectParameterFn, basicInspectParameterFn } from './parser/utils';
 
 /** @public */
 export interface DBRefLike {
@@ -111,17 +112,26 @@ export class DBRef extends BSONValue {
     return new DBRef(doc.$ref, doc.$id, doc.$db, copy);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    const addQuotes = inspect ? false : true;
+    inspect ??= basicInspectParameterFn;
+
+    const namespaceArg = addQuotes
+      ? `'${inspect(this.namespace, options)}'`
+      : inspect(this.namespace, options);
+    const objectIDArg = addQuotes
+      ? `new ObjectId('${inspect(this.oid, options)}')`
+      : inspect(this.oid, options);
+    const args = [namespaceArg, objectIDArg];
+
+    if (this.db) {
+      args.push(addQuotes ? `'${inspect(this.db, options)}'` : inspect(this.db, options));
+    }
+
+    if (Object.keys(this.fields).length > 0) {
+      args.push(inspect(this.fields, options));
+    }
 
-  inspect(): string {
-    // NOTE: if OID is an ObjectId class it will just print the oid string.
-    const oid =
-      this.oid === undefined || this.oid.toString === undefined ? this.oid : this.oid.toString();
-    return `new DBRef("${this.namespace}", new ObjectId("${String(oid)}")${
-      this.db ? `, "${this.db}"` : ''
-    })`;
+    return `new DBRef(${args.join(', ')})`;
   }
 }

src/decimal128.ts

@@ -1,7 +1,7 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import { Long } from './long';
-import { isUint8Array } from './parser/utils';
+import { type InspectParameterFn, basicInspectParameterFn, isUint8Array } from './parser/utils';
 import { ByteUtils } from './utils/byte_utils';
 
 const PARSE_STRING_REGEXP = /^(\+|-)?(\d+|(\d*\.\d*))?(E|e)?([-+])?(\d+)?$/;
@@ -847,12 +847,13 @@ export class Decimal128 extends BSONValue {
     return Decimal128.fromString(doc.$numberDecimal);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Decimal128("${this.toString()}")`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    const addQuotes = inspect ? false : true;
+    inspect ??= basicInspectParameterFn;
+    const d128string = inspect(this.toString(), options);
+    if (addQuotes) {
+      return `new Decimal128('${d128string}')`;
+    }
+    return `new Decimal128(${d128string})`;
   }
 }

src/double.ts

@@ -1,5 +1,6 @@
 import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
+import { type InspectParameterFn, basicInspectParameterFn } from './parser/utils';
 
 /** @public */
 export interface DoubleExtended {
@@ -71,13 +72,8 @@ export class Double extends BSONValue {
     return options && options.relaxed ? doubleValue : new Double(doubleValue);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    const eJSON = this.toExtendedJSON() as DoubleExtended;
-    return `new Double(${eJSON.$numberDouble})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    inspect ??= basicInspectParameterFn;
+    return `new Double(${inspect(this.valueOf(), options)})`;
   }
 }

src/int_32.ts

@@ -1,5 +1,6 @@
 import { BSONValue } from './bson_value';
 import type { EJSONOptions } from './extended_json';
+import { type InspectParameterFn, basicInspectParameterFn } from './parser/utils';
 
 /** @public */
 export interface Int32Extended {
@@ -59,12 +60,8 @@ export class Int32 extends BSONValue {
     return options && options.relaxed ? parseInt(doc.$numberInt, 10) : new Int32(doc.$numberInt);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Int32(${this.valueOf()})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    inspect ??= basicInspectParameterFn;
+    return `new Int32(${inspect(this.value, options)})`;
   }
 }

src/long.ts

@@ -1,6 +1,7 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
+import { type InspectParameterFn, basicInspectParameterFn } from './parser/utils';
 import type { Timestamp } from './timestamp';
 
 interface LongWASMHelpers {
@@ -1056,12 +1057,10 @@ export class Long extends BSONValue {
     return longResult;
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Long("${this.toString()}"${this.unsigned ? ', true' : ''})`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    inspect ??= basicInspectParameterFn;
+    const longVal = inspect(this.toString(), options);
+    const unsignedVal = this.unsigned ? `, ${inspect(this.unsigned, options)}` : '';
+    return `new Long(${longVal}${unsignedVal})`;
   }
 }

src/max_key.ts

@@ -25,11 +25,6 @@ export class MaxKey extends BSONValue {
     return new MaxKey();
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
   inspect(): string {
     return 'new MaxKey()';
   }

src/min_key.ts

@@ -25,11 +25,6 @@ export class MinKey extends BSONValue {
     return new MinKey();
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
   inspect(): string {
     return 'new MinKey()';
   }

src/objectid.ts

@@ -1,5 +1,6 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
+import { type InspectParameterFn, basicInspectParameterFn } from './parser/utils';
 import { BSONDataView, ByteUtils } from './utils/byte_utils';
 
 // Regular expression that checks for hex value
@@ -294,13 +295,13 @@ export class ObjectId extends BSONValue {
    * Converts to a string representation of this Id.
    *
    * @returns return the 24 character hex string representation.
-   * @internal
    */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new ObjectId("${this.toHexString()}")`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectParameterFn): string {
+    const addQuotes = inspect ? false : true;
+    inspect ??= basicInspectParameterFn;
+    if (addQuotes) {
+      return `new ObjectId('${inspect(this.toHexString(), options)}')`;
+    }
+    return `new ObjectId(${inspect(this.toHexString(), options)})`;
   }
 }

src/parser/utils.ts

@@ -27,3 +27,23 @@ export function isMap(d: unknown): d is Map<unknown, unknown> {
 export function isDate(d: unknown): d is Date {
   return Object.prototype.toString.call(d) === '[object Date]';
 }
+
+/** @internal */
+export type StylizeFunction = (x: string, style: string) => string;
+export type InspectParameterFn = (x: unknown, options: unknown) => string;
+// eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+export const basicInspectParameterFn: InspectParameterFn = v => `${v}`;
+
+export function getStylizeFunction(options?: unknown): StylizeFunction {
+  const stylizeExists =
+    options != null &&
+    typeof options === 'object' &&
+    'stylize' in options &&
+    typeof options.stylize === 'function';
+
+  if (stylizeExists) {
+    return options.stylize as StylizeFunction;
+  } else {
+    return basicInspectParameterFn;
+  }
+}

src/regexp.ts

@@ -1,6 +1,7 @@
 import { BSONValue } from './bson_value';
 import { BSONError } from './error';
 import type { EJSONOptions } from './extended_json';
+import { getStylizeFunction } from './parser/utils';
 
 function alphabetize(str: string): string {
   return str.split('').sort().join('');
@@ -103,12 +104,15 @@ export class BSONRegExp extends BSONValue {
     throw new BSONError(`Unexpected BSONRegExp EJSON object form: ${JSON.stringify(doc)}`);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
+   /** @internal */
+   [Symbol.for('nodejs.util.inspect.custom')](depth?: number, options?: unknown): string {
+    return this.inspect(depth, options);
   }
 
-  inspect(): string {
-    return `new BSONRegExp(${JSON.stringify(this.pattern)}, ${JSON.stringify(this.options)})`;
+  inspect(depth?: number, options?: unknown): string {
+    const stylize = getStylizeFunction(options);
+    const pattern = stylize(`'${this.pattern}'`, 'regexp');
+    const flags = stylize(`'${this.options}'`, 'regexp');
+    return `new BSONRegExp(${pattern}, ${flags})`;
   }
 }