npm package: @rhcp/mimir_transforms
Description: A WebAssembly build of Mimir transforms, suitable for use in Nodejs and browsers.
Latest version: 0.8.1

# Mimir's transforms packaged for WebAssembly

This is a [WebAssembly](https://webassembly.org/) build of Mimir's transforms.  Two packages are provided, [@rhcp/mimir_transforms](https://www.npmjs.com/package/@rhcp/mimir_transforms) for use in Nodejs and [@rhcp/mimir_transforms_web](https://www.npmjs.com/package/@rhcp/mimir_transforms) for use in browsers (with a [caveat](#web-usage-note)).

### Using the nodejs package

Add the dependency:

```
npm i @rhcp/mimir_transforms
```

Import & use it:

```
import { headingHash } from "@rhcp/mimir_transforms";

console.log(headingHash("#hello"));
```

Prints:

```
# hello
```

### Using the web package

```
npm i @rhcp/mimir_transforms_web
```

Import the package, initialize it, and log a transformed string.

```
import { default as init, headingHash } from "@rhcp/mimir_transforms";
await init();
console.log(headingHash("#hello"))
```

Prints:

```
# hello
```

Please note that this example assumes you have a bundler which will resolve the name `@rhcp/mimir_transforms`.


### Web usage note

The Nodejs-focused `mimir_transforms` package is the intended way to use these transforms.  The client-side `mimir_transforms_web` package is provided for one use case: live editor preview.  The reason for preferring server-side or build-time transforms is due to the size of the wasm file.  In short, users should not have to download a 1MB wasm file in order to view 10kB of content.

### List of transforms

There is currently no auto-generated documentation for these transforms, however there is a [type definition file](./mimir_transforms.d.ts) which can be consulted for the list of transforms and their descriptions.  It also allows easy discovery of transforms and their descriptions in your editor.

## Initial setup for contributors

Install wasm-pack. The [wasm-pack](https://rustwasm.github.io/wasm-pack/) site recommends curling into your shell to install, but I prefer using cargo:

```
cargo install wasm-pack
```

Once wasm-pack is installed, you can build & test this package.

### 🛠️ Build packages for web and node

| Command | Purpose | Directory |
| --- | --- | --- |
| `make dev_web` | Create a dev build of the transforms for use in web browsers. | `web` |
| `make build_web` | Create an optimized build of the transforms for use in web browsers. | `web` |
| `make dev_node` | Create a dev build of the transforms for use in nodejs. | `node` |
| `make build_node` | Create an optimized build of the transforms for use in nodejs. | `node` |
| `make clean` | Clean the wasm builds' target directories. | `node` & `web` |
| `make publish` | Clean, build, and publish to npm. **Note:** update the version number in [Cargo.toml](./Cargo.toml) first! | `node` & `web` |

For more information about the commands, see the [Makefile](./Makefile) and [wasm-pack build docs](https://rustwasm.github.io/docs/wasm-pack/commands/build.html).

### 🔬 Running tests

```
wasm-pack test --headless --firefox
wasm-pack test --headless --chrome
wasm-pack test --headless --safari
wasm-pack test --node
```

Leave off `--headless` to run the tests in a live browser.

Also see [wasm-pack test docs](https://rustwasm.github.io/docs/wasm-pack/commands/test.html).