or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md memory-management.md

tile.json

AssemblyScript Loader

A convenient loader for AssemblyScript modules that makes working with AssemblyScript modules as convenient as it gets without sacrificing efficiency. It mirrors the relevant parts of the WebAssembly API while also providing utility to allocate and read strings, arrays, and classes.

Deprecation Notice: The loader has been deprecated in AssemblyScript 0.20. While it will likely continue to work, switching to the new static bindings generation is recommended.

Package Information

Package Name: @assemblyscript/loader
Package Type: npm
Language: JavaScript/TypeScript
Installation: npm install @assemblyscript/loader

Core Imports

import loader from "@assemblyscript/loader";

Named imports:

import { instantiate, instantiateSync, instantiateStreaming, demangle } from "@assemblyscript/loader";

For CommonJS:

const loader = require("@assemblyscript/loader");
// or
const { instantiate, instantiateSync, instantiateStreaming, demangle } = require("@assemblyscript/loader");

Browser ESM:

<script type="module" src="https://cdn.jsdelivr.net/npm/@assemblyscript/loader/index.js"></script>

Browser UMD:

<script src="https://cdn.jsdelivr.net/npm/@assemblyscript/loader/umd/index.js"></script>

Basic Usage

import loader from "@assemblyscript/loader";

// Instantiate a WebAssembly module
const { exports } = await loader.instantiate(
  // WebAssembly source (buffer, Response, or Module)
  fetch("optimized.wasm"),
  // Optional imports
  {}
);

// Use string utilities
const strPtr = exports.__newString("Hello, world!");
const result = exports.__getString(strPtr);

// Use array utilities  
const arrayPtr = exports.__newArray(exports.INT32ARRAY_ID, [1, 2, 3, 4, 5]);
const values = exports.__getArray(arrayPtr);

// Memory management
exports.__pin(strPtr);  // Prevent garbage collection
exports.__unpin(strPtr); // Allow garbage collection

Architecture

The @assemblyscript/loader is built around several key components:

Instantiation Functions: Core functions for loading and initializing WebAssembly modules with proper setup
Memory Management Utilities: Runtime interface for allocating, reading, and managing WebAssembly memory objects
Type System Integration: Runtime type information (RTTI) support for dynamic type inference of arrays and objects
Export Demangling: Automatic transformation of mangled AssemblyScript exports into JavaScript-friendly object structures
Cross-Platform Support: Works in both browser and Node.js environments with feature detection

Capabilities

Module Instantiation

Core functions for loading and instantiating AssemblyScript WebAssembly modules with automatic utility injection.

function instantiate<T extends Record<string,unknown>>(
  source: WebAssembly.Module | BufferSource | Response | PromiseLike<WebAssembly.Module | BufferSource | Response>,
  imports?: Imports
): Promise<ResultObject & { exports: ASUtil & T }>;

function instantiateSync<T extends Record<string,unknown>>(
  source: WebAssembly.Module | BufferSource,
  imports?: Imports
): ResultObject & { exports: ASUtil & T }>;

function instantiateStreaming<T extends Record<string,unknown>>(
  source: Response | PromiseLike<Response>,
  imports?: Imports
): Promise<ResultObject & { exports: ASUtil & T }>;

function demangle<T extends Record<string,unknown>>(
  exports: Record<string,unknown>,
  extendedExports?: Record<string,unknown>
): T;

interface ResultObject {
  module: WebAssembly.Module;
  instance: WebAssembly.Instance;
}

interface Imports {
  [key: string]: Record<string,unknown> | undefined;
  env?: {
    memory?: WebAssembly.Memory;
    table?: WebAssembly.Table;
    seed?(): number;
    abort?(msg: number, file: number, line: number, column: number): void;
    trace?(msg: number, numArgs?: number, ...args: number[]): void;
    mark?(): void;
  };
}

Memory Management Utilities

Comprehensive utilities for managing WebAssembly memory, including string and array allocation, reading, and runtime memory management.

interface ASUtil {
  memory?: WebAssembly.Memory;
  table?: WebAssembly.Table;

  // String utilities
  __getString(ptr: number): string;
  __newString(str: string): number;

  // Array utilities (basic)
  __getArray(ptr: number): number[];
  __newArray(id: number, valuesOrCapacity?: Array<number> | ArrayBufferView | number): number;
  __getArrayView(ptr: number): ArrayBufferView;

  // ArrayBuffer utilities
  __getArrayBuffer(ptr: number): ArrayBuffer;
  __newArrayBuffer(buf: ArrayBuffer): number;

  // Function utilities
  __getFunction(ptr: number): ((...args: unknown[]) => unknown) | null;

  // Runtime interface
  __new(size: number, id: number): number;
  __pin(ptr: number): number;
  __unpin(ptr: number): void;
  __collect(incremental?: boolean): void;
}

Memory Management

Types

interface ResultObject {
  module: WebAssembly.Module;
  instance: WebAssembly.Instance;
}

interface Imports {
  [key: string]: Record<string,unknown> | undefined;
  env?: {
    memory?: WebAssembly.Memory;
    table?: WebAssembly.Table;
    seed?(): number;
    abort?(msg: number, file: number, line: number, column: number): void;
    trace?(msg: number, numArgs?: number, ...args: number[]): void;
    mark?(): void;
  };
}

interface ASUtil {
  memory?: WebAssembly.Memory;
  table?: WebAssembly.Table;
  // ... (complete interface defined in Memory Management capability)
}

// Default export object
interface LoaderModule {
  instantiate: typeof instantiate;
  instantiateSync: typeof instantiateSync;
  instantiateStreaming: typeof instantiateStreaming;
  demangle: typeof demangle;
}