assemblyscript-loader

AssemblyScript Loader

AssemblyScript's loader component to run and work with compiled WebAssembly modules, as a stand-alone module.

Usage

$> npm install assemblyscript-loader

import load from "assemblyscript-loader"; // JS: var load = require("assemblyscript-loader").load;

load("path/to/myModule.wasm", {
  imports: {
    ...
  }
}).then(module => {
  ...
  // i.e. call module.exports.main()
});

Alternatively, when LoadOptions#exports is specified, the respective object is pre-initialized with the (always present) ready promise that is resolved when loading is complete:

// myModule.js (CommonJS)
require("assemblyscript-loader").load("path/to/myModule.wasm", { exports: module.exports });

// otherModule.js (CommonJS)
var myModule = require("./myModule.js");
myModule.ready.then(() => {
  ...
});

API

• load(file: string | Uint8Array | ArrayBuffer, options: LoadOptions): Promise<Module>
  Loads a WebAssembly module either from a file or a buffer and returns a promise for the loaded Module.

• LoadOptions
  Options to set up the environment created by load.

  • memory: WebAssembly.Memory
    Memory instance to import, if applicable.
  • imports: { [key: string]: any }
    Import elements. Usually functions.
  • exports: { [key: string]: any }
    Object to populate with exports. Creates a new object if omitted.

• Module
  Common module interface as returned by load.

  • imports: Imports
    Imported elements. Usually functions.
  • exports: Exports
    Exported elements. Usually functions.
  • memory: Memory
    A reference to the underlying memory instance.
  • log(type: LogType, message: string): void
    An overridable method receiving console outputs.

• Imports
  An object of imported functions.

• Exports
  An object of exported functions (plus the ready promise).

• LogType
  An enum of log types:

  Key	Value
  LOG	0
  INFO	1
  WARN	2
  ERROR	3

• Memory extends WebAssembly.Memory
  The WebAssembly Memory instance populated with additional accessors for more convenient memory access.

  • sbyte / s8: NumberAccessor
    Signed 8-bit integer accessors.
  • byte / u8: NumberAccessor
    Unsigned 8-bit integer accessors.
  • short / s16: NumberAccessor
    Signed 16-bit integer accessors.
  • ushort / u16: NumberAccessor
    Unsigned 16-bit integer accessors.
  • int / s32: NumberAccessor
    Signed 32-bit integer accessors.
  • uint / u32: NumberAccessor
    Unsigned 32-bit integer accessors.
  • long / s64: LongAccessor
    Signed 64-bit integer accessors.
  • ulong / u64: LongAccessor
    Unsigned 64-bit integer accessors.
  • float / f32: NumberAccessor
    32-bit float accessors.
  • double / f64: NumberAccessor
    64-bit float accessors.
  • array: ArrayAccessor
    Array accessors.
  • string: StringAccessor
    String accessors.

• NumberAccessor
  Number memory accessor.

  • get(ptr: number): number
    Gets a value of the underlying type from memory at the specified pointer.
  • set(ptr: number, value: number): void
    Sets a value of the underlying type in memory at the specified pointer.

• LongAccessor
  Long memory accessor. See also: long.js

  • get(ptr: number): Long
    Gets a Long from memory at the specified pointer.
  • set(ptr: number, value: Long): void
    Sets a Long in memory at the specified pointer.

• ArrayAccessor
  Array memory accessor.

  • get(ptr: number): { length: number, base: number }
    Gets an array from memory at the specified pointer and returns its length and element base pointer.
  • create(length: number, elementByteSize: number): { ptr: number, base: number }
    Creates an array in memory and returns its pointer and element base pointer.

• StringAccessor
  String memory accessor.

  • get(ptr: number): string
    Gets a string from memory at the specified pointer.
  • create(value: string): number
    Creates a string in memory and returns its pointer.

• initializeMemory(memoryInstance: WebAssembly.Memory, malloc: Function, memset: Function): Memory
  Just populates a WebAssembly Memory instance with the AssemblyScript-typical accessors.

• xfetch(file: string): Promise<Response>
  Underlying fetch implementation that also works under node.js.

Note that the create methods of array and string accessors require an exported or imported implementation of malloc, memset, free etc. to be present. Also remember that memory is unmanaged here and that free must be called manually to clean up memory, just like in C. Once WebAssembly exposes the garbage collector natively, there will be other options as well.

The long.js dependency can be safely excluded if working with long/ulong values isn't needed. In this case, the implementation will still accept and produce Long-like objects having a low and a high property representing the respective low and high 32-bits.

Building

Clone the GitHub repository and install the development dependencies:

$> git clone https://github.com/AssemblyScript/loader.git
$> cd loader
$> npm install

Afterwards, to build the distribution files to dist/, run:

$> npm run build