assemblyscript-loader
TypeScript icon, indicating that this package has built-in type declarations

0.3.0 • Public • Published

AssemblyScript Loader

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

npm Build Status

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

Dependents (0)

Package Sidebar

Install

npm i assemblyscript-loader

Weekly Downloads

0

Version

0.3.0

License

Apache-2.0

Last publish

Collaborators

  • assemblyscript
  • dcode