fix(NODE-6059): clean up experimental APIs

Author: nbbeeken

src/bson.ts

@@ -51,7 +51,7 @@ export {
   Decimal128
 };
 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, type OnDemand } from './parser/on_demand/index';

src/parser/on_demand/index.ts

@@ -1,40 +1,20 @@
-import { type BSONError, BSONOffsetError } from '../../error';
 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';
+import { type BSONElement, parseToElements } from './parse_to_elements';
 /**
  * @experimental
  * @public
  *
  * A new set of BSON APIs that are currently experimental and not intended for production use.
  */
 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>;
-  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;
 
   // Utils
   ByteUtils: ByteUtils;
   NumberUtils: NumberUtils;
-  getSize: (source: Uint8Array, offset: number) => number;
 };
 
 /**
@@ -44,11 +24,8 @@ export type OnDemand = {
 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

@@ -1,4 +1,5 @@
 import { BSONOffsetError } from '../../error';
+import { NumberUtils } from '../../utils/number_utils';
 
 /**
  * @internal
@@ -44,24 +45,6 @@ export type BSONElement = [
   length: number
 ];
 
-/**
- * @experimental
- * @public
- *
- * 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);
-  }
-  return (
-    source[offset] |
-    (source[offset + 1] << 8) |
-    (source[offset + 2] << 16) |
-    (source[offset + 3] << 24)
-  );
-}
-
 /**
  * Searches for null terminator of a BSON element's value (Never the document null terminator)
  * **Does not** bounds check since this should **ONLY** be used within parseToElements which has asserted that `bytes` ends with a `0x00`.
@@ -97,7 +80,7 @@ export function parseToElements(
     );
   }
 
-  const documentSize = getSize(bytes, startOffset);
+  const documentSize = NumberUtils.getSize(bytes, startOffset);
 
   if (documentSize > bytes.length - startOffset) {
     throw new BSONOffsetError(
@@ -161,15 +144,15 @@ export function parseToElements(
       type === BSONElementType.array ||
       type === BSONElementType.javascriptWithScope
     ) {
-      length = getSize(bytes, offset);
+      length = NumberUtils.getSize(bytes, offset);
     } else if (
       type === BSONElementType.string ||
       type === BSONElementType.binData ||
       type === BSONElementType.dbPointer ||
       type === BSONElementType.javascript ||
       type === BSONElementType.symbol
     ) {
-      length = getSize(bytes, offset) + 4;
+      length = NumberUtils.getSize(bytes, offset) + 4;
       if (type === BSONElementType.binData) {
         // binary subtype
         length += 1;

src/parser/on_demand/parse_to_structure.ts

@@ -10,7 +10,7 @@ import { webByteUtils } from './web_byte_utils';
  */
 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 */
   allocate: (size: number) => Uint8Array;
   /** Create empty space of size, use pooled memory when available */
@@ -36,9 +36,9 @@ export type ByteUtils = {
   /** 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;
+  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;
 };
 
 declare const Buffer: { new (): unknown; prototype?: { _isBuffer?: boolean } } | undefined;

src/utils/byte_utils.ts

@@ -1,3 +1,5 @@
+import { BSONOffsetError } from '../error';
+
 const FLOAT = new Float64Array(1);
 const FLOAT_BYTES = new Uint8Array(FLOAT.buffer, 0, 8);
 
@@ -13,15 +15,20 @@ const isBigEndian = FLOAT_BYTES[7] === 0;
  * 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;
+  /**
+   * Parses a int32 little-endian at offset, throws if it is negative.
+   * - size as in `size_t`
+   */
+  getSize: (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;
 };
 
 /**
@@ -31,6 +38,18 @@ export type NumberUtils = {
  * @public
  */
 export const NumberUtils: NumberUtils = {
+  getSize(source: Uint8Array, offset: number): number {
+    if (source[offset + 3] > 127) {
+      throw new BSONOffsetError('BSON size cannot be negative', 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 */
   getInt32LE(source: Uint8Array, offset: number): number {
     return (

src/utils/number_utils.ts

@@ -6,7 +6,7 @@ import {
   BSONError,
   BSONVersionError,
   BSONRuntimeError,
-  onDemand
+  BSONOffsetError
 } from '../register-bson';
 
 const instanceOfChecksWork = !__isWeb__;
@@ -111,19 +111,19 @@ describe('BSONError', function () {
 
   describe('class BSONOffsetError', () => {
     it('is a BSONError instance', function () {
-      expect(BSONError.isBSONError(new onDemand.BSONOffsetError('Oopsie', 3))).to.be.true;
+      expect(BSONError.isBSONError(new BSONOffsetError('Oopsie', 3))).to.be.true;
     });
 
     it('has a name property equal to "BSONOffsetError"', function () {
-      expect(new onDemand.BSONOffsetError('Woops!', 3)).to.have.property('name', 'BSONOffsetError');
+      expect(new BSONOffsetError('Woops!', 3)).to.have.property('name', 'BSONOffsetError');
     });
 
     it('sets the offset property', function () {
-      expect(new onDemand.BSONOffsetError('Woops!', 3)).to.have.property('offset', 3);
+      expect(new BSONOffsetError('Woops!', 3)).to.have.property('offset', 3);
     });
 
     it('includes the offset in the message', function () {
-      expect(new onDemand.BSONOffsetError('Woops!', 3))
+      expect(new BSONOffsetError('Woops!', 3))
         .to.have.property('message')
         .that.matches(/offset: 3/i);
     });

test/node/error.test.ts

@@ -30,6 +30,7 @@ const EXPECTED_EXPORTS = [
   'Decimal128',
   'BSONError',
   'BSONRuntimeError',
+  'BSONOffsetError',
   'setInternalBufferSize',
   'serialize',
   'serializeWithBufferAndIndex',

test/node/exports.test.ts

@@ -5,7 +5,7 @@ import * as BSON from '../../../register-bson';
 import { bufferFromHexArray, stringToUTF8HexBytes, int32LEToHex } from '../../tools/utils';
 
 const parseToElements = BSON.onDemand.parseToElements;
-const BSONOffsetError = BSON.onDemand.BSONOffsetError;
+const BSONOffsetError = BSON.BSONOffsetError;
 
 describe('parseToElements()', () => {
   context('when given less than 5 bytes', () => {