npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, πŸ‘‹, I’m Ryan HefnerΒ  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you πŸ™

Β© 2024 – Pkg Stats / Ryan Hefner

@minar-kotonoha/as-bind

v0.4.0

Published

Isomorphic library to handle passing high-level data structures between AssemblyScript and JavaScript πŸ€πŸš€

Downloads

4

Readme

as-bind

Build Status npm bundle size (minified) npm npm version GitHub

Isomorphic library to handle passing high-level data structures between AssemblyScript and JavaScript. πŸ€πŸš€

Markdown Parser Demo

Asbind Markdown Parser Demo Gif

Table of Contents

Features

  • The library is Isomorphic. Meaning it supports both the Browser, and Node! And has ESM, CommonJS, and IIFE bundles! 🌐
  • Wraps around the AssemblyScript Loader. The loader handles all the heavy-lifting of passing data into WebAssembly linear memory. πŸ’ͺ
  • Wraps around imported JavaScript functions, and exported AssemblyScript functions of the AssemblyScript Wasm Module. This allows high-level data types to be passed directly to exported AssemblyScript functions! 🀯
  • The library works at runtime, so no generated code that you have to maintain and make it play nicely in your environment. πŸƒ
  • Maintains great performance (relative to generating the corresponding JavaScript code), by using Speculative Execution, and caching types passed between functions. πŸ€”
  • Installable from package managers (npm), with a modern JavaScript API syntax. πŸ“¦
  • The library is < 5KB (minified and gzip'd) and tree-shakeable! 🌲
  • This library is currently (as of January, 2020) the wasm-bindgen in the Rust/Wasm ecosystem, for AssemblyScript. πŸ˜€

Installation

You can install as-bind in your project by running the following:

npm install --save as-bind

Quick Start

1. Compiling your Assemblyscript

To enable as-bind for your AssemblyScript Wasm modules, add the as-bind entrypoint when compiling your module:

asc ./node_modules/as-bind/lib/assembly/as-bind.ts your-entryfile.ts [...other cli options...]

For optional testing purposes , let's export an example function we can try in your-entryfile.ts:

export function myExportedFunctionThatTakesAString(value: string): string {
  return "AsBind: " + value;
}

2. In your Javascript

For browser JavaScript. We can do the following:

// If you are using a Javascript bundler, use the ESM bundle with import syntax
import { AsBind } from "as-bind";

// If you are not using a bundler add a <script> tag to your HTML
// Where the `src` points to the iife bundle (as-bind.iife.js), for example: https://unpkg.com/as-bind
// Then, INSTEAD of using the import syntax, do: `const { AsBind } = AsBindIIFE;`

const wasm = fetch("./path-to-my-wasm.wasm");

const asyncTask = async () => {
  const asBindInstance = await AsBind.instantiate(wasm);

  // You can now use your wasm / as-bind instance!
  const response = asBindInstance.exports.myExportedFunctionThatTakesAString(
    "Hello World!"
  );
  console.log(response); // AsBind: Hello World!
};
asyncTask();

For Node JavaScript, we would use the CommonJS bundle by do the following:

const { AsBind } = require("as-bind");
const fs = require("fs");

const wasm = fs.readFileSync("./path-to-my-wasm.wasm");

const asyncTask = async () => {
  const asBindInstance = await AsBind.instantiate(wasm);

  // You can now use your wasm / as-bind instance!
  const response = asBindInstance.exports.myExportedFunctionThatTakesAString(
    "Hello World!"
  );
  console.log(response); // AsBind: Hello World!
};
asyncTask();

Did the quick start not work for you, or you are noticing some weird behavior? Please see the FAQ and Common Issues

Additional Examples

Passing a high-level type to a an exported function, and returning a high-level type

See the Quick Start

Passing a high-level type to an imported function

In this example, we will implement a console.log that we can call from AssemblyScript!

AssemblyScript

Inside of myWasmFileName.ts:

declare function consoleLog(message: string): void;

export function myExportedFunctionThatWillCallConsoleLog(): void {
  consoleLog("Hello from AS!");
}

JavaScript

import { AsBind } from "as-bind";

const wasm = fetch("./path-to-my-wasm.wasm");

const asyncTask = async () => {
  // Instantiate the wasm file, and pass in our importObject
  const asBindInstance = await AsBind.instantiate(wasm, {
    myWasmFileName: {
      consoleLog: message => {
        console.log(message);
      }
    }
  });

  // Should call consoleLog, and log: "Hello from AS!"
  asBindInstance.exports.myExportedFunctionThatWillCallConsoleLog();
};
asyncTask();

Supported Data Types

TL;DR: Currently Numbers, Strings, and Typed Arrays are supported. Returning a high-level data type from an imported JavaScript function, BigInt, and passing AssemblyScript Classes will be coming later.

Note: As discovered in #28, Array<NumberType> is NOT the same as TypedArray, and may not work for your use case. You want to use TypedArray where possible.

| Function & Direction | Number (32-bit Integers and 32-bit / 64-bit Floats) | Strings | Int8Array | Uint8Array | Int16Array | UInt16Array | Int32Array | Uint32Array | Float32Array | Float64Array | AssemblyScript Classes | | ------------------------------------------- | --------------------------------------------------- | ------- | --------- | ---------- | ---------- | ----------- | ---------- | ----------- | ------------ | ------------ | ---------------------- | | Exported AssemblyScript Function Parameters | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | ❌ | | Exported AssemblyScript Function Return | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | ❌ | | Imported JavaScript Function Paramters | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | βœ”οΈ | ❌ | | Imported JavaScript Function Return | βœ”οΈ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |

Supported AssemblyScript Runtime Variants

as-bind only supports AssemblyScript modules compiled with the --runtime full (default), and --runtime stub flags. These should be the only supported modes, because these runtime variants specify that you would like types / objects to be created externally as well as internally. Other runtime variants would mean that you DO NOT want anything externally created for your wasm module.

Please see the AssemblyScript Docs on runtime variants for more information.

Reference API

AsBind

The default exported ESM class of as-bind, also available as import { AsBind } from "as-bind" / const { AsBind } = require('as-bind').

Class Properties

The AsBind class is meant to vaugely act as the WebAssembly Object exposed to JavaScript environments.

version

AsBind.version: string

Value that is the current version of your imported AsBind.

instantiate
AsBind.instantiate: (
  moduleOrBuffer: (
    WebAssembly.Module |
    BufferSource |
    Response |
    PromiseLike<WebAssembly.Module>
  ),
  imports?: WasmImports
) => Promise<AsBindInstance>`

This function is the equivalent to the AssemblyScript Loader instantiate function, which is similar to the WebAssembly.instantiateStreaming function. It essentially takes as its parameters:

  • Any type of object that can be (resolved) and instantied into a WebAssembly instance. Which in our case would be an AsBindInstance.

  • A WebAssembly importObject, which would have all of your imported functions that can be called from within your AssemblyScript module.

instantiateSync
AsBind.instantiateSync: (
  moduleOrBuffer: (
    WebAssembly.Module |
    BufferSource
  ),
  imports?: WasmImports
) => AsBindInstance`

This is a synchronous version of AsBind.instantiate. This does not accept a promise-like as its module, and returns an AsBindInstance instead of a Promise that resolves an AsBindInstance. This is only reccomended for use in testing or development. Please see the Documentation sections for AsBind.instantiate for more information.

Instance Properties

An AsBindInstance is vaugley similar to a WebAssembly instance.

exports

Similar to to WebAssembly.Instance.prototype.exports, this is an object containing all of the exported fields from the WebAssembly module. However, exported functions are bound / wrapped in which they will handle passing the supported high-level data types to the exported AssemblyScript function.

Each exported function has the property: shouldCacheTypes. If you would like to disable type caching (speculative execution) for a particular function, you can do: asBindInstance.exports.myFunction.shouldCacheTypes = false;. Or set to true, to re-enable type caching.

unboundExports

This is essentially the same as the WebAssembly.Instance.prototype.exports, this is an object containing all of the exported fields from the WebAssembly module. These are not bound / wrapped, so you can access the original exported functions.

importObject

Similar to to WebAssembly.instantiateStreaming() importObject, This is the original passed importObject on instantiation, after the importObject functions are bound / wrapped by as-bind.

Each wrapped importObject function has the property: shouldCacheTypes. If you would like to disable type caching (speculative execution) for a particular function, you can do: asBindInstance.importObject.myFunction.shouldCacheTypes = false;. Or set to true, to re-enable type caching.

enableExportFunctionTypeCaching

Calling this method will (re-)enable type caching (speculative execution) for ALL exported functions on the AsBindInstance.

disableExportFunctionTypeCaching

Calling this method will disable type caching (speculative execution) for ALL exported functions on the AsBindInstance.

enableImportFunctionTypeCaching

Calling this method will (re-)enable type caching (speculative execution) for ALL importObject functions on the AsBindInstance.

disableImportFunctionTypeCaching

Calling this method will disable type caching (speculative execution) for ALL importObject functions on the AsBindInstance.

Motivation

This library was inspired by several chats I had with some awesome buddies of mine in the WebAssembly Community:

  • Till Schneidereit and I had a chat about WasmBoy, and about how I had a really good experience writing the emulator, even though I had to do my own memory management. But they helped me realize, building something low level isn't that bad with manual memory management, but building something like a markdown parser would be very tedious since you have to manually write the string back and forth. Which then inspired this library, and its markdown parser demo.

  • While I was building WasmByExample I wanted to start building the "High Level Data Structures" section. I then realized how much work it would be to maintain code for passing data between WebAssembly Linear memory would be for each data type, and how much work it would be to created each individual example. Then, my buddy Ashley Williams helped me realize, if your docs are becoming too complex, it may be a good idea to write a tool. That way you have less docs to write, and users will have an easier time using your stuff!

Thus, this library was made to help AssemblyScript/JavaScript users build awesome things! I also want to give a huge thanks to the AssemblyScript team and communitty for the help they provided me. I'm super appreciative of you all! πŸ˜„πŸŽ‰

Performance

TL;DR This library should be fast, but depending on your project you may want some more careful consideration. πŸ€”

as-bind does all of its data passing at runtime. Meaning this will be slower than a code generated bindings generator, such as something like wasm-bindgen. This is because, as-bind needs to cycle through every supported type on every paremeter or return value for each function, whenever the function is called. However, this is mitigated due to the Speculative execution that the library implements.

Which in this case means, the library by default will assume the type of value being passed to, or returned by a function will not change. Thus, the library will only have to cycle through the params once, cache the types, and then for calls to the functions after this it would be as fast as a code generated solution (in theory). This speculative execution can be turned off as specified in the Reference API.

If your project is doing one-off processing using a high level data type, this project should have a very small impact on performance of your project. However, if you project is doing its processing in a very time constrained loop (such as a game running at 60fps), you may want to be more considerate when choosing this library. The speculative execution should greatly help in the amount of time to pass high level data types, but if your game is already not running as fast as you would like, you may want to avoid this library, or even not using high level data types, for passing memory to your WebAssembly module. However, the library also exposes all original exports under the AsBindInstance.unboundExports as covered in the Reference API, so you could, in theory, still access the non-bound exports without any of the performance overhead if you don't require any of the binding / wrapping that AsBind does for you.

Eventually for the most performant option, we would want to do some JavaScript code generation in the AssemblyScript compiler itself, as part of an as-bindgen project for the most performant data passing.

In the future, these types of high-level data passing tools will not be needed for WebAssembly toolchains, once the WebAssembly Inteface Types proposal lands, and this functionality is handled by the runtime / toolchain.

Projects using as-bind

  • The as-bind example is a Markdown Parser, in which as-bind takes in a string, passes it to a rough markdown parser / compiler written in AssemblyScript, and returns a string. (Live Demo), (Source Code)

  • use-as-bind is a React hook for using as-bind with an as-bind enabled WASM source. It's goal is to provide a simple API for React users to add WASM to their apps. (Live Demo)

If you're project is using as-bind, and you would like to be featured here. Please open a README with links to your project, and if appropriate, explaining how as-bind is being used. 😊

FAQ and Common Issues

I am calling my exports, but it is not returning the types that I am returning? It seems to be returning pointers?

This is probably because you are not adding the as-bind entry file. Please see the Quick Start on how to compile your AssemblyScript module with this entry file. If this still does not work, please take a look at the Supported Types to ensure what type you are trying to pass will work.

Didn't find a solution to your problem? Feel free to open an issue!

Contributing

Contributions are definitely welcome! Feel free to open a PR for small fixes such as typos and things. Larger fixes, or new features should start out as an issue for discussion, in which then a PR should be made. πŸ₯³

This project will also adhere to the AssemblyScript Code of Conduct.

License

MIT. πŸ“