bson 6.1.0 → 6.3.0

package/src/symbol.ts

@@ -1,4 +1,5 @@
 import { BSONValue } from './bson_value';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export interface BSONSymbolExtended {
@@ -33,10 +34,6 @@ export class BSONSymbol extends BSONValue {
     return this.value;
   }
 
-  inspect(): string {
-    return `new BSONSymbol(${JSON.stringify(this.value)})`;
-  }
-
   toJSON(): string {
     return this.value;
   }
@@ -51,8 +48,8 @@ export class BSONSymbol extends BSONValue {
     return new BSONSymbol(doc.$symbol);
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    return `new BSONSymbol(${inspect(this.value, options)})`;
   }
 }

package/src/timestamp.ts

@@ -1,6 +1,7 @@
 import { BSONError } from './error';
 import type { Int32 } from './int_32';
 import { Long } from './long';
+import { type InspectFn, defaultInspect } from './parser/utils';
 
 /** @public */
 export type TimestampOverrides = '_bsontype' | 'toExtendedJSON' | 'fromExtendedJSON' | 'inspect';
@@ -141,12 +142,10 @@ export class Timestamp extends LongWithoutOverridesClass {
     return new Timestamp({ t, i });
   }
 
-  /** @internal */
-  [Symbol.for('nodejs.util.inspect.custom')](): string {
-    return this.inspect();
-  }
-
-  inspect(): string {
-    return `new Timestamp({ t: ${this.getHighBits()}, i: ${this.getLowBits()} })`;
+  inspect(depth?: number, options?: unknown, inspect?: InspectFn): string {
+    inspect ??= defaultInspect;
+    const t = inspect(this.high >>> 0, options);
+    const i = inspect(this.low >>> 0, options);
+    return `new Timestamp({ t: ${t}, i: ${i} })`;
   }
 }

package/src/utils/byte_utils.ts

@@ -25,8 +25,8 @@ export type ByteUtils = {
   toHex: (buffer: Uint8Array) => string;
   /** Create a Uint8Array containing utf8 code units from a string */
   fromUTF8: (text: string) => Uint8Array;
-  /** Create a string from utf8 code units */
-  toUTF8: (buffer: Uint8Array, start: number, end: number) => string;
+  /** Create a string from utf8 code units, fatal=true will throw an error if UTF-8 bytes are invalid, fatal=false will insert replacement characters */
+  toUTF8: (buffer: Uint8Array, start: number, end: number, fatal: boolean) => string;
   /** Get the utf8 code unit count from a string if it were to be transformed to utf8 */
   utf8ByteLength: (input: string) => number;
   /** Encode UTF8 bytes generated from `source` string into `destination` at byteOffset. Returns the number of bytes encoded. */

package/src/utils/latin.ts

@@ -0,0 +1,61 @@
+/**
+ * This function is an optimization for small basic latin strings.
+ * @internal
+ * @remarks
+ * ### Important characteristics:
+ * - If the uint8array or distance between start and end is 0 this function returns an empty string
+ * - If the byteLength of the string is 1, 2, or 3 we invoke String.fromCharCode and manually offset into the buffer
+ * - If the byteLength of the string is less than or equal to 20 an array of bytes is built and `String.fromCharCode.apply` is called with the result
+ * - If any byte exceeds 128 this function returns null
+ *
+ * @param uint8array - A sequence of bytes that may contain basic latin characters
+ * @param start - The start index from which to search the uint8array
+ * @param end - The index to stop searching the uint8array
+ * @returns string if all bytes are within the basic latin range, otherwise null
+ */
+export function tryLatin(uint8array: Uint8Array, start: number, end: number): string | null {
+  if (uint8array.length === 0) {
+    return '';
+  }
+
+  const stringByteLength = end - start;
+  if (stringByteLength === 0) {
+    return '';
+  }
+
+  if (stringByteLength > 20) {
+    return null;
+  }
+
+  if (stringByteLength === 1 && uint8array[start] < 128) {
+    return String.fromCharCode(uint8array[start]);
+  }
+
+  if (stringByteLength === 2 && uint8array[start] < 128 && uint8array[start + 1] < 128) {
+    return String.fromCharCode(uint8array[start]) + String.fromCharCode(uint8array[start + 1]);
+  }
+
+  if (
+    stringByteLength === 3 &&
+    uint8array[start] < 128 &&
+    uint8array[start + 1] < 128 &&
+    uint8array[start + 2] < 128
+  ) {
+    return (
+      String.fromCharCode(uint8array[start]) +
+      String.fromCharCode(uint8array[start + 1]) +
+      String.fromCharCode(uint8array[start + 2])
+    );
+  }
+
+  const latinBytes = [];
+  for (let i = start; i < end; i++) {
+    const byte = uint8array[i];
+    if (byte > 127) {
+      return null;
+    }
+    latinBytes.push(byte);
+  }
+
+  return String.fromCharCode(...latinBytes);
+}

package/src/utils/node_byte_utils.ts

@@ -1,4 +1,6 @@
 import { BSONError } from '../error';
+import { validateUtf8 } from '../validate_utf8';
+import { tryLatin } from './latin';
 
 type NodeJsEncoding = 'base64' | 'hex' | 'utf8' | 'binary';
 type NodeJsBuffer = ArrayBufferView &
@@ -125,8 +127,25 @@ export const nodeJsByteUtils = {
     return Buffer.from(text, 'utf8');
   },
 
-  toUTF8(buffer: Uint8Array, start: number, end: number): string {
-    return nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8', start, end);
+  toUTF8(buffer: Uint8Array, start: number, end: number, fatal: boolean): string {
+    const basicLatin = end - start <= 20 ? tryLatin(buffer, start, end) : null;
+    if (basicLatin != null) {
+      return basicLatin;
+    }
+
+    const string = nodeJsByteUtils.toLocalBufferType(buffer).toString('utf8', start, end);
+    if (fatal) {
+      // TODO(NODE-4930): Insufficiently strict BSON UTF8 validation
+      for (let i = 0; i < string.length; i++) {
+        if (string.charCodeAt(i) === 0xfffd) {
+          if (!validateUtf8(buffer, start, end)) {
+            throw new BSONError('Invalid UTF-8 string in BSON document');
+          }
+          break;
+        }
+      }
+    }
+    return string;
   },
 
   utf8ByteLength(input: string): number {

package/src/utils/web_byte_utils.ts

@@ -1,4 +1,5 @@
 import { BSONError } from '../error';
+import { tryLatin } from './latin';
 
 type TextDecoder = {
   readonly encoding: string;
@@ -172,8 +173,20 @@ export const webByteUtils = {
     return new TextEncoder().encode(text);
   },
 
-  toUTF8(uint8array: Uint8Array, start: number, end: number): string {
-    return new TextDecoder('utf8', { fatal: false }).decode(uint8array.slice(start, end));
+  toUTF8(uint8array: Uint8Array, start: number, end: number, fatal: boolean): string {
+    const basicLatin = end - start <= 20 ? tryLatin(uint8array, start, end) : null;
+    if (basicLatin != null) {
+      return basicLatin;
+    }
+
+    if (fatal) {
+      try {
+        return new TextDecoder('utf8', { fatal }).decode(uint8array.slice(start, end));
+      } catch (cause) {
+        throw new BSONError('Invalid UTF-8 string in BSON document', { cause });
+      }
+    }
+    return new TextDecoder('utf8', { fatal }).decode(uint8array.slice(start, end));
   },
 
   utf8ByteLength(input: string): number {