From 38fdc7f7f9f966419ef07b1549d66bdb215c122b Mon Sep 17 00:00:00 2001
From: Neal Beeken <neal.beeken@mongodb.com>
Date: Mon, 18 Mar 2024 11:17:13 -0400
Subject: [PATCH 1/2] feat(NODE-5959): make byte parsing utils available on
 onDemand library

---
 src/parser/on_demand/index.ts             | 12 +++++++++++-
 src/parser/on_demand/parse_to_elements.ts |  4 +++-
 src/utils/byte_utils.ts                   |  5 ++++-
 src/utils/number_utils.ts                 | 21 +++++++++++++++++++--
 4 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/src/parser/on_demand/index.ts b/src/parser/on_demand/index.ts
index dd3094ec..1b86d728 100644
--- a/src/parser/on_demand/index.ts
+++ b/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);
 
diff --git a/src/parser/on_demand/parse_to_elements.ts b/src/parser/on_demand/parse_to_elements.ts
index 0a778a92..3672b6f5 100644
--- a/src/parser/on_demand/parse_to_elements.ts
+++ b/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 {
diff --git a/src/utils/byte_utils.ts b/src/utils/byte_utils.ts
index 9c748acb..1cf29f8b 100644
--- a/src/utils/byte_utils.ts
+++ b/src/utils/byte_utils.ts
@@ -1,7 +1,10 @@
 import { nodeJsByteUtils } from './node_byte_utils';
 import { webByteUtils } from './web_byte_utils';
 
-/** @internal */
+/**
+ * @public
+ * @experimental
+ */
 export type ByteUtils = {
   /** Transforms the input to an instance of Buffer if running on node, otherwise Uint8Array */
   toLocalBufferType(buffer: Uint8Array | ArrayBufferView | ArrayBuffer): Uint8Array;
diff --git a/src/utils/number_utils.ts b/src/utils/number_utils.ts
index 66dd4ff5..b80b86b4 100644
--- a/src/utils/number_utils.ts
+++ b/src/utils/number_utils.ts
@@ -6,12 +6,29 @@ FLOAT[0] = -1;
 // Big endian    [191, 240, 0, 0, 0, 0, 0, 0]
 const isBigEndian = FLOAT_BYTES[7] === 0;
 
+/**
+ * @experimental
+ * @public
+ */
+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 (

From 33e073cec86c023d8f4480ded77de77731b7542e Mon Sep 17 00:00:00 2001
From: Neal Beeken <neal.beeken@mongodb.com>
Date: Mon, 18 Mar 2024 16:28:01 -0400
Subject: [PATCH 2/2] docs: byteutils and numberutils

---
 src/utils/byte_utils.ts   | 3 +++
 src/utils/number_utils.ts | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/src/utils/byte_utils.ts b/src/utils/byte_utils.ts
index 1cf29f8b..63ad742e 100644
--- a/src/utils/byte_utils.ts
+++ b/src/utils/byte_utils.ts
@@ -4,6 +4,9 @@ import { webByteUtils } from './web_byte_utils';
 /**
  * @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 */
diff --git a/src/utils/number_utils.ts b/src/utils/number_utils.ts
index b80b86b4..162897e9 100644
--- a/src/utils/number_utils.ts
+++ b/src/utils/number_utils.ts
@@ -9,6 +9,8 @@ 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;