Epic: Polyfill Flexibility
This is the master issue to track work necessary to tackle the inflexibility of the SDK in regards to dependencies and polyfills. It lives in this repo (stellar/js-stellar-sdk) but the work covers multiple repos.
First, the doc that put us on this path: link (see 2. Packaging).
Package Structure
We need our packages to be more modular:
Problematic Dependencies
We need to eliminate the use of dependencies that are problematic (meaning: not available in every deployment environment, not cross-platform, not pleasant to use, etc.) or provide thorough instructions on what does or does not need to be polyfilled by the application developer.
The philosophy imbued here follows w3ctag/polyfills#6/comment. The libraries will make the best possible assumption about which library to use if some functionality is needed. For example, if dealing with bytes is commonplace in a library, it will rely on the existence of Buffer. However, as a library, it will not polyfill it on its own. Instead, it should detect the existence of the object at runtime and provide an appropriate error + instructions.
For example, if we started a project:
npm init -y && npm install stellar-sdk
echo 'const sdk = require("stellar-sdk");' > index.js
firefox index.js We would get an error in the console:
Error: 'Buffer' polyfill not detected. Configure your bundling pipeline to provide the Buffer class (e.g. https://github.com/feross/buffer).
The following dependencies need work:
In fact, many of the dependencies can be replaced.
- in
stellar-base, we have:
Epic: Polyfill Flexibility
This is the master issue to track work necessary to tackle the inflexibility of the SDK in regards to dependencies and polyfills. It lives in this repo (stellar/js-stellar-sdk) but the work covers multiple repos.
First, the doc that put us on this path: link (see 2. Packaging).
Package Structure
We need our packages to be more modular:
sodium-nativetweetnaclcrypto(or a polyfill)@fulltag, e.g.yarn add stellar-base@full:soroban-clientandstellar-sdkinto one library:SorobannamespaceHorizonnamespacexdrnamespace@stellar/strkey@stellar/webauthProblematic Dependencies
We need to eliminate the use of dependencies that are problematic (meaning: not available in every deployment environment, not cross-platform, not pleasant to use, etc.) or provide thorough instructions on what does or does not need to be polyfilled by the application developer.
The philosophy imbued here follows w3ctag/polyfills#6/comment. The libraries will make the best possible assumption about which library to use if some functionality is needed. For example, if dealing with bytes is commonplace in a library, it will rely on the existence of
Buffer. However, as a library, it will not polyfill it on its own. Instead, it should detect the existence of the object at runtime and provide an appropriate error + instructions.For example, if we started a project:
We would get an error in the console:
The following dependencies need work:
Buffer, which is problematic because it's only available in Node environments and can be replaced with (a) a custom wrapper over the nativeUint8Array, (b) an explicit polyfill instruction, or (c) a full port over toUint8Array.js-xdrstellar-basestellar-sdkstellar-sdkaxiosinstellar-sdkis problematic because it doesn't support HTTP/2 (see Stellar SDK doesn't fully support HTTP2 #612 and HTTP/2 support axios/axios#1175) and can't be used in a lot of environments (see Replace Axios with Fetch #241)eventsourceis problematic because not everyone needs streaming support and SSE isn't supported in all environmentssodium-nativeis problematic because it requires complicated compilation steps and can't always be elided (see Design Doc: Flexibility in choosing a cryptography provider js-stellar-base#646 for a proposed solution)In fact, many of the dependencies can be replaced.
stellar-base, we have:base32.jscan be inlinedbignumber.jscan usebigints plus Migrate code to use the nativeBigInttype wherever possible. js-stellar-base#607buffercan be polyfilled or ported to use nativeUint8Arrays (noted above)crccan be inlined (see remove the dependency on crc by calculating checksum in strkey js-stellar-base#621)sha.jscan probably be inlined