Use Case

As a React Native user
I want to be able to install BSON and have it work without further steps
So that using it in conjunction with Realm SDK is straight forward

User Impact

• What is the current experience?
• BSON v5 dropped existing polyfills for maintainability reasons,
• RN environments are missing:
  • TextEncoder, TextDecoder
  • atob, btoa
  • crypto.getRandomValues (optional when app not in production)
    • Has a native component so heavier polyfill
• These have to be installed and imported onto the global object prior to importing the BSON library

Dependencies

• Realm SDK
• React Native Hermes Engine

Questions

• Can BSON point the react-native import at a bundle with polyfills?
  • Yes, this is the approach we're taking. As a side effect they will always be present until a future update where they can stop being shipped in preference of runtime globals.
• How should those optional polyfills be discovered? (ex. peerOptionalDependency?)
  • We are going to ship the polyfills in the npm release of this package, essentially pinning to a version.

Acceptance Criteria

Implementation Requirements

• Vendor text-encoding-polyfill and base-64 into the bson repo
  • This is because we need to change these to export the APIs instead of modify the global object.
• Add bundle tooling that will create a new rn-polyfill.cjs file in the lib directory.
  • This file will export TextEncoder, TextDecoder, atob, btoa using the vendored packages, it will not populate the global with these APIs.
• Add a new rollup output file bson.rn.cjs that has a require call to the polyfill file
  • The file must otherwise be unmodified from the bson.cjs bundle
  • The require invocation will keep the polyfilled APIs within the module's scope
• Update the "exports" field in the package.json to point react-native tooling at this new bundle

Testing Requirements

• Using the existing loadCJSBundle test helper
  • import the bson.rn.cjs without adding the polyfilled APIs to the global
  • assert that Binary.to/from UTF8/Base64 work without crashing

Documentation Requirements

• The BSON package will not officially support react native.
  • Despite this effort the focus is on supporting Realm users whereas RN generally might break in patch/minors and we can fix those issues as needed depending on downstream Realm needs.
• Document the support to be at a different tier than the rest of the BSON library, reference Realm's tiered support documentation for inspiration

Follow Up Requirements

• Testing to be added on Realm's CI