feat(NODE-5958): add BSON iterating API

.eslintrc.json

@@ -64,6 +64,7 @@
     "@typescript-eslint/no-unsafe-return": "off",
     "@typescript-eslint/no-unsafe-argument": "off",
     "@typescript-eslint/no-unsafe-call": "off",
+    "@typescript-eslint/no-unsafe-enum-comparison": "off",
     "@typescript-eslint/consistent-type-imports": [
       "error",
       {

src/bson.ts

@@ -54,7 +54,7 @@ export { BSONValue } from './bson_value';
 export { BSONError, BSONVersionError, BSONRuntimeError } 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';
 
 /** @public */
 export interface Document {

src/parser/on_demand/index.ts

@@ -1,5 +1,6 @@
 import { type BSONError, BSONOffsetError } from '../../error';
 import { type BSONElement, parseToElements } from './parse_to_elements';
+import { type BSONReviver, type Container, parseToStructure } from './parse_to_structure';
 /**
  * @experimental
  * @public
@@ -12,6 +13,21 @@ export type OnDemand = {
     isBSONError(value: unknown): value is BSONError;
   };
   parseToElements: (this: void, bytes: Uint8Array, startOffset?: number) => Iterable<BSONElement>;
+  parseToStructure: <
+    TRoot extends Container = {
+      dest: Record<string, unknown>;
+      kind: 'object';
+    }
+  >(
+    bytes: Uint8Array,
+    startOffset?: number,
+    root?: TRoot,
+    reviver?: BSONReviver
+  ) => TRoot extends undefined ? Record<string, unknown> : TRoot['dest'];
+  // Types
+  BSONElement: BSONElement;
+  Container: Container;
+  BSONReviver: BSONReviver;
 };
 
 /**
@@ -21,6 +37,7 @@ export type OnDemand = {
 const onDemand: OnDemand = Object.create(null);
 
 onDemand.parseToElements = parseToElements;
+onDemand.parseToStructure = parseToStructure;
 onDemand.BSONOffsetError = BSONOffsetError;
 
 Object.freeze(onDemand);

src/parser/on_demand/parse_to_elements.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unsafe-enum-comparison */
 import { BSONOffsetError } from '../../error';
 
 /**
@@ -45,8 +44,11 @@ export type BSONElement = [
   length: number
 ];
 
-/** Parses a int32 little-endian at offset, throws if it is negative */
-function getSize(source: Uint8Array, offset: number): number {
+/**
+ * @internal
+ * Parses a int32 little-endian at offset, throws if it is negative
+ */
+export function getSize(source: Uint8Array, offset: number): number {
   if (source[offset + 3] > 127) {
     throw new BSONOffsetError('BSON size cannot be negative', offset);
   }
@@ -80,7 +82,9 @@ function findNull(bytes: Uint8Array, offset: number): number {
  * @public
  * @experimental
  */
-export function parseToElements(bytes: Uint8Array, startOffset = 0): Iterable<BSONElement> {
+export function parseToElements(bytes: Uint8Array, pOffset?: number | null): Iterable<BSONElement> {
+  const startOffset = pOffset ?? 0;
+
   if (bytes.length < 5) {
     throw new BSONOffsetError(
       `Input must be at least 5 bytes, got ${bytes.length} bytes`,

src/parser/on_demand/parse_to_structure.ts

@@ -0,0 +1,143 @@
+import { type Code } from '../../code';
+import { type BSONElement, getSize, parseToElements } from './parse_to_elements';
+
+/** @internal */
+const DEFAULT_REVIVER: BSONReviver = (
+  _bytes: Uint8Array,
+  _container: Container,
+  _element: BSONElement
+) => null;
+
+/** @internal */
+function parseToElementsToArray(bytes: Uint8Array, offset?: number | null): BSONElement[] {
+  const res = parseToElements(bytes, offset);
+  return Array.isArray(res) ? res : [...res];
+}
+
+/** @internal */
+type ParseContext = {
+  elementOffset: number;
+  elements: BSONElement[];
+  container: Container;
+  previous: ParseContext | null;
+};
+
+/**
+ * @experimental
+ * @public
+ * A union of the possible containers for BSON elements.
+ *
+ * Depending on kind, a reviver can accurately assign a value to a name on the container.
+ */
+export type Container =
+  | {
+      dest: Record<string, unknown>;
+      kind: 'object';
+    }
+  | {
+      dest: Map<string, unknown>;
+      kind: 'map';
+    }
+  | {
+      dest: Array<unknown>;
+      kind: 'array';
+    }
+  | {
+      dest: Code;
+      kind: 'code';
+    }
+  | {
+      kind: 'custom';
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      dest: any;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      [key: string]: any;
+    };
+
+/**
+ * @experimental
+ * @public
+ */
+export type BSONReviver = (
+  bytes: Uint8Array,
+  container: Container,
+  element: BSONElement
+) => Container | null;
+
+/**
+ * @experimental
+ * @public
+ */
+export function parseToStructure<
+  TRoot extends Container = {
+    dest: Record<string, unknown>;
+    kind: 'object';
+  }
+>(
+  bytes: Uint8Array,
+  startOffset?: number | null,
+  pRoot?: TRoot | null,
+  pReviver?: BSONReviver | null
+): TRoot extends undefined ? Record<string, unknown> : TRoot['dest'] {
+  const root = pRoot ?? {
+    kind: 'object',
+    dest: Object.create(null) as Record<string, unknown>
+  };
+
+  const reviver = pReviver ?? DEFAULT_REVIVER;
+
+  let ctx: ParseContext | null = {
+    elementOffset: 0,
+    elements: parseToElementsToArray(bytes, startOffset),
+    container: root,
+    previous: null
+  };
+
+  /** BSONElement offsets: type indicator and value offset */
+  const enum e {
+    type = 0,
+    offset = 3
+  }
+
+  /** BSON Embedded types */
+  const enum t {
+    object = 3,
+    array = 4,
+    javascriptWithScope = 15
+  }
+
+  embedded: while (ctx !== null) {
+    for (
+      let it: BSONElement | undefined = ctx.elements[ctx.elementOffset++];
+      it != null;
+      it = ctx.elements[ctx.elementOffset++]
+    ) {
+      const type = it[e.type];
+      const offset = it[e.offset];
+
+      const container = reviver(bytes, ctx.container, it);
+      const isEmbeddedType =
+        type === t.object || type === t.array || type === t.javascriptWithScope;
+
+      if (container != null && isEmbeddedType) {
+        const docOffset: number =
+          type !== t.javascriptWithScope
+            ? offset
+            : // value offset + codeSize + value int + code int
+              offset + getSize(bytes, offset + 4) + 4 + 4;
+
+        ctx = {
+          elementOffset: 0,
+          elements: parseToElementsToArray(bytes, docOffset),
+          container,
+          previous: ctx
+        };
+
+        continue embedded;
+      }
+    }
+    ctx = ctx.previous;
+  }
+
+  return root.dest;
+}