@wapc/host
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.3 • Public • Published

    waPC JavaScript Host (Node + Browser)

    This is the JavaScript implementation of the waPC standard for WebAssembly host runtimes. It allows any WebAssembly module to be loaded as a guest and receive requests for invocation as well as to make its own function requests of the host.

    This package defines the protocol for RPC exchange between guest (WebAssembly) modules and the host runtime.

    Who is this for?

    Library developers who want to load waPC-compliant WebAssembly binaries in nodejs or browser environments. The waPC protocol allows a host to execute arbitrary wasm functions without knowing the exported bindings beforehand.

    While waPC does not prescribe a serialization/deserialization format, MessagePack is common recommended unless you need otherwise.

    Installation

    $ npm install @wapc/host

    Usage

    Node

    const { instantiate } = require('@wapc/host');
    const { encode, decode } = require('@msgpack/msgpack');
    const { promises: fs } = require('fs');
    const path = require('path');
    
    async function main() {
      // Read wasm off the local disk as Uint8Array
      buffer = await fs.readFile(path.join(__dirname, 'fixtures', 'rust_echo_string.wasm'));
    
      // Instantiate a WapcHost with the bytes read off disk
      const host = await instantiate(buffer);
    
      // Encode the payload with MessagePack
      const payload = encode({ msg: 'hello world' });
    
      // Invoke the operation in the wasm guest
      const result = await host.invoke('echo', payload);
    
      // Decode the results using MessagePack
      const decoded = decode(result);
    
      // log to the console
      console.log(`Result: ${decoded}`);
    }
    
    main().catch(err => console.error(err));

    Browser

    Browser environments can instantiate from a FetchResponse with waPC.instantiateStreaming(). If the browser does not support streaming wasm then waPC gracefully degrades and waits for the response to complete before instantiating.

    <script src="https://unpkg.com/@msgpack/msgpack@2.5.1/dist.es5+umd/msgpack.min.js"></script>
    <script src="dist/index.bundle.js"></script>
    <script>
      (async () => {
        // Fetch wasm bytes
        response = await fetch('/test/fixtures/rust_echo_string.wasm');
    
        // Instantiate a WapcHost with fetch response object
        const host = await waPC.instantiateStreaming(response);
    
        // Encode the arguments to send to the wasm function (Example using msgpack)
        const payload = MessagePack.encode({ msg: 'hello world' });
    
        // Invoke the "echo" function in the wasm guest
        const result = await host.invoke('echo', payload);
    
        // Decode the results (using msgpack in this example)
        const decoded = MessagePack.decode(result);
      })();
    </script>

    Contributing

    Running tests

    Node unit tests

    $ npm run test:unit

    Browser unit tests

    $ npm run test:browser

    Building

    $ npm run build

    Keywords

    none

    Install

    npm i @wapc/host

    DownloadsWeekly Downloads

    47

    Version

    0.0.3

    License

    ISC

    Unpacked Size

    3.54 MB

    Total Files

    43

    Last publish

    Collaborators

    • pkedy
    • jsoverson
    • wapcbot