bson - npm Package Compare versions

Comparing version 6.5.0 to 6.6.0

bson.d.ts

@@ -143,5 +143,7 @@ /**
         BSONRuntimeError,
+        BSONOffsetError,
         BSONType,
         EJSON,
         onDemand,
+        OnDemand,
         Document,
@@ -200,6 +202,8 @@ CalculateObjectSizeOptions
  */
-declare class BSONOffsetError extends BSONError {
+export declare class BSONOffsetError extends BSONError {
     get name(): 'BSONOffsetError';
     offset: number;
-    constructor(message: string, offset: number);
+    constructor(message: string, offset: number, options?: {
+        cause?: unknown;
+    });
 }
@@ -331,2 +335,44 @@
 /**
+ * @public
+ * @experimental
+ *
+ * A collection of functions that help work with data in a Uint8Array.
+ * ByteUtils is configured at load time to use Node.js or Web based APIs for the internal implementations.
+ */
+declare type ByteUtils = {
+    /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
+    toLocalBufferType: (buffer: Uint8Array | ArrayBufferView | ArrayBuffer) => Uint8Array;
+    /** Create empty space of size */
+    allocate: (size: number) => Uint8Array;
+    /** Create empty space of size, use pooled memory when available */
+    allocateUnsafe: (size: number) => Uint8Array;
+    /** Check if two Uint8Arrays are deep equal */
+    equals: (a: Uint8Array, b: Uint8Array) => boolean;
+    /** Check if two Uint8Arrays are deep equal */
+    fromNumberArray: (array: number[]) => Uint8Array;
+    /** Create a Uint8Array from a base64 string */
+    fromBase64: (base64: string) => Uint8Array;
+    /** Create a base64 string from bytes */
+    toBase64: (buffer: Uint8Array) => string;
+    /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+    fromISO88591: (codePoints: string) => Uint8Array;
+    /** **Legacy** binary strings are an outdated method of data transfer. Do not add public API support for interpreting this format */
+    toISO88591: (buffer: Uint8Array) => string;
+    /** Create a Uint8Array from a hex string */
+    fromHex: (hex: string) => Uint8Array;
+    /** Create a lowercase hex string from bytes */
+    toHex: (buffer: Uint8Array) => 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. */
+    encodeUTF8Into: (destination: Uint8Array, source: string, byteOffset: number) => number;
+    /** Generate a Uint8Array filled with random bytes with byteLength */
+    randomBytes: (byteLength: number) => Uint8Array;
+};
+
+/* Excluded declaration from this release type: ByteUtils */
+
+/**
  * Calculate the bson size for a passed in Javascript object.
@@ -1019,2 +1065,32 @@ *
 /**
+ * @experimental
+ * @public
+ *
+ * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
+ */
+declare type NumberUtils = {
+    /**
+     * Parses a signed int32 at offset. Throws a `RangeError` if value is negative.
+     */
+    getNonnegativeInt32LE: (source: Uint8Array, offset: number) => number;
+    getInt32LE: (source: Uint8Array, offset: number) => number;
+    getUint32LE: (source: Uint8Array, offset: number) => number;
+    getUint32BE: (source: Uint8Array, offset: number) => number;
+    getBigInt64LE: (source: Uint8Array, offset: number) => bigint;
+    getFloat64LE: (source: Uint8Array, offset: number) => number;
+    setInt32BE: (destination: Uint8Array, offset: number, value: number) => 4;
+    setInt32LE: (destination: Uint8Array, offset: number, value: number) => 4;
+    setBigInt64LE: (destination: Uint8Array, offset: number, value: bigint) => 8;
+    setFloat64LE: (destination: Uint8Array, offset: number, value: number) => 8;
+};
+
+/**
+ * Number parsing and serializing utilities.
+ *
+ * @experimental
+ * @public
+ */
+declare const NumberUtils: NumberUtils;
+
+/**
  * A class representation of the BSON ObjectId type.
@@ -1149,8 +1225,7 @@ * @public
  */
-declare type OnDemand = {
-    BSONOffsetError: {
-        new (message: string, offset: number): BSONOffsetError;
-        isBSONError(value: unknown): value is BSONError;
-    };
+export declare type OnDemand = {
     parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+    BSONElement: BSONElement;
+    ByteUtils: ByteUtils;
+    NumberUtils: NumberUtils;
 };
@@ -1157,0 +1232,0 @@

package.json

@@ -17,3 +17,3 @@ {
   "types": "bson.d.ts",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "author": {
@@ -20,0 +20,0 @@ "name": "The MongoDB NodeJS Team",

src/binary.ts

@@ -189,11 +189,11 @@ import { type InspectFn, defaultInspect, isAnyArrayBuffer, isUint8Array } from './parser/utils';
   toJSON(): string {
-    return ByteUtils.toBase64(this.buffer);
+    return ByteUtils.toBase64(this.buffer.subarray(0, this.position));
   }
 
   toString(encoding?: 'hex' | 'base64' | 'utf8' | 'utf-8'): string {
-    if (encoding === 'hex') return ByteUtils.toHex(this.buffer);
-    if (encoding === 'base64') return ByteUtils.toBase64(this.buffer);
+    if (encoding === 'hex') return ByteUtils.toHex(this.buffer.subarray(0, this.position));
+    if (encoding === 'base64') return ByteUtils.toBase64(this.buffer.subarray(0, this.position));
     if (encoding === 'utf8' || encoding === 'utf-8')
-      return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength, false);
-    return ByteUtils.toUTF8(this.buffer, 0, this.buffer.byteLength, false);
+      return ByteUtils.toUTF8(this.buffer, 0, this.position, false);
+    return ByteUtils.toUTF8(this.buffer, 0, this.position, false);
   }
@@ -200,0 +200,0 @@

src/bson.ts

@@ -54,6 +54,6 @@ import { Binary, UUID } from './binary';
 export { BSONValue } from './bson_value';
-export { BSONError, BSONVersionError, BSONRuntimeError } from './error';
+export { BSONError, BSONVersionError, BSONRuntimeError, BSONOffsetError } from './error';
 export { BSONType } from './constants';
 export { EJSON } from './extended_json';
-export { onDemand } from './parser/on_demand/index';
+export { onDemand, type OnDemand } from './parser/on_demand/index';
 
@@ -60,0 +60,0 @@ /** @public */

src/error.ts

@@ -101,6 +101,6 @@ import { BSON_MAJOR_VERSION } from './constants';
 
-  constructor(message: string, offset: number) {
-    super(`${message}. offset: ${offset}`);
+  constructor(message: string, offset: number, options?: { cause?: unknown }) {
+    super(`${message}. offset: ${offset}`, options);
     this.offset = offset;
   }
 }

src/parser/on_demand/index.ts

@@ -1,2 +0,3 @@
-import { type BSONError, BSONOffsetError } from '../../error';
+import { ByteUtils } from '../../utils/byte_utils';
+import { NumberUtils } from '../../utils/number_utils';
 import { type BSONElement, parseToElements } from './parse_to_elements';
@@ -10,7 +11,9 @@ /**
 export type OnDemand = {
-  BSONOffsetError: {
-    new (message: string, offset: number): BSONOffsetError;
-    isBSONError(value: unknown): value is BSONError;
-  };
   parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+  // Types
+  BSONElement: BSONElement;
+
+  // Utils
+  ByteUtils: ByteUtils;
+  NumberUtils: NumberUtils;
 };
@@ -25,3 +28,4 @@
 onDemand.parseToElements = parseToElements;
-onDemand.BSONOffsetError = BSONOffsetError;
+onDemand.ByteUtils = ByteUtils;
+onDemand.NumberUtils = NumberUtils;
 
@@ -28,0 +32,0 @@ Object.freeze(onDemand);

src/parser/on_demand/parse_to_elements.ts

@@ -1,3 +0,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-enum-comparison */
 import { BSONOffsetError } from '../../error';
+import { NumberUtils } from '../../utils/number_utils';
 
@@ -12,3 +12,3 @@ /**
  */
-const enum t {
+const enum BSONElementType {
   double = 1,
@@ -49,13 +49,8 @@ string = 2,
 
-/** Parses a int32 little-endian at offset, throws if it is negative */
-function getSize(source: Uint8Array, offset: number): number {
-  if (source[offset + 3] > 127) {
-    throw new BSONOffsetError('BSON size cannot be negative', offset);
+function getSize(source: Uint8Array, offset: number) {
+  try {
+    return NumberUtils.getNonnegativeInt32LE(source, offset);
+  } catch (cause) {
+    throw new BSONOffsetError('BSON size cannot be negative', offset, { cause });
   }
-  return (
-    source[offset] |
-    (source[offset + 1] << 8) |
-    (source[offset + 2] << 16) |
-    (source[offset + 3] << 24)
-  );
 }
@@ -85,3 +80,8 @@
  */
-export function parseToElements(bytes: Uint8Array, startOffset = 0): Iterable<BSONElement> {
+export function parseToElements(
+  bytes: Uint8Array,
+  startOffset: number | null = 0
+): Iterable<BSONElement> {
+  startOffset ??= 0;
+
   if (bytes.length < 5) {
@@ -127,33 +127,47 @@ throw new BSONOffsetError(
 
-    if (type === t.double || type === t.long || type === t.date || type === t.timestamp) {
+    if (
+      type === BSONElementType.double ||
+      type === BSONElementType.long ||
+      type === BSONElementType.date ||
+      type === BSONElementType.timestamp
+    ) {
       length = 8;
-    } else if (type === t.int) {
+    } else if (type === BSONElementType.int) {
       length = 4;
-    } else if (type === t.objectId) {
+    } else if (type === BSONElementType.objectId) {
       length = 12;
-    } else if (type === t.decimal) {
+    } else if (type === BSONElementType.decimal) {
       length = 16;
-    } else if (type === t.bool) {
+    } else if (type === BSONElementType.bool) {
       length = 1;
-    } else if (type === t.null || type === t.undefined || type === t.maxKey || type === t.minKey) {
+    } else if (
+      type === BSONElementType.null ||
+      type === BSONElementType.undefined ||
+      type === BSONElementType.maxKey ||
+      type === BSONElementType.minKey
+    ) {
       length = 0;
     }
     // Needs a size calculation
-    else if (type === t.regex) {
+    else if (type === BSONElementType.regex) {
       length = findNull(bytes, findNull(bytes, offset) + 1) + 1 - offset;
-    } else if (type === t.object || type === t.array || type === t.javascriptWithScope) {
+    } else if (
+      type === BSONElementType.object ||
+      type === BSONElementType.array ||
+      type === BSONElementType.javascriptWithScope
+    ) {
       length = getSize(bytes, offset);
     } else if (
-      type === t.string ||
-      type === t.binData ||
-      type === t.dbPointer ||
-      type === t.javascript ||
-      type === t.symbol
+      type === BSONElementType.string ||
+      type === BSONElementType.binData ||
+      type === BSONElementType.dbPointer ||
+      type === BSONElementType.javascript ||
+      type === BSONElementType.symbol
     ) {
       length = getSize(bytes, offset) + 4;
-      if (type === t.binData) {
+      if (type === BSONElementType.binData) {
         // binary subtype
         length += 1;
       }
-      if (type === t.dbPointer) {
+      if (type === BSONElementType.dbPointer) {
         // dbPointer's objectId
@@ -160,0 +174,0 @@ length += 12;

src/utils/byte_utils.ts

 import { nodeJsByteUtils } from './node_byte_utils';
 import { webByteUtils } from './web_byte_utils';
 
-/** @internal */
+/**
+ * @public
+ * @experimental
+ *
+ * A collection of functions that help work with data in a Uint8Array.
+ * ByteUtils is configured at load time to use Node.js or Web based APIs for the internal implementations.
+ */
 export type ByteUtils = {
   /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
-  toLocalBufferType(buffer: Uint8Array | ArrayBufferView | ArrayBuffer): Uint8Array;
+  toLocalBufferType: (buffer: Uint8Array | ArrayBufferView | ArrayBuffer) => Uint8Array;
   /** Create empty space of size */
@@ -33,5 +39,5 @@ allocate: (size: number) => Uint8Array;
   /** Encode UTF8 bytes generated from `source` string into `destination` at byteOffset. Returns the number of bytes encoded. */
-  encodeUTF8Into(destination: Uint8Array, source: string, byteOffset: number): number;
+  encodeUTF8Into: (destination: Uint8Array, source: string, byteOffset: number) => number;
   /** Generate a Uint8Array filled with random bytes with byteLength */
-  randomBytes(byteLength: number): Uint8Array;
+  randomBytes: (byteLength: number) => Uint8Array;
 };
@@ -38,0 +44,0 @@

src/utils/number_utils.ts

@@ -10,7 +10,42 @@ const FLOAT = new Float64Array(1);
 /**
+ * @experimental
+ * @public
+ *
+ * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
+ */
+export type NumberUtils = {
+  /**
+   * Parses a signed int32 at offset. Throws a `RangeError` if value is negative.
+   */
+  getNonnegativeInt32LE: (source: Uint8Array, offset: number) => number;
+  getInt32LE: (source: Uint8Array, offset: number) => number;
+  getUint32LE: (source: Uint8Array, offset: number) => number;
+  getUint32BE: (source: Uint8Array, offset: number) => number;
+  getBigInt64LE: (source: Uint8Array, offset: number) => bigint;
+  getFloat64LE: (source: Uint8Array, offset: number) => number;
+  setInt32BE: (destination: Uint8Array, offset: number, value: number) => 4;
+  setInt32LE: (destination: Uint8Array, offset: number, value: number) => 4;
+  setBigInt64LE: (destination: Uint8Array, offset: number, value: bigint) => 8;
+  setFloat64LE: (destination: Uint8Array, offset: number, value: number) => 8;
+};
+
+/**
  * Number parsing and serializing utilities.
  *
- * @internal
+ * @experimental
+ * @public
  */
-export const NumberUtils = {
+export const NumberUtils: NumberUtils = {
+  getNonnegativeInt32LE(source: Uint8Array, offset: number): number {
+    if (source[offset + 3] > 127) {
+      throw new RangeError(`Size cannot be negative at offset: ${offset}`);
+    }
+    return (
+      source[offset] |
+      (source[offset + 1] << 8) |
+      (source[offset + 2] << 16) |
+      (source[offset + 3] << 24)
+    );
+  },
+
   /** Reads a little-endian 32-bit integer from source */
@@ -17,0 +52,0 @@ getInt32LE(source: Uint8Array, offset: number): number {

No alert changes

Improved metrics

Total package byte prevSize

2349492

increased by0.42%

Lines of code

30397

increased by0.68%

No dependency changes