Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/drsensor/rs-jest
Jest preprocessor/transformer for Rust
https://github.com/drsensor/rs-jest
jest jest-transform my-experiment rust webassembly
Last synced: 2 months ago
JSON representation
Jest preprocessor/transformer for Rust
- Host: GitHub
- URL: https://github.com/drsensor/rs-jest
- Owner: DrSensor
- License: mit
- Created: 2018-08-29T12:31:22.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-07T23:53:16.000Z (about 2 years ago)
- Last Synced: 2024-11-02T03:03:31.683Z (2 months ago)
- Topics: jest, jest-transform, my-experiment, rust, webassembly
- Language: TypeScript
- Size: 649 KB
- Stars: 17
- Watchers: 2
- Forks: 1
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
[![npm][npm]][npm-url]
[![size][size]][size-url]
[![npm][npm-download]][npm-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
# rs-jest
tl;dr -- see [examples](#examples)
This is a jest transformer that loads Rust code so it can be interop with Javascript base project. Currently, the Rust code will be compiled as:
- [x] WebAssembly module/instance
- [ ] Node.js addon/ffi
## Requirements
- Node v8 or later
- Jest v23 or later
-
Rust v1.28.0 with wasm32-uknown-unknown installed```console
rustup default 1.28.0
rustup target add wasm32-unknown-unknown
```
## Getting Started
To begin, you'll need to install `rs-jest`:
```console
npm install rs-jest --save-dev
```
Then configure Jest to make `rs-jest` to transform the Rust (`*.rs`) file. For example:
jest.config.js
```js
module.exports = {
transform: {
"^.+\\.rs$": "rs-jest"
}
};
```
or if you prefer to put the config in
package.json
```json
"jest": {
"transform": {
"^.+\\.rs$": "rs-jest"
}
}
```
quick usage
lib.rs
```rust
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
```
index.js
```js
import wasm from "lib.rs";
export async function increment(a) {
const { instance } = await wasm;
return instance.exports.add(1, a);
}
```
And run `jest` via your preferred method.
## Options
Pretty much like [ts-jest][], you can configure `rs-jest` by using global variables under the `"rs-jest"` key:
export
How wasm code would be exported. This options is identical with [option `export` in webassembly-loader][webassembly-loader]. (see [examples](#examples))
```json
{
"globals": {
"rs-jest": {
"export": "instance"
}
},
"transform": {
"^.+\\.rs$": "rs-jest"
}
}
```
target
- Type: `String`
- Default: `wasm32-unknown-unknown`
- Expected value: see [supported platform](https://forge.rust-lang.org/platform-support.html)
The Rust target to use. Currently it **only support [wasm related target](https://kripken.github.io/blog/binaryen/2018/04/18/rust-emscripten.html)**
```json
{
"globals": {
"rs-jest": {
"target": "wasm32-unknown-emscripten"
}
},
"transform": {
"^.+\\.rs$": "rs-jest"
}
}
```
release
- Type: `Boolean`
- Default: `true`
Whether to compile the Rust code in debug or release mode.
```json
{
"globals": {
"rs-jest": {
"release": false
}
},
"transform": {
"^.+\\.rs$": "rs-jest"
}
}
```
## Examples
See the test cases and example projects in [fixtures](./test/fixtures) and [examples](./examples/) for more insight.
The exported module are pretty much like rollup-plugin-rust so it can be used alongside with it
### Given this Rust code
lib.rs
```rust
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
```
Cargo.toml
```toml
[package]
name = "adder"
version = "0.1.0"
authors = ["Full Name "]
[lib]
crate-type = ["cdylib"]
path = "lib.rs"
```
### With options
#### `{export: 'buffer'}`
```js
import wasmCode from "./lib.rs";
WebAssembly.compile(wasmCode).then(module => {
const instance = new WebAssembly.Instance(module);
console(instance.exports.add(1, 2)); // 3
});
```
---
#### `{export: 'module'}`
```js
import wasmModule from "./lib.rs";
const instance = new WebAssembly.Instance(wasmModule);
console(instance.exports.add(1, 2)); // 3
```
---
#### `{export: 'instance'}`
```js
import wasm from "./lib.rs";
console(wasm.exports.add(1, 2)); // 3
```
---
#### `{export: 'async'}`
```rust
extern {
fn hook(c: i32);
}
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
hook(a + b)
}
```
```js
import wasmInstantiate from "./lib.rs";
wasmInstantiate(importObject | undefined).then(({ instance, module }) => {
console(instance.exports.add(1, 2)); // 3
// create different instance, extra will be called in different environment
const differentInstance = new WebAssembly.Instance(module, {
env: {
hook: result => result * 2
}
});
console(differentInstance.exports.add(1, 2)); // 6
});
```
---
#### `{export: 'async-instance'}`
```js
import wasmInstantiate from "./lib.rs";
wasmInstantiate(importObject | undefined).then(instance => {
console(instance.exports.add(1, 2)); // 3
});
```
---
#### `{export: 'async-module'}`
```js
import wasmInstantiate from "./lib.rs";
wasmCompile(importObject | undefined).then(module => {
const differentInstance = new WebAssembly.Instance(module);
console(differentInstance.exports.add(1, 2)); // 3
});
```
---
## You may also want to look at
- [rollup-plugin-rust](https://github.com/DrSensor/rollup-plugin-rust)
- [webassembly-loader](https://github.com/DrSensor/webassembly-loader) + [rust-native-wasm-loader](https://github.com/dflemstr/rust-native-wasm-loader)
## Who use this?
- [example-stencil-rust](https://github.com/DrSensor/example-stencil-rust)
- [add yours 😉]
## Contributing
- [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for how you can make contribution
- [HACKING.md](./.github/HACKING.md) for technical details
## Credits
- [typescript-library-starter](https://github.com/alexjoverm/typescript-library-starter)
- [webpack-defaults](https://github.com/webpack-contrib/webpack-defaults)
---
## License
[](https://app.fossa.io/projects/git%2Bgithub.com%2FDrSensor%2Frs-jest?ref=badge_large)
[ts-jest]: https://github.com/kulshekhar/ts-jest/
[webassembly-loader]: https://github.com/DrSensor/webassembly-loader#export
[npm]: https://img.shields.io/npm/v/rs-jest.svg
[npm-url]: https://npmjs.com/package/rs-jest
[npm-download]: https://img.shields.io/npm/dm/rs-jest.svg
[deps]: https://david-dm.org/DrSensor/rs-jest.svg
[deps-url]: https://david-dm.org/DrSensor/rs-jest
[tests]: https://img.shields.io/circleci/project/github/DrSensor/rs-jest.svg
[tests-url]: https://circleci.com/gh/DrSensor/rs-jest
[cover]: https://codecov.io/gh/DrSensor/rs-jest/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/DrSensor/rs-jest
[size]: https://packagephobia.now.sh/badge?p=rs-jest
[size-url]: https://packagephobia.now.sh/result?p=rs-jest