feat(NODE-5959): make byte parsing utils available on onDemand library (#662)

Author: nbbeeken

src/parser/on_demand/index.ts

@@ -1,5 +1,7 @@
 import { type BSONError, BSONOffsetError } from '../../error';
-import { type BSONElement, parseToElements } from './parse_to_elements';
+import { ByteUtils } from '../../utils/byte_utils';
+import { NumberUtils } from '../../utils/number_utils';
+import { type BSONElement, parseToElements, getSize } from './parse_to_elements';
 import { type BSONReviver, type Container, parseToStructure } from './parse_to_structure';
 /**
  * @experimental
@@ -28,6 +30,11 @@ export type OnDemand = {
   BSONElement: BSONElement;
   Container: Container;
   BSONReviver: BSONReviver;
+
+  // Utils
+  ByteUtils: ByteUtils;
+  NumberUtils: NumberUtils;
+  getSize: (source: Uint8Array, offset: number) => number;
 };
 
 /**
@@ -39,6 +46,9 @@ const onDemand: OnDemand = Object.create(null);
 onDemand.parseToElements = parseToElements;
 onDemand.parseToStructure = parseToStructure;
 onDemand.BSONOffsetError = BSONOffsetError;
+onDemand.ByteUtils = ByteUtils;
+onDemand.NumberUtils = NumberUtils;
+onDemand.getSize = getSize;
 
 Object.freeze(onDemand);
 

src/parser/on_demand/parse_to_elements.ts

@@ -45,7 +45,9 @@ export type BSONElement = [
 ];
 
 /**
- * @internal
+ * @experimental
+ * @public
+ *
  * Parses a int32 little-endian at offset, throws if it is negative
  */
 export function getSize(source: Uint8Array, offset: number): number {

src/utils/byte_utils.ts

@@ -1,7 +1,13 @@
 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;

src/utils/number_utils.ts

@@ -6,12 +6,31 @@ FLOAT[0] = -1;
 // Big endian    [191, 240, 0, 0, 0, 0, 0, 0]
 const isBigEndian = FLOAT_BYTES[7] === 0;
 
+/**
+ * @experimental
+ * @public
+ *
+ * A collection of functions that get or set various numeric types and bit widths from a Uint8Array.
+ */
+export type NumberUtils = {
+  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 = {
   /** Reads a little-endian 32-bit integer from source */
   getInt32LE(source: Uint8Array, offset: number): number {
     return (