feat(NODE-5957): add BSON indexing API

[nbbeeken]

Description

What is changing?

• Add new parseToElements API for experimental use only
• Breaks out the step of parsing BSON into its components by ONLY determining types, and offsets and lengths of element names and values
• Adds a new BSONOffsetError, also experimental, that is specific to this API

Algorithm

1. Defaults offset to 0
2. Create an empty array of "elements"
3. Always operates on a BSON document, so it asserts the leading 4 bytes are a positive int32 that is not larger than the length of the input minus the starting offset
   1. We also assert that the position in the input equal to the declared size minus 1 is 0.
4. The first type of every document begins at offset=4 while that offset is less than the document size plus the starting offset we read a single byte from the input
5. If that type is 0 and the current offset is equal to the document length then we have reached the end of the document
6. If that type is 0 and the current offset is NOT equal to the document length, then the BSON is invalid
7. If the type is any other number we attempt to determine the length of a null-terminated string from the input
   1. The search for null should never overrun the size of the document
8. Depending on the type we either store a hardcoded length or read the input to determine its length
   1. If Double (1), Long (18), Date (9), Timestamp (17), then the length is 8
   2. If Int (16), then the length is 4
   3. If ObjectId (7), then the length is 12
   4. If Decimal128 (19), then the length is 16
   5. If Boolean (8), then the length is 1
   6. If Null (10), Undefined (6), MaxKey (127), MinKey (255), then the length is 0
   7. If Regexp (11)
      1. We search for a null terminator of the pattern string and use that length plus 1 to search for another null terminator of the flags string
   8. If Object (3), Array (4), CodeWithScope (15)
      1. We use the next 4 bytes as a positive int32 to calculate the length
   9. If String (2), Binary (5), DBpointer (12), Code (13), Symbol (14)
      1. We use the next 4 bytes as a positive int32 plus 4 bytes to calculate the length
      2. If Binary (5) we add 1 to the length for the subtype
      3. If DBpointer (12) we add 12 to the length for the ObjectId
   10. Else we throw an error that the type is unknown
9. If the length calculated exceeds the documentSize then we throw an error (malformed int32)
10. Push the type, nameOffset, nameLength, offset, and length to the array of elements
11. Increment the offset by length
12. When the loop finishes return elements

Is there new documentation needed for these changes?

There is TS doc marking the new APIs as @experimental

What is the motivation for this change?

This API is intended to be a building block for unlocking optimizations around lazily parsing BSON.

Double check the following

• Ran npm run check:lint script
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[aditi-khare-mongoDB]

LGTM, left a few clarifying comments

[aditi-khare-mongoDB]

LGTM!

Concerns addressed and go-ahead to merge given via slack