girlmath

Currency conversion lib

Table of Contents

• Installation
• Usage
• Development
  • Prerequisites
  • Running Tests
  • npm scripts
  • Directory Structure
  • Generating JS Lib

Installation

girlmath is available on npm and can be installed by running

npm install @tbd54566975/girlmath

Usage

Once installed, girlmath can be used like so:

import girlmath from '@tbd54566975/girlmath'

const btc = girlmath.convert('10', 'USD', 'BTC', '0.000023')

[!IMPORTANT] girlmath only ships ESM at the moment

[!IMPORTANT] A quirk with the auto-generated JS makes it such that girlmath must be imported as a default export

Development

Prerequisites

This project is using node v20.5.0. You can verify your node and npm installation via the terminal:

$ node --version
v20.5.0

If you don't have node installed, feel free to choose whichever approach you feel the most comfortable with. If you don't have a preferred installation method, we recommend using nvm (aka node version manager). nvm allows you to install and use different versions of node. It can be installed by running brew install nvm (assuming that you have homebrew)

Once you have installed nvm, install the desired node version with nvm install vX.Y.Z. After installation, you can run nvm use to automatically tell nvm which node version to use (this will be picked up from the target version noted in .nvmrc):

nvm use
Found 'bindings/girlmath-js/.nvmrc' with version <v20.5.0>
Now using node v20.5.0 (npm v9.8.0)

Running Tests

First things first run:

cd bindings/girlmath-js
npm install

Running tests requires the js lib to be generated first which can be done by running:

npm run generate-lib

running node runtime tests:

npm run test:node

running browser runtime tests requires installing headless browsers (chrome, firefox, and webkit) which can be done by running:

npx playwright install

running the tests:

npm run test:browser

npm scripts

| command | description | | :--------------------- | :-------------------------------------------------- | | npm run clean | deletes all autogenerated dirs | | npm run generate-lib | generates js lib from a clean slate | | npm run test:node | runs tests in node runtime | | npm run test:browser | runs tests in browser runtime using web-test-runner |

Directory Structure

.
├── Cargo.toml
├── README.md
├── package.json
├── dist # <-- dir where gitignored bundled js and auto-generated typings are output
│   └── index.js
├── pkg # <-- gitignored dir where wasm-pack generated js is output
├── scripts
│   ├── build.sh # <-- runs wasm-pack, base64 encodes wasm output, and adds utility functions to autogenerated js
│   ├── bundle.js # <-- bundles autogenerated js 
│   ├── epilogue.d.ts
│   └── epilogue.js # <-- utility functions added to autogenerated js
├── src # <-- rust bindings
│   └── lib.rs
├── tests
│   ├── bundle-tests.js # <-- script used to bundle tests to be run in the browser
│   ├── compiled # <-- gitignored dir where bundled tests are output
│   └── girlmath.test.js
└── web-test-runner.config.mjs

Generating JS Lib

[!NOTE] Almost all of the heavy lifting is done by wasm-pack.

It all starts in src/lib.rs which is the code wasm-pack compiles to WASM. This can be done by running scripts/build.sh.

[!NOTE] the rustdoc in src/lib.rs is automatically converted into TSDoc

wasm-pack generates the wasm and necessary JS code to use/run the wasm and outputs it into the pkg directory. our scripts/build.sh script converts the wasm into a JS file that exports the base64'ed wasm. This makes it such that the wasm can be imported and loaded synchronously without making a network request. build.sh also adds utility functions that allow for synchronous wasm loading and base64 decoding

[!NOTE] wasm-pack also auto-generates the type declarations

[!NOTE] wasm-pack generates commonJS (aka cjs)

Then, scripts/bundle.js is run to bundle all JS into 1 file as ESM which is output into the dist directory alongside index.js. Both of these files in addition to the type declarations are what get packed into the tarball published to npm.

[!NOTE] index.js imports the bundle and runs loadWasmSync so that downstream consumers don't have to.