Use Case

As a Node.js engineer and user
I want a clear idea of whether an API views or copies bytes
So that I can write code accordingly

User Experience

• What is the desired/expected outcome for the user once this ticket is implemented?
  • At the very least documentation that calls out whether a view or copy is made
  • Copying when it makes sense to have a unique copy of data
  • Viewing when performance matters and copying can be accomplished externally

Dependencies

• BSON

Risks/Unknowns

• What could go wrong while implementing this change? (e.g., performance, inadvertent behavioral changes in adjacent functionality, existing tech debt, etc)
  • Caution should be taken to not regress performance if changes are being made
  • Semver also applies what normally would have been a copy should not become a view if it would break the assumption that bytes can be modified without side-effects on other views
• Is there an opportunity for better cross-driver alignment or testing in this area?
  • Perhaps. It is a general concept that is in other languages. IIRC rust is capable of no copy views over BSON, but they can also control mutability in their declarations.
• Is there an opportunity to improve existing documentation on this subject?
  • Yes that is the minimum goal of this ticket.

Acceptance Criteria

Implementation Requirements

• Audit all:
  • views (Buffer.slice, subarray, Uint8Array given arraybuffer, etc.)
  • copies (Uint8Array.slice, Uint8Array given an iterable)
• Add documentation clarifying which should be expected externally
• Identify if any are problematic

Testing Requirements

• Any existing API should be tested to not change from view returning to copy returning or visa versa.

Documentation Requirements

• API Docs
• Maybe manual docs if there's some global opinion/stance taken on views vs copies

Follow Up Requirements

• File a ticket to standardize behavior