README.md

wasi-js

This is a Javascript library for interacting with WASI Modules in node and in the browser.

Features

wasi-js uses the same API as the WASI integration in Node.

However, wasi-js is focused on:

• Bringing WASI to an Isomorphic context (Node.js and the Browser)

• Make it easy to plug in different filesystems (via wasmfs)

• Make code safer using Typescript

• Pure JavaScript implementation (no Native bindings needed)

• Very small

• Easy to plugin support for sleep, blocking read of stdout, and writing to stdout and stderr.

Installation

To install wasi-js, run this command:

npm install wasi-js

Testing

There is currently no test suite directly in this package. However, that doesn't mean that it doesn't get thorough testing. Indeed, it is tested by the other packages of CoWasm that depend on it, including a large number of tests in the cpython test suite (which helped me find many bugs).

Quick Start

This quick start is for node. It's something like this. See cowasm for a nontrivial application that uses wasi-js both in node and the browser. The usage is something like this:

import { WASI } from "wasi-js";
import fs from "fs";
import nodeBindings from "wasi-js/dist/bindings/node";

const wasi = new WASI({
  args: [],
  env: {},
  bindings: {...nodeBindings, fs},
});

const source = await readFile(pathToWasm);
const typedArray = new Uint8Array(source);
const result = await WebAssembly.instantiate(typedArray, wasmOpts);
wasi.start(result.instance);

Set the env variable DEBUG=wasi* to see a log of all wasi system calls; this uses the debug library.

History

This started long ago as a fork of version 0.12.0 of @wasmer/wasi to keep it alive, since the Wasmer company deleted it entirely (replacing it with a rust rewrite with very different goals), and I would like to use it in CoWasm. I added some functionality to better support blocking IO and other features needed mainly in the browser. I also found and fixed some very subtle bugs while trying to get the cPython test suite to work.

There is no real test suite directly of this package. That said, I have tested it quite a bit indirectly via Python test suites.

As mentioned above, this is based on what the wasmer devs wrote, which itself was based on what Gus Caplan wrote. I have also added hooks for implementing blocking IO.

Here's what the WASMER people wrote:

This project is based from the Node implementation made by Gus Caplan
https://github.com/devsnek/node-wasi
However, JavaScript WASI is focused on:
 * Bringing WASI to the Browsers
 * Make easy to plug different filesystems
 * Provide a type-safe api using Typescript
 * Providing multiple output targets to support both browsers and node
 * The API is adapted to the Node-WASI API: https://github.com/nodejs/wasi/blob/wasi/lib/wasi.js

This is the original MIT license below:

Copyright 2019 Gus Caplan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.