File: src/interoperability.md Copy Chapter

Interoperability

How to talk to AssemblyScript from C or other languages.

Strings Copy Chapter

Strings in AssemblyScript are stored in WTF-16 encoding, closely matching JavaScript and its string APIs. When embedding AssemblyScript into a C or Rust environment, conversion between WTF-16 and UTF-8 is typically necessary (API).

Details to keep in mind: In UTF-16, certain Unicode code points are represented by two UTF-16 code units called surrogate pairs. However, just like in JavaScript, strings are not sanitized so lone surrogates can appear in a string, which are technically ill-formed UTF-16. This is done to mimic JavaScript as closely as possible, and avoids string re-encoding when calling JavaScript APIs from WebAssembly.

We hope that future WebAssembly features will be designed with both C/Rust and JS/WebAPIs in mind without penalizing the respective other. (1, 2)

Class layout Copy Chapter

Layout of objects in memory resembles that of non-packed C structs, and @unmanaged classes (not tracked by GC, essentially C structs) can be used to describe them:

struct Foo {
  uint32_t bar;
  uint16_t baz;
  uint64_t qux;
}

@unmanaged class Foo {
  bar: u32; // aligned to 4 bytes
  baz: u16; // aligned to 2 bytes
  qux: u64; // aligned to 8 bytes
}

offsetof<Foo>("bar") == 0
offsetof<Foo>("baz") == 4
offsetof<Foo>("qux") == 8
offsetof<Foo>() == 16

var foo = changetype<Foo>(ptrToFoo)
foo.bar // -> i32.load(ptrToFoo, 0)
foo.baz // -> i32.load16_u(ptrToFoo, 4)
foo.qux // -> i64.load(ptrToFoo, 8)

More complex structures usually require manual offset calculation, mostly for the reason that it is not feasible to implement something more specific into AssemblyScript as it does not use such structures on its own:

struct Foo {
  int32_t bar;
  uint32_t baz[10];
}

@unmanaged class Foo {
  bar: i32
  getBaz(i: i32): u32 {
    return load<u32>(
      changetype<usize>(this) + (<usize>i << alignof<u32>()),
      4 // or use offsetof/sizeof to calculate the base offset plus alignment
    )
  }
}

Calling convention Copy Chapter

Exported functions will properly wrap return values, but functions not visible externally do not guarantee proper wrapping.

export function getU8(): u8 {
  return someU8 // will wrap to someU8 & 0xff
}

On the other hand, calling any AssemblyScript function does not require wrapping of arguments.

Optional arguments Copy Chapter

If a function exported from AssemblyScript accepts optional arguments, the exports.__setArgumentsLength(numArguments) helper must be called with the number of actual arguments (while zeroing all the others) to inform the varargs stub to fill in the default values of omitted arguments. The loader does this automatically.

Garbage collection Copy Chapter

Also see the dedicated page on garbage collection.

File: src/introduction.md Copy Chapter

sidebarDepth: 0 Copy Chapter

Introduction

AssemblyScript compiles a strict variant of TypeScript (a typed superset of JavaScript) to WebAssembly using Binaryen, looking like:

export function fib(n: i32): i32 {
  var a = 0, b = 1
  if (n > 0) {
    while (--n) {
      let t = a + b
      a = b
      b = t
    }
    return b
  }
  return a
}

asc fib.ts -b fib.wasm -O3

Its architecture differs from a JavaScript VM in that it compiles a program ahead of time, quite similar to your typical C compiler. One can think of it as TypeScript syntax on top of WebAssembly instructions, statically compiled, to produce lean and mean WebAssembly binaries.

In a nutshell Copy Chapter

On top of WebAssembly types, AssemblyScript not only provides low-level built-ins to access WebAssembly features directly, making it suitable as a thin layer on top of Wasm, but also comes with its own JavaScript-like standard library and a relatively small memory management and garbage collection runtime, making it suitable as a general purpose higher-level language for WebAssembly today.

For example, on the lowest level, memory can be accessed using the load<T>(offset) and store<T>(offset, value) built-ins that compile to WebAssembly instructions directly

store<i32>(8, load<i32>(0) + load<i32>(4))

while the standard library provides higher-level implementations of Array, ArrayBuffer, DataView, Math (double and single precision), Uint8Array, String, Map, Set etc.:

var view = new Int32Array(12)
view[2] = view[0] + view[1]

It is worth to note, however, that AssemblyScript still has its quirks, and we are patiently waiting for future WebAssembly features (marked as 🦄 throughout the documentation) to become available for us to use.

Sounds appealing to you? Read on!

File: src/loader.md Copy Chapter

sidebarDepth: 2 Copy Chapter

Loader

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

import loader from "@assemblyscript/loader"; // or require
loader.instantiate(
  // Binary to instantiate
  fetch("optimized.wasm"), // or fs.readFileSync
                           // or fs.promises.readFile
                           // or just a buffer
  // Additional imports
  { ... }
).then(({ exports }) => {
  ...
})

The loader basically instantiates the module using WebAssembly APIs, but also adds additional utility to it while evaluating export names and making a nice object structure of them. For example, if one exports an entire class Foo from the module, there will be an exports.Foo constructor etc. available when using the loader.

::: tip NOTE
Allocating objects or invoking the GC externally requires compiling with --exportRuntime. See: Garbage collection.
:::

Installation Copy Chapter

For each version of the AssemblyScript compiler, there is a standalone version of the loader that can be installed from npm:

npm install --save @assemblyscript/loader

On the web:

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

::: tip
If you need a specific version of the loader, append the respective version number as usual.
:::

Usage Copy Chapter

One task the loader does not perform is to implicitly translate between WebAssembly pointers and JavaScript objects, and that's where the mixed in utility comes into play. For example, if one has

// AssemblyScript
export function concat(a: string, b: string): string {
  return a + b
}

and then wants to call concat externally, the string arguments cannot just be JavaScript strings but must first be allocated in the module's memory with their lifetime tracked, like so:

// JavaScript
const { concat } = myModule.exports
const { __newString, __getString } = myModule.exports

function doConcat(aStr, bStr) {
  let aPtr = __newString(aStr)
  let bPtr = __newString(bStr)
  let cPtr = concat(aPtr, bPtr)
  let cStr = __getString(cPtr)
  return cStr
}

console.log(doConcat("Hello ", "world!"))

Creating arrays Copy Section

Arrays (or more advanced classes for that matter) require a bit more cooperation because we need to know their value type in order to work with them properly. To achieve this, every class has a unique id internally, and a chunk of runtime type information (RTTI) is shipped with the module to evaluate class types. Here's an example of working with an Int32Array:

// AssemblyScript
export function sum(arr: Int32Array): i32 {
  let sum = 0
  for (let i = 0, k = arr.length; i < k; ++i) {
    sum += unchecked(arr[i])
  }
  return sum
}
export const Int32Array_ID = idof<Int32Array>()

// JavaScript
const { sum, Int32Array_ID } = myModule.exports
const { __newArray } = myModule.exports

function doSum(values) {
  const arrPtr = __newArray(Int32Array_ID, values)
  return sum(arrPtr)
}

console.log(doSum([1, 2, 3]))

This works with all kinds of arrays, except that ids are different and values are interpreted differently, of course.

Reading arrays Copy Section

If one is instead interested in the values of an array being returned by the module, there are two approaches to this. Let's say we have the following module:

// AssemblyScript
export function getRandomArray(len: i32): Int32Array {
  const arr = new Int32Array(len)
  // fill with random values
  return arr
}

The first is, obviously, to read the array's values from the module's memory by essentially copying them to a JS array

// JavaScript
const { getRandomArray } = myModule.exports
const { __getArray } = myModule.exports

function doGetRandomArray(len) {
  const arrPtr = getRandomArray(len)
  const values = __getArray(arrPtr)
  return values
}

console.log(doGetRandomArray(10))

which is always safe, while the second is to create a live view on the array, enabling two-way modification of its values:

// JavaScript
const { getRandomArray } = myModule.exports
const { __getArrayView, __pin, __unpin } = myModule.exports

function doGetRandomArrayView(len) {
  const arrPtr = __pin(getRandomArray(len)) // pin if necessary
  const view = __getArrayView(arrPtr)
  return { ptr, view }
}

const randomArray = doGetRandomArrayView(10)
console.log(randomArray.view)
__unpin(randomArray.ptr) // unpin if necessary

The latter variant can be more efficient (and useful) but is a little dangerous because the view may become detached from the module's memory when memory automatically grows. Also, the viewed array can grow automatically when pushed to, with the view then referencing random memory. Pushing to an array can be avoided quite easily, yet it is notoriously hard to predict when module memory grows - but one can try to set a sufficiently large size of --initialMemory or defensively trigger a sufficiently large dynamic allocation being freed immediately before dealing with potentially problematic views.

Custom classes Copy Section

As mentioned earlier, the loader understands how to make a nice object structure of a module's exports, and it is possible to utilize it to work with classes in a more natural way. For example, when calling the following function externally

// AssemblyScript
export class Foo {
  constructor(public str: string) {}
  getString(): string {
    return this.str
  }
}

export function getFoo(): Foo { // this one
  return new Foo("Hello world!")
}

one can wrap the received pointer in a myModule.exports.Foo instance:

// JavaScript
const { Foo, getFoo } = myModule.exports
const { __getString, __pin, __unpin } = myModule.exports

const fooPtr = __pin(getFoo()) // pin if necessary
const foo = Foo.wrap(fooPtr)
const strPtr = foo.getString()
console.log(__getString(strPtr))
__unpin(fooPtr) // unpin if necessary

API Copy Chapter

For reference, here comes the full API provided by the loader.

::: tip
Copying from and extending the examples above is typically sufficient.
:::

Static members Copy Section

• ts Copy

  function instantiate<T>(
    moduleOrBuffer: WasmInstantiable,
    imports?: WasmImports
  ): Promise<ASUtil & T>

  Asynchronously instantiates an AssemblyScript module from anything that can be instantiated.

• ts Copy

  function instantiateSync<T>(
    moduleOrBuffer: WasmInstantiable,
    imports?: WasmImports
  ): ASUtil & T

  Synchronously instantiates an AssemblyScript module from a WebAssembly.Module or binary buffer. Not recommended.

• ts Copy

  function instantiateStreaming<T>(
    response: Response | PromiseLike<Response>,
    imports?: WasmImports
  ): Promise<ASUtil & T>

  Asynchronously instantiates an AssemblyScript module from a response, i.e. as obtained by fetch.

• ts Copy

  function demangle<T>(
    exports: WasmExports,
    baseModule?: Object
  ): T

  Demangles an AssemblyScript module's exports to a friendly object structure. You usually don't have to call this manually as instantiation does this implicitly.

Note that T above can either be omitted if the shape of the module is unknown, or can reference a .d.ts (i.e. typeof MyModule) as produced by the compiler with the -d option.

Module instance utility Copy Section

The following utility functions are mixed into the module's exports.

• ts Copy

  function __newString(str: string): number

  Allocates a new string in the module's memory and returns a pointer to it. Requires --exportRuntime for access to __new.

• ts Copy

  function __newArray(id: number, values: number[]): number

  Allocates a new array in the module's memory and returns a pointer to it. The id is the unique runtime id of the respective array class. If you are using Int32Array for example, the best way to know the id is an export const Int32Array_ID = idof(). Requires --exportRuntime for access to __new.

• ts Copy

  function __getString(ptr: number): string

  Copies a string's value from the module's memory to a JavaScript string. ptr must not be zero.

• ts Copy

  function __getArrayBuffer(ptr: number): ArrayBuffer

  Copies an ArrayBuffer's value from the module's memory to a JavaScript buffer. ptr must not be zero.

• ts Copy

  function __getArray(ptr: number): number[]

  Copies an array's values from the module's memory to a JavaScript array. Infers the array type from RTTI. ptr must not be zero.

• ts Copy

  function __getArrayView(ptr: number): TypedArray

  Gets a live view on the values of an array in the module's memory. Infers the array type from RTTI. ptr must not be zero.

  This differs from __getArray in that the data isn't copied but remains live in both directions. That's faster but also unsafe because if the array grows or becomes garbage collected, the view will no longer represent the correct memory region and modifying its values in this state will most likely corrupt memory or otherwise explode. Use, but use with care.

• ts Copy

  function __getInt8ArrayView(ptr: number): Int8Array
  function __getUint8ArrayView(ptr: number): Uint8Array
  function __getUint8ClampedArrayView(ptr: number): Uint8ClampedArray
  function __getInt16ArrayView(ptr: number): Int16Array
  function __getUint16ArrayView(ptr: number): Uint16Array
  function __getInt32ArrayView(ptr: number): Int32Array
  function __getUint32ArrayView(ptr: number): Uint32Array
  function __getInt64ArrayView(ptr: number): BigInt64Array
  function __getUint64ArrayView(ptr: number): BigUint64Array
  function __getFloat32ArrayView(ptr: number): Float32Array
  function __getFloat64ArrayView(ptr: number): Float64Array

  Slightly more efficient variants of __getArrayView where the type of the array is know beforehand. Doesn't try to infer the type.

Module instance runtime interface Copy Section

When compiling with --exportRuntime, the loader will expose the runtime interface (__new, __pin, __unpin, __collect) as well. See: Garbage collection

Convenience vs. efficiency Copy Chapter

Making the loader's API any more convenient has its tradeoffs. One would either have to include extended type information with the module itself or generate an additional JavaScript file of glue code that does (and hides) all the lifting. As such, one can consider the loader as a small and efficient building block that can do it all, yet does not sacrifice efficiency. If that's not exactly what you are looking for, take a look at more convenient tools below. Just remember that these have tradeoffs.

More convenient tools Copy Section

• as-bind is a library, built on top of the loader, to make passing high-level data structures between AssemblyScript and JavaScript more convenient.

Advanced usage Copy Chapter

Direct memory access Copy Section

All of the above can be mixed with direct memory accesses on myModule.exports.memory.buffer, for instance by adhering to class layout.

TypeScript definitions Copy Section

The compiler is able to emit definitions using the -d command line option that are compatible with modules demangled by the loader, and these can be used for proper typings in development:

// TypeScript
import MyModule from "myModule"; // pointing at the generated d.ts

loader.instantiate<typeof MyModule>(
  fetch("myModule.wasm"),
  { ... }
).then(({ exports }) => {
  ...
})

File: src/memory.md Copy Chapter

Memory

Similar to other languages that use linear memory, and until the GC 🦄 proposal becomes available, all data in AssemblyScript is stored at a specific offset in linear memory so other parts of the program can read and modify it.

Importing memory Copy Chapter

The WebAssembly.Memory instance used by your program can be imported from the host by using the --importMemory command line option. The module will then expect an import named memory within the env module to be provided upon instantiation.

An imported memory becomes the singleton memory of the module and can be accessed in the same way as a non-imported memory. Note that if the module defines data segments, it will place the data into the imported memory upon instantiation of the module, which must be taken into account when pre-populating the memory externally (e.g. when utilizing --memoryBase to reserve some space as described in Memory Regions below).

Exporting memory Copy Chapter

A module exports its memory as memory by default, unless disabled with --noExportMemory.

Accessing memory during instantiation Copy Chapter

AssemblyScript runs any top-level statements as part of the emitted WebAssembly module's implicit start function by default. Since the implicit start function executes immediately upon instantiation, this leads to a special case because control flow has not yet yielded back to the host, so the module's exported memory only becomes available externally after the implicit start function completes. The implicit start function may however already trigger external code that requires to read from memory, like when printing a string to console.

There are two solutions to this:

1. Exporting an explicit start function

   The --explicitStart command line argument can be used to force exporting the start function as _start instead of making it the module's implicit start function. When doing so it is important to call exports._start() once before calling any other exports to properly initialize the module first.

2. Preparing memory pre-instantiation and importing it

   An alternative is to create the WebAssembly.Memory object before instantiating the module, and using --importMemory to import it. This way around the memory is already known when the implicit start function executes.

Memory regions Copy Chapter

Internally, there are two regions of memory the compiler is aware of:

Static memory Copy Section

Memory starts with static data, like strings and arrays (of constant values) the compiler encountered while translating the program. Unlike in other languages, there is no concept of a stack in AssemblyScript and it instead relies on WebAssembly's execution stack exclusively.

A custom region of memory can be reserved using the --memoryBase option. For example, if one needs an image buffer of exactly N bytes, instead of allocating it one could reserve that space, telling the compiler to place its own static data afterwards, partitioning memory in this order:

Dynamic memory Copy Section

Dynamic memory, commonly known as the heap, is managed by the garbage collector, at runtime. When space for a new object is requested by the program, the runtime's memory manager reserves a suitable region and returns a pointer to it to the program. Once an object is not needed anymore and becomes unreachable, the garbage collector returns the object's memory to the memory manager for reuse.

The memory manager guarantees an alignment of 16 bytes, so an ArrayBuffer, which can be the backing buffer of multiple views, always fits up to v128 values with natural alignment.

Internals Copy Chapter

WebAssembly is specified to use little-endian and as a result, so is AssemblyScript.

Objects in AssemblyScript have a common hidden header used by the runtime to keep track of them. The header includes information about the block used by the memory manager, state information used by the garbage collector, a unique id per concrete class and the data's actual size. The length of a String (id = 1) is computed from that size for example. The header is "hidden" in that the reference to an object points right after it, at the first byte of the object's actual data.

Common header layout

In Wasm32, the header is aligned to 16 bytes right after mmInfo and rtSize, with 16 bytes of managed information in between. The object's payload starts at 16 bytes alignment again.

The most basic objects using the common header are ArrayBuffer and String. These do not have any fields but are just data:

ArrayBuffer layout

String layout

Collections Copy Section

Collections like Array, Map and Set use one or multiple ArrayBuffers to store their data, but their backing buffers are only exposed for typed arrays, as it is the case in JavaScript. This is because collections can grow automatically, which would otherwise lead to no longer valid references to buffers sticking around.

ArrayBufferView layout

This is not an actual class but a helper to simplify the implementation of the typed array views. Each typed array view like Uint8Array is like a subclass of ArrayBufferView with a static value type attached.

Array layout

The layouts of Set and Map are a bit more sophisticated and therefore not mentioned here, but feel free to take a look at their sources.

File: src/peculiarities.md Copy Chapter

Peculiarities

Special features that exist for internal implementation purposes or are otherwise nice to have.

Annotations Copy Chapter

Decorators work more like actual compiler annotations in AssemblyScript.

Custom decorators can be given meaning by using a transform.

Operator overloads Copy Chapter

Operator overloads can only be used on class methods. The respective argument types must match the class type.

Binary operations Copy Section

@operator(OP)
static __op(left: T, right :T): T { ... }

@operator(OP)
__op(right: T): T  { ... }

The === operation cannot be overloaded (is identity equality).

Unary prefix operations Copy Section

@operator.prefix(OP)
static __op(self: T): T { ... }

@operator.prefix(OP)
__op(): T { ... }

::: tip
Note that increment and decrement overloads can have slightly different semantics. If the overload is declared as an instance method, on ++a the compiler does emit code that reassigns the resulting value to a while if the overload is declared static, the overload behaves like any other overload, skipping the otherwise implicit assignment.
:::

Unary postfix operations Copy Section

@operator.postfix(OP)
static __op(self: T): T { ... }

@operator.postfix(OP)
__op(): T { ... }

::: tip
Overloaded postfix operations do not preserve the original value automatically.
:::

Range limits Copy Chapter

The following range limits are present as global constants for convenience:

• ts Copy

  const i8.MIN_VALUE: i8 = -128
  const i8.MAX_VALUE: i8 = 127

• ts Copy

  const i16.MIN_VALUE: i16 = -32768
  const i16.MAX_VALUE: i16 = 32767

• ts Copy

  const i32.MIN_VALUE: i32 = -2147483648
  const i32.MAX_VALUE: i32 = 2147483647

• ts Copy

  const i64.MIN_VALUE: i64 = -9223372036854775808
  const i64.MAX_VALUE: i64 = 9223372036854775807

• ts Copy

  const isize.MIN_VALUE: isize // WASM32: i32.MIN_VALUE, WASM64: i64.MIN_VALUE
  const isize.MAX_VALUE: isize // WASM32: i32.MAX_VALUE, WASM64: i64.MAX_VALUE

• ts Copy

  const u8.MIN_VALUE: u8 = 0
  const u8.MAX_VALUE: u8 = 255

• ts Copy

  const u16.MIN_VALUE: u16 = 0
  const u16.MAX_VALUE: u16 = 65535

• ts Copy

  const u32.MIN_VALUE: u32 = 0
  const u32.MAX_VALUE: u32 = 4294967295

• ts Copy

  const u64.MIN_VALUE: u64 = 0
  const u64.MAX_VALUE: u64 = 18446744073709551615

• ts Copy

  const usize.MIN_VALUE: usize = 0
  const usize.MAX_VALUE: usize // WASM32: u32.MAX_VALUE, WASM64: u64.MAX_VALUE

• ts Copy

  const bool.MIN_VALUE: bool = 0
  const bool.MAX_VALUE: bool = 1

• ts Copy

  const f32.MIN_VALUE: f32 = -3.40282347e+38
  const f32.MAX_VALUE: f32 = 3.40282347e+38
  const f32.MIN_SAFE_INTEGER: f32 = -16777215
  const f32.MAX_SAFE_INTEGER: f32 = 16777215
  const f32.EPSILON: f32 = 1.19209290e-07

• ts Copy

  const f64.MIN_VALUE: f64 = -1.7976931348623157e+308
  const f64.MAX_VALUE: f64 = 1.7976931348623157e+308
  const f64.MIN_SAFE_INTEGER: f64 = -9007199254740991
  const f64.MAX_SAFE_INTEGER: f64 = 9007199254740991
  const f64.EPSILON: f64 = 2.2204460492503131e-16

Tree-shaking Copy Chapter

Module-level Copy Section

The compiler only compiles elements reachable from the entry file and ignores everything that remains unused. This is very similar to a JavaScript VM's behavior when running a JavaScript file, but unlike in TypeScript it also affects checking of types. Helps to reduce compilation times and binary sizes significantly.

Branch-level Copy Section

In addition to module-level tree-shaking, the compiler ignores branches that it can prove won't be taken. Works with constants, built-ins that compile to a constant, expressions that can be precomputed to a constant, plus the following globals to detect specific compiler flags or features:

• ts Copy

  const ASC_TARGET: i32

  Indicates the compilation target. Possible values are 0 = JS (portable), 1 = WASM32, 2 = WASM64.

• ts Copy

  const ASC_NO_ASSERT: bool

  Whether --noAssert has been set.

• ts Copy

  const ASC_MEMORY_BASE: usize

  The value of --memoryBase.

• ts Copy

  const ASC_OPTIMIZE_LEVEL: i32

  The value of --optimizeLevel. Possible values are 0, 1, 2 and 3.

• ts Copy

  const ASC_SHRINK_LEVEL: i32

  The value of --shrinkLevel. Possible values are 0, 1 and 2.

• ts Copy

  const ASC_LOW_MEMORY_LIMIT: i32

  The value of --lowMemoryLimit.

• ts Copy

  const ASC_EXPORT_RUNTIME: i32

  Whether --exportRuntime has been set.

• ts Copy

  const ASC_FEATURE_SIGN_EXTENSION: bool
  const ASC_FEATURE_MUTABLE_GLOBALS: bool
  const ASC_FEATURE_NONTRAPPING_F2I: bool
  const ASC_FEATURE_BULK_MEMORY: bool
  const ASC_FEATURE_SIMD: bool
  const ASC_FEATURE_THREADS: bool
  const ASC_FEATURE_EXCEPTION_HANDLING: bool
  const ASC_FEATURE_TAIL_CALLS: bool
  const ASC_FEATURE_REFERENCE_TYPES: bool
  const ASC_FEATURE_MULTI_VALUE: bool
  const ASC_FEATURE_GC: bool
  const ASC_FEATURE_MEMORY64: bool

  Whether the respective feature is enabled.

  For example, if a library supports SIMD but also wants to provide a fallback when being compiled without SIMD support:

  ts Copy

  if (ASC_FEATURE_SIMD) {
    // compute with SIMD operations
  } else {
    // fallback without SIMD operations
  }

• ts Copy

  const ASC_WASI: i32

  A constant only being defined when WASI bindings are used via import "wasi". Can be checked with isDefined(ASC_WASI).

File: src/portability.md Copy Chapter

Portability

With AssemblyScript using a stricter variant of TypeScript's syntax with a few semantic differences, there comes the opportunity to compile the same code to JavaScript with tsc and WebAssembly with asc. The AssemblyScript compiler itself is portable code.

Portable Stdlib Copy Chapter

Besides the full standard library, AssemblyScript provides a portable variant of the functionality that is present in both JavaScript and WebAssembly. In addition to that, the portable library lifts some of the functionality that is only available with asc to JavaScript, like the portable conversions mentioned below.

To use the portable library, add the following somewhere along your build step so the portable features are present in the environment

require("assemblyscript/std/portable")

and extend assemblyscript/std/portable.json instead of assemblyscript/std/assembly.json within your tsconfig.json. The AssemblyScript compiler itself is an example of how this can be done.

::: tip
The portable standard library is still pretty much a work in progress and we are extending it as we go while working on the compiler. If you need something specific, feel free to improve its definitions and feature set.
:::

Differences Copy Chapter

There are a few semantics differences that must be taken care of.

Conversions Copy Section

While asc understands the meaning of

// non-portable
let someFloat: f32 = 1.5
let someInt: i32 = <i32>someFloat

and then inserts the correct conversion steps, tsc does not because all numeric types are just aliases of number. Hence, when targeting JavaScript with tsc, the above will result in

var someFloat = 1.5
var someInt = someFloat

which is obviously wrong. To account for this, portable conversions can be used, resulting in actually portable code. For example

// portable
let someFloat: f32 = 1.5
let someInt: i32 = i32(someFloat)

will essentially result in

var someFloat = 1.5
var someInt = someFloat | 0

which is correct. The best way of dealing with this is asking yourself the question: What would this code do when compiled to JavaScript?

Overflows Copy Section

Likewise, again because asc knows the meaning but tsc does not, overflows must be handled explicitly:

// non-portable
let someU8: u8 = 255
let someOtherU8: u8 = someU8 + 1

// portable
let someU8: u8 = 255
let someOtherU8: u8 = u8(someU8 + 1)

essentially resulting in

let someU8 = 255
let someOtherU8 = (someU8 + 1) & 0xff

API features Copy Section

In JavaScript, some parts of the standard library function a little more loosely than how they would when compiling to WebAssembly. While the portable definitions try to take care of this, one example where this can happen is Map#get returning undefined when a key cannot be found in JavaScript, while resulting in an abort in WebAssembly, where it is necessary to first check that the key exists using Map#has. The best way of dealing with this is asking yourself the question: What would this code do when compiled to WebAssembly?

Limitations Copy Chapter

In JavaScript, all numeric values are IEEE754 doubles that cannot represent the full range of values fitting in a 64-bit integer (max. safe integer is 2^53 - 1). Hence i64 and u64 are not portable and not present in std/portable. There are several ways to deal with this. One is to use an i64 polyfill like in this example.

Other than that, portable code (JavaScript) does not have a concept of memory, so there are no load and store implementations. Technically this can be polyfilled in various ways, but no default is provided since actual implementations are expected to be relatively specific (for instance: the portable compiler accesses Binaryen's memory).

File: src/quick-start.md Copy Chapter

sidebarDepth: 0 Copy Chapter

Quick Start

Paving the way to what might be your first AssemblyScript module.

Prerequisites Copy Chapter

The following assumes that a recent version of Node.js and its package manager npm (comes with Node.js) are installed, with the commands below executed in a command prompt. Basic knowledge about writing and working with TypeScript modules, which is very similar, is a plus.

Setting up a new project Copy Chapter

To get started with AssemblyScript, switch to a new directory and initialize a new node module:

npm init

Now install both the loader and the compiler using npm. Let's assume that the compiler is not required in production and make it a development dependency:

npm install --save @assemblyscript/loader
npm install --save-dev assemblyscript

::: tip
If you need a specific version of the loader and/or the compiler, append the respective version number as usual.
:::

Once installed, the compiler provides a handy scaffolding utility to quickly set up a new AssemblyScript project, for example in the directory of the just initialized node module:

npx asinit .

It automatically creates the recommended directory structure and configuration files:

This command will make sure that the following files exist in the project
directory '/path/to/mymodule':

  ./assembly
  Directory holding the AssemblyScript sources being compiled to WebAssembly.

  ./assembly/tsconfig.json
  TypeScript configuration inheriting recommended AssemblyScript settings.

  ./assembly/index.ts
  Example entry file being compiled to WebAssembly to get you started.

  ./build
  Build artifact directory where compiled WebAssembly files are stored.

  ./build/.gitignore
  Git configuration that excludes compiled binaries from source control.

  ./index.js
  Main file loading the WebAssembly module and exporting its exports.

  ./tests/index.js
  Example test to check that your module is indeed working.

  ./asconfig.json
  Configuration file defining both a 'debug' and a 'release' target.

  ./package.json
  Package info containing the necessary commands to compile to WebAssembly.

Do you want to proceed? [Y/n]

Once initialized, edit the sources in assembly/, tweak compiler options in asconfig.json to fit your needs, and run the build command to compile your module to WebAssembly:

npm run asbuild

Next steps Copy Chapter

Once compiled, you may run the tests in tests/index.js:

npm test

add imports to the generated index.js (instantiates the module and re-exports it):

...
const imports = {
  "assembly/index": {
    declaredImportedFunction: function(...) { ... }
  }
};
...

and ultimately use your WebAssembly module like a normal node module:

const myModule = require("path/to/mymodule");
myModule.add(1, 2);

::: tip NOTE
Your module's exports only understand integers and floats for now, with strings and objects being passed as pointers, but we'll get into that later when covering the loader.
:::

Read on to learn more!

File: src/runtime.md Copy Chapter

Runtime

::: danger WARNING
This section is OUTDATED and covers version 0.17 of the AssemblyScript compiler. It has been superseded by the new runtime introduced in 0.18 that is now described under Garbage collection.

Migration from AssemblyScript 0.17 to 0.18 requires re-evaluating uses of __retain and __release, since these have been replaced with __pin and __unpin with slightly different semantics. An object can now be exactly pinned or not pinned, but cannot be pinned multiple times, and WebAssembly exports do not have a special case of pre-retaining objects for the caller anymore. Also, runtime names have changed, and instead of distinguishing between full (runtime exported) and half (runtime not exported), there's now an option --exportRuntime to achieve the effect with any runtime variant.
:::

Documentation for AssemblyScript 0.17:

AssemblyScript's runtime takes care of all the ins and outs of memory management and garbage collection, yet the compiler lets a developer choose the ideal runtime variant for their use case.

Variants Copy Chapter

The default runtime included in a program is the full runtime, but deciding for another variant using the --runtime option can help to reduce binary size significantly. The full runtime adds about 2KB of additional optimized code to your module, which is not that much considering what it brings to the table, but might still be overkill for simple programs.

::: tip
Previous versions of the compiler (pre 0.7) did not include any runtime functionality by default but instead required importing an allocator and potentially an experimental tracing collector. This is not supported anymore by recent versions of the compiler.
:::

Interface Copy Chapter

The following paragraphs are relevant in low-level code respectively when working with objects externally only. In normal high-level code, the compiler utilizes these mechanisms automatically.

Allocating managed objects Copy Section

When allocating a managed object, it is necessary to also provide its unique class id so the runtime can properly recognize it. The unique id of any managed type can be obtained via idof(). Each concrete class (like String, Array, Array<f32>) has its own id. The ids of ArrayBuffer (id=0), String (id=1) and ArrayBufferView (id=2) are always the same, while all other ids are generated sequentially on first use of a class and differ between modules. Hence, it is usually necessary to export Uint8Array_ID = idof() for example when allocating one externally. The relevant interface is:

• ts Copy

  function __new(size: usize, id: u32): usize

  Dynamically allocates an object represented by the specified id of at least the given size in bytes and returns its address. Alignment is guaranteed to be 16 bytes to fit up to v128 values naturally. Does not zero memory.

The loader provides some additional functionality for convenience, like __newString.

Managing lifetimes Copy Section

The concept is simple: If a reference to an object is established, the reference count of the object is increased by 1 (a reference is retained), and when a reference to an object is deleted, the reference count of the object is decreased by 1 (a reference is released). If the reference count of an object reaches 0, it is considered for collection and its memory ultimately returned to the memory manager for reuse. The relevant interface is:

• ts Copy

  function __retain(ptr: usize): usize

  Retains a reference to the object pointed to by ptr. The object doesn't become collected as long as there's at least one retained reference to it. Returns the pointer.

• ts Copy

  function __release(ptr: usize): void

  Releases a reference to the object pointer to by ptr. The object is considered for collection once all references to it have been released.

The compiler inserts retain and release calls automatically and this is opaque to a user on a higher level. On a lower level, for instance when dealing with managed objects externally, it is necessary to understand and adhere to the rules the compiler applies.

{% hint style="info" %}
Technically, both __retain and __release are nops when using the stubruntime, so one can either decide to skip the following for good or spend a little extra time to account for the possibility of upgrading to full later on.
{% endhint %}

Rules

1. A reference to an object is retained when assigning it to a target (local, global, field or otherwise inserting it into a structure) of a reference type, with the exceptions stated in (3).
2. A reference to an object is released when assigning another object to a target of a reference type previously retaining a reference to it, or if the lifetime of the local or structure currently retaining a reference to an object ends.
3. A reference to an object is not released but remains retained when returning a reference typed object from a call (function, getter, constructor or operator overload). Instead, the caller is expected to perform the release. This also means:
   • If a reference to the object would be immediately retained by assigning the object to a target of a reference type, the compiler will not retain it twice, but skip retaining it on assignment.
   • If a reference to the object will not be immediately retained, the compiler will insert a temporary local into the current scope that autoreleases the reference to the object at the end of the scope.

::: tip
Objects created by calling __new start with a reference count of 0. This is not the case for constructors, these behave like calls. Built-ins like store<T> emit instructions directly and don't behave like calls.
:::

Working with references externally Copy Section

Working with objects through imports and exports, like when using the loader, is relatively straight-forward. However, if not handled properly, the program will either leak memory, free objects prematurely or even break. So here's some advice:

• Always __retain a reference to manually __new'ed objects and __release the reference again when done with the object.
• Always __release the reference to an object that was a return value of a call (see above) when done with it. It is not necessary to __retain a reference to returned objects.
• Always __retain a reference to an object read from memory, and __release the reference again when done with the object.

Working with references internally Copy Section

Working with objects internally, like when creating custom standard library components or otherwise writing low-level code, requires special care because switching between pointers and reference types can become quite tricky. The internal interface also provides additional utility that is only relevant in very specific cases.

::: tip
One common point of confusion here is that the rules above operate on types, not values. Means: If the target is of a reference-type, the rules apply, but if the target is of an usize type, the rules do not apply, even if the value is a changetype(..)'d object.
:::

{
  let ref = new ArrayBuffer(10) // retains (reference type)
  let buf = changetype<usize>(ref) // does not retain (usize)
  ...
  // compiler will automatically __release(ref)
}

{
  let buf = changetype<usize>(new ArrayBuffer(10)) // does not retain (usize)
  // inserts a temporary, because _the object_ is not immediately assigned
  ...
  // compiler will automatically __release(theTemp)
}

{
  let ref = changetype<ArrayBuffer>(__new(10, idof<ArrayBuffer>())
  // retains on ref, because after changetype an object is assigned
  ...
  // compiler will automatically __release(ref)
}

Collecting garbage Copy Section

By default, the full and half runtime will automatically try to collect cyclic garbage when memory must be grown. This behavior can be disabled by setting gc.auto = false in performance critical code. Likewise, if there is a good opportunity to collect cyclic garbage at a given point in time, like if the application is idle, gc.collect() can be called to force a full garbage collection cycle. Protip: If no cyclic structures are used, no garbage must be collected.

Implementation Copy Chapter

The memory manager used by AssemblyScript is a variant of TLSF (Two-Level Segregate Fit memory allocator) and it is accompanied by PureRC (a variant of A Pure Reference Counting Garbage Collector) with slight modifications of assumptions to avoid unnecessary work. Essentially, TLSF is responsible for partitioning dynamic memory into chunks that can be used by the various objects, while PureRC keeps track of their lifetimes.

Performance considerations Copy Chapter

Both the TLSF memory manager and the concept of reference counting are a good fit for predictable performance scenarios. Remember: WebAssembly is about exactly that. It is not necessarily the fastest choice in every possible scenario, though.

It is also likely that our implementations are not as optimized yet as ultimately possible. If you are smarter than us, please let us know of your thoughts and findings.

Internals Copy Chapter

If you are interested in the inner workings, the internal APIs are explained in the runtime's README file and of course in its sources - feel free to take a look!

Runtime type information \(RTTI\)

Every module using managed objects contains a memory segment with basic type information, that the loader for example uses when allocating new arrays. Internally, RTTI is used to perform dynamic instanceof checks and to determine whether a class is inherently acyclic. The memory offset of RTTI can be obtained by reading the __rtti_base global. Essentially, the compiler maps every concrete class to a unique id, starting with 0 (=ArrayBuffer), 1 (=String) and 2 (=ArrayBufferView) . For each such class, the compiler remembers the id of the respective base class, if any, and a set of flags describing the class. Flags for example contain information about key and value alignments, whether a class is managed and so on. Structure is like this:

Flag values are currently still in flux, but if you are interested in these, feel free to take a look at the sources.

Notes

Unlike other reference counting implementions, allocating an object starts with a reference count of 0. This is useful in standard library code where memory is first allocated and then assigned to a variable, establishing the first reference.

The compiler does some extra work to evaluate whether an object can potentially become part of a reference cycle. Any object that cannot directly or indirectly reference another object of its kind is considered inherently acyclic, so it does not have to be added to the cycle buffer for further evaluation by deferred garbage collection.

Due to the lack of random access to WebAssembly's execution stack (remember: AssemblyScript does not have a stack on its own), values returned from a function become pre-retained for the caller, expecting that it will release the reference at the end, or give the reference to its own caller. This also leads to situations where sometimes a reference must be retained on assignment, and sometimes it must not. It also leads to situations where two branches must be unified, for example if there is a pre-retained value in one arm and one that is not in the other. The compiler is taking care of these situations, but it also requires special care when dealing with the reference counting internals within the standard library.

The compiler also utilizes a concept of so called autorelease locals. Essentially, if a reference enters a block of code from somewhere else, is pre-retained but not immediately assigned, such a local is added to the current scope to postpone the necessary release until the scope is exited.

One thing not particularly ideal at this point is that each function is expected to retain the reference-type arguments it is given, and release them again at the end. This is necessary because the compiler does just a single pass and doesn't know whether a variable becomes reassigned beforehand (no SSA or similar, that's left to Binaryen in an attempt to avoid duplicating its code). It does already skip this for certain variables like this that cannot be reassigned, but there are definitely more optimization opportunities along the way. Due to AssemblyScript essentially being a compiler on top of another compiler, it is somewhat unclear however where to perform such optimizations.

File: src/status.md Copy Chapter

sidebarDepth: 2 Copy Chapter

Status

Not all language features are equally viable to implement on top of WebAssembly's current capabilities, and while AssemblyScript is already useful today, there is also still a lot to do. Keep in mind that WebAssembly is an evolving technology, and so is AssemblyScript.

Philosophy Copy Chapter

The original idea which made AssemblyScript attractive is that it aims to be a thin and efficient layer on top of WebAssembly with a familiar syntax, ultimately producing lean and mean binaries. This idea is composed of two components, however, that are sometimes orthogonal: Lean and mean implies that we have to stay close to WebAssembly's capabilities, i.e. not going too far already where implementations of certain language features would be inefficient or increase binary size disproportionately, while a familiar syntax naturally begs for supporting more of the original language right now.

As such, while AssemblyScript wants to stay as close as possible to being a language that feels very familiar with JavaScript and TypeScript developers, and aims to preserve compatiblity with existing tooling, it ultimately is a language compiling to WebAssembly and will prioritize language features that allow developers to write fast and small WebAssembly modules on top of the features that WebAssembly already provides.

WebAssembly features Copy Chapter

Some crucial language features rely on future WebAssembly functionality to be efficient. The following table aims to give an overview from a WebAssembly perspective:

Chrome  
Firefox  
Safari  
Node.js  
Wasmtime (¹ native i64 support)

Language features Copy Chapter

As such, certain higher-level language features still have their limitations or are not yet available. From a language perspective:

Bootstrap Copy Section

The first release able to bootstrap itself and pass the test suite is v0.18, released in January 2021. Note that the compiler is not technically "self hosted" in WebAssembly still, as it currently uses a JavaScript frontend for I/O and links to Binaryen (C++ with Emscripten), which also requires some JavaScript glue code. As such, to make the compiler work in a WebAssembly-only engine like Wasmtime, the next steps would be to work towards a WebAssembly-only build of Binaryen, and replace the I/O parts provided by asc with WASI.

Classes and interfaces Copy Section

These mostly work, with a a few caveats.

• Access modifiers like private and protected are not currently enforced. Likely to be enforced in the future.
• Interface fields must be implemented as getters and setters. Likely to be lifted in the future.
• Note that WebAssembly doesn't magically neglect the runtime cost of making extensive use of managed classes, so there are often faster alternatives.

Standard library Copy Section

Some standard library APIs function a little different than in JavaScript to account for differences introduced by static typing or missing WebAssembly features. We are also maintaining a separate status document specific to the standard library.

Generics Copy Section

AssemblyScript compiles generics to one concrete method or function per set of unique contextual type arguments, also known as monomorphisation. Implications are that a module only includes and exports concrete functions for sets of type arguments actually used and that concrete functions can be shortcutted with static type checks at compile time, which turned out to be quite useful.

• The compiler does not currently enforce extends Y clauses on type parameters. Likely to be enforced in the future.
• WebAssembly GC 🦄 may introduce more sophisticated mechanisms like reified generics, potentially post-MVP.
• Concrete functions compiling to the exact same code are de-duplicated during optimization.

Garbage collection Copy Section

Garbage collection is currently implemented in linear memory, independent from the host, and is best paired with the loader for interop.

Interop with JS Copy Section

WebAssembly only understands numeric values as of today and cannot easily exchange objects with JavaScript. Hence, when an object is returned from WebAssembly to JavaScript, what the caller passes and the callee receives is a pointer to the object in linear memory. Note that WebAssembly does not know what to do with JavaScript objects passed to it, as the VM will implicitly convert the object to a number when it crosses the boundary, which is typically not what you want.

For example, to pass a string to a WebAssembly export, one first has to allocate the string in the WebAssembly module's linear memory, and then pass the resulting pointer to the WebAssembly export. The same is true for arrays and other objects.

For now, the loader provides the utility necessary to translate between objects in linear memory and JavaScript objects (e.g. with __newString and __getString), and our hopes are on Type Imports 🦄, Interface Types 🦄 and perhaps Garbage collection 🦄 to make interop more convenient eventually.

See also: Will interop between AssemblyScript and JavaScript become better?

Union types Copy Section

WebAssembly cannot efficiently represent locals or globals of dynamic types, so union types are not supported in AssemblyScript. One can however take advantage of the fact that AssemblyScript is a static compiler, with monomorphized generics and static type checks, to achieve a similar effect:

function addOrConcat<T>(a: T, b: T): T {
  return a + b; // concats if a string, otherwise adds
}

function addOrSomethingElse<T>(a: T, b: T): T {
  if (isString<T>()) {
    return "something else"; // eliminated if T is not a string
  } else {
    return a + b; // eliminated if T is a string
  }
}

Another effect of the above is that AssemblyScript does not have an any type or undefined value.

Symbols Copy Section

The standard library implements Symbol, and it is possible to work with and create new symbols, but there is no deep compiler integration like registration of Symbol.iterator etc. yet.

JSON Copy Section

JSON integration in the compiler itself is still an open question due to its untyped nature. May require a mix of reflection and schema-specific code generation for natural integration.

Solutions being developed by the community:

• nearprotocol/assemblyscript-json

RegExp Copy Section

Regular expressions have been on our todo list for quite a while. It's mostly that a good implementation becomes complicated pretty quickly with special Unicode cases, exponential behavior and so on. Also, an ideal RegExp implementation would be compatible with the ECMAScript specification, reasonably fast and integrate deeply with the compiler, so RegExp literals can be pre-compiled (to WebAssembly code or an intermediate bytecode), making it unnecessary most of the time to ship the entire engine with a module.

Solutions being developed by the community:

• ColinEberhardt/assemblyscript-regex

Closures Copy Section

Closures (functions with a captured environment) are not yet supported and we are waiting for the Function References 🦄 and Garbage collection 🦄 (captured environments are GC'ed) proposals to land. However, since this is a crucial language feature, we may end up with a filler implementation using linear memory. Not available yet, though.

In the meantime we recommend to restructure code so closures are not necessary, i.e. instead of writing

function computeSum(arr: i32[]): i32 {
  var sum = 0
  arr.forEach(value => {
    sum += value // fails
  })
  return sum
}

restructure to

var sum: i32 // becomes a WebAssembly Global
function computeSum(arr: i32[]): i32 {
  sum = 0
  arr.forEach(value => {
    sum += value // works
  })
  return sum
}

or to

function computeSum(arr: i32[]): i32 {
  var sum = 0
  for (let i = 0, k = arr.length; i < k; ++i) {
    sum += arr[i] // works
  }
  return sum
}

Iterators Copy Section

It has not been attempted to implement iterators due to uncertainty how efficient iterators will be using frequent dynamic allocation. Also requires symbols for deep integration. Therefore for ... of loops are not currently supported. To work around the limitation of not having iterators, otherwise non-functional standard library APIs return an array for now:

Map\

• ts Copy

  function keys(): Array<K>

• ts Copy

  function values(): Array<V>

Set\

• ts Copy

  function values(): Array<T>

Rest parameters Copy Section

It has not yet been attempted to implement variadic functions due to uncertainty how efficient it will be without random stack access. The risk is that doing dynamic allocations instead may introduce an unfortunate hidden cost to function calls.

In the meantime, optional function arguments, which do not have such a hidden cost, may be able to help:

function handleGiven(a: i32, b: i32 = -1, c: i32 = -1): void {
  handle(a);
  if (~b) {
    handle(b);
    if (~c) {
      handle(c);
    }
  }
}

Exceptions Copy Section

Exceptions are not yet supported and we are waiting for the Exception handling 🦄 proposal to land. It is not yet feasible to implement exceptions without the help of the proposal as throwing and catching an exception requires stack unwinding, so the following will currently crash the program with a call to abort("message", ...):

function doThrow(): void {
  throw new Error("message")
}

In the meantime we recommend to do as they did in the olden days and return an error code or null to indicate an exception.

Promises Copy Section

The concept of async execution requires an underlying concept of an event loop, which browsers and Node.js have but WebAssembly does not. In the meantime, it is recommended to stick to synchronous code within WebAssembly or call back into WebAssembly when an external async operation completes.

BigInt Copy Section

We have favored the use of WebAssembly's native 64-bit integers over BigInts and their INTn notation so far, since BigInts can represent values > 64-bits and as such would have to be implemented as less-efficient heap allocated objects. There are certain use cases relying on representing more than 64-bits, of course, but we still have to figure out how to support both types without introducing conflicts.

Dynamicness Copy Section

AssemblyScript intentionally avoids very dynamic JavaScript features that cannot be compiled efficiently, like for example:

• Assigning any value to any variable.
• Compare values of incompatible types.
• Implicitly convert from a non-string to a string without using x.toString().
• Assign a new property, that has not been statically declared, to a class or object.
• Assign a class to a variable (e.g. var clazz = MyClass) since classes are static constructs without a runtime representation.
• Patch class .prototypes since there are none.
• Access arguments to dynamically obtain function arguments.
• Dynamically obtain the name of a function at runtime or otherwise use reflection.

Some of these restrictions, like implicit conversion to strings when concatenating with a string, may be lifted in the future, while others, like prototypes, may never be viable in ahead-of-time compilation. For instance, some features would work in an interpreter and may become efficient with a JIT compiler, yet going down that rabbit hole runs counter to WebAssembly's, and by definition AssemblyScript's, goals.

Tooling features Copy Chapter

Debugging Copy Section

Debugging of AssemblyScript modules is not as convenient as it should be, but possible with debug information and accompanying source maps. For a better debugging experience, we may eventually want to integrate with the DWARF format used by for example LLVM, ideally through Binaryen.

Testing Copy Section

The standard library provides the assert built-in, which does not decide on a particular flavor of testing, yet is often sufficient to write basic tests.

Solutions being developed by the community:

• jtenner/as-pect

Linting Copy Section

AssemblyScript piggy-backs on top of TypeScript's excellent infrastructure currently, making it trivial to get started, but could need more sophisticated checking (as one types) for where code is valid TypeScript but not valid AssemblyScript or vice-versa with // @ts-ignore. It is still an open question whether a custom language server is needed (potentially with a separate file extension), or if a plugin on top of existing TypeScript tooling would be an equally viable option. The latter would imply having to reinvent fewer wheels, like code navigation and refactoring etc., while the former may feel more polished once all the wheels have been reinvented.

Solutions being developed by the community:

• Shopify/asls

File: src/transforms.md Copy Chapter

Transforms

AssemblyScript is compiled statically, so code transformation cannot be done at runtime but must instead be performed at compile-time. To enable this, the compiler frontend (asc) provides a mechanism to hook into the compilation process before, while and after the module is being compiled.

Specifying --transform ./myTransform on the command line will load the node module pointed to by ./myTransform.

const { Transform } = require("assemblyscript/cli/transform")
const assemblyscript = require("assemblyscript")
class MyTransform extends Transform {
  ...
}
module.exports = MyTransform

Properties Copy Chapter

A transform is an ES6 class/node module with the following inherited properties:

• ts Copy

  readonly program: Program

  Reference to the Program instance.

• ts Copy

  readonly baseDir: string

  Base directory used by the compiler.

• ts Copy

  readonly stdout: OutputStream

  Output stream used by the compiler.

• ts Copy

  readonly stderr: OutputStream

  Error stream uses by the compiler.

• ts Copy

  readonly log: typeof console.log

  Logs a message to console.

• ts Copy

  function writeFile(filename: string, contents: string | Uint8Array, baseDir: string): boolean

  Writes a file to disk.

• ts Copy

  function readFile(filename: string, baseDir: string): string | null

  Reads a file from disk.

• ts Copy

  function listFiles(dirname: string, baseDir: string): string[] | null

  Lists all files in a directory.

Hooks Copy Chapter

The frontend will call several hooks, if present on the transform, during the compilation process:

• ts Copy

  function afterParse(parser: Parser): void

  Called when parsing is complete, before a program is initialized from the AST. Note that types are not yet known at this stage and there is no easy way to obtain them.

• ts Copy

  function afterInitialize(program: Program): void

  Called once the program is initialized, before it is being compiled. Types are known at this stage, respectively can be resolved where necessary.

• ts Copy

  function afterCompile(module: Module): void

  Called with the resulting module before it is being emitted. Useful to modify the IR before writing any output, for example to replace imports with actual functionality or to add custom sections.

Transforms are a very powerful feature, but may require profound knowledge of the compiler to utilize them to their full extent, so reading through the compiler sources is a plus.

File: src/types.md Copy Chapter

Types

Instead of using the number type for all sorts of numeric values, AssemblyScript inherits WebAssembly's more specific integer and floating point types:

Type rules Copy Chapter

AssemblyScript will complain when it sees an implicit conversion that might not actually be intended, quite similar to what a C compiler would do.

Casting Copy Section

In AssemblyScript, the type assertions <T>expression and expression as T known from TypeScript become explicit type conversions, essentially telling the compiler that the conversion is intended. In addition, each of the type names mentioned above, except aliases, also act as portable conversion built-ins that can be used just like i32(expression). Using portable conversions is especially useful where the exact same code is meant to be compiled to JavaScript with the TypeScript compiler (see), that otherwise would require the insertion of asm.js-style type coercions like expression | 0.

Inference Copy Section

Compared to TypeScript, type inference in AssemblyScript is limited because the type of each expression must be known in advance. This means that variable and parameter declarations must either have their type annotated or have an initializer. Without a type annotation and only an initializer, AssemblyScript will assume i32 at first and only reconsider another type if the value doesn't fit (becomes i64), is a float (becomes f64) or irrefutably has another type than these, like the type of a variable, the return type of a function or a class type. Furthermore, functions must be annotated with a return type to help the compiler make the correct decisions, for example where a literal is returned or multiple return statements are present.

Nullability Copy Section

Basic types cannot be nullable, but class and function types can. Appending | null declares a nullable type.

Assignability Copy Section

Assigning a value of one type to a target of another type can be performed without explicit casts where the full range of possible values can be represented in the target type, regardless of interpretation/signedness:

Note that isize and usize are aliases of either i32 and u32 in WASM32 respectively i64 and u64 in WASM64 🦄.

var  i8val: i8  = -128  // 0x80
var  u8val: u8  = i8val // becomes 128 (0x80)
var i16val: i16 = i8val // becomes -128 through sign-extension (0xFF80)
var u16val: u16 = i8val // becomes 65408 through masking (0xFF80)
var f32val: f32 = i8val // becomes -128.0

Comparability Copy Section

Comparing two values of different types can be performed without an explicit cast under the same rules as outlined in assignability above

1. if the comparison is absolute (==, !=)
2. if the comparison is relative (>, <, >=, <=) and both types have the same signedness

because WebAssembly has distinct operations for signed and unsigned comparisons. The comparison uses the larger type and returns bool.

Bit shifts Copy Section

The result of a bit shift (<<, >>) is the left type, with the right type implicitly converted to the left type, performing an arithmetic shift if the left type is signed and a logical shift if the left type is unsigned.

The result of an unsigned right shift (>>>) is the left type (signedness is retained), with the right type implicitly converted to the left type, but always performing a logical shift.

Note that only the log2(sizeof<T>()) least signficant bits of the shift affect the result:

If the left type is a float, an error is emitted.

Macro types Copy Chapter

The following macro types provide access to related types that would otherwise be impossible to obtain.

File: src/examples/arrays.md Copy Chapter

Arrays example

Shows how to exchange and work with arrays either created in WebAssembly or in JavaScript.

Contents Copy Chapter

• Using the loader and the full runtime to work with managed objects.
• Creating arrays in WebAssembly and using them in JavaScript.
• Creating arrays in JavaScript and using them in WebAssembly.
• Using both copies of and live views on arrays.
• Performing unchecked accesses where the length of an array is known.
• Pinning objects externally to prevent premature garbage collection.

Example Copy Chapter

#!optimize=speed&runtime=default&exportRuntime
/** Creates a new array and returns it to JavaScript. */
export function createArray(length: i32): Int32Array {
  return new Int32Array(length)
}

/** Randomizes the specified array's values. */
export function randomizeArray(arr: Int32Array): void {
  for (let i = 0, k = arr.length; i < k; ++i) {
    let value = i32((Math.random() * 2.0 - 1.0) * i32.MAX_VALUE)
    unchecked(arr[i] = value)
  }
}

/** Computes the sum of an array's values and returns the sum to JavaScript. */
export function sumArray(arr: Int32Array): i32 {
  let total = 0
  for (let i = 0, k = arr.length; i < k; ++i) {
    total += unchecked(arr[i])
  }
  return total
}

// We'll need the unique Int32Array id when allocating one in JavaScript
export const Int32Array_ID = idof<Int32Array>()

#!html
<textarea id="output" style="width: 100%; height: 100%" readonly></textarea>
<script>
loader.instantiate(module_wasm).then(({ exports }) => {
  const output = document.getElementById('output')

  /** Logs a message to the textarea. */
  function log(message = '') {
    output.value += `${message}\n`
  }

  // A simple example using an array created in WebAssembly.
  function example1() {
    log('=== Example1 ===')

    // Obtain the necessary runtime helpers
    const { __pin, __unpin, __getArray } = exports

    // Create a new array in WebAssembly and get a reference to it. Note that
    // the array is not reachable from within WebAssembly, only externally, so
    // we should pin it to prevent it from becoming garbage collected too early.
    let arrayPtr = __pin(exports.createArray(5))
    log(`Array pointer: ${arrayPtr}`)

    // Log its elements to make sure these are zero
    log('Initial values: ' + __getArray(arrayPtr).join(', '))

    // Randomize the array in WebAssembly and log it again
    exports.randomizeArray(arrayPtr)
    log('Randomized values: ' + __getArray(arrayPtr).join(', '))

    // Compute the array values' sum and log it. This will overflow i32 range.
    let total = exports.sumArray(arrayPtr)
    log(`Sum (likely overflown): ${total}`)

    // We are done with the array, so __unpin it so it can become collected.
    __unpin(arrayPtr)

    log()
  }
  example1()

  // A slightly more advanced example allocating the array in JavaScript instead
  // of WebAssembly, and utilizing a live view to modify it in WebAssembly memory.
  function example2() {
    log('=== Example2 ===')

    // Obtain the necessary runtime helpers
    const { __pin, __unpin, __newArray, __getArray, __getArrayView } = exports

    // Create a new array, but this time in JavaScript. Note that the array is
    // again not reachable from within WebAssembly, only externally, so we
    // should pin it to prevent it from becoming garbage collected too early.
    let arrayPtr = __pin(__newArray(exports.Int32Array_ID, [
      3, 4, 5, 6, 7, 8, 9
    ]))
    log('Array pointer: ' + arrayPtr)

    // Log its elements to make sure these are the provided values
    log('Initial values: ' + __getArray(arrayPtr).join(', '))

    // Compute the array values' sum and log it
    let total = exports.sumArray(arrayPtr)
    log('Sum: ' + total)

    // Instead of copying, let's obtain a live view on the array and modify its
    // values right in WebAssembly memory.
    let view = __getArrayView(arrayPtr)
    view.reverse()

    // Log the array's elements, now reversed
    log('Reversed values: ' + __getArray(arrayPtr).join(', '))

    // We are done with the array, so __unpin it so it can become collected.
    __unpin(arrayPtr)

    log()
  }
  example2()
})
</script>

::: tip NOTE
This example utilizes the loader to work with managed objects, hence requires --exportRuntime to be set to expose the runtime helpers to JavaScript.
:::

Resources Copy Chapter

Further information on using the loader and the runtime helpers is available as part of the loader's and the garbage collection documentation.

File: src/examples/game-of-life.md Copy Chapter

Game of Life example

Continuously updates a slightly modified variant of Conway's Game of Life and visualizes its state on a canvas.

Contents Copy Chapter

• Exporting functions from a WebAssembly module.
• Calling functions exported from WebAssembly.
• Importing configuration values from JavaScript.
• Instantiating the module's memory in JavaScript and import it using --importMemory.
• Speeding up a program by forcing helper functions in a hot path to always @inline.
• Utilizing JavaScript's Math instead of native libm to reduce module size via --use Math=JSMath.
• Reacting to user input by directly modifying an input image buffer.
• Finding out about WebAssembly's unintuitive byte order.
• And finally: Continuously updating an input to an output image buffer and rendering the output image buffer.
• Featuring: Clicking and drawing lots of stuff.

Example Copy Chapter

#!optimize=speed&runtime=stub&importMemory&use=Math=JSMath
// Configuration imported from JS
declare const BGR_ALIVE: u32;
declare const BGR_DEAD: u32;
declare const BIT_ROT: u32;

var width: i32, height: i32, offset: i32;

/** Gets an input pixel in the range [0, s]. */
@inline
function get(x: u32, y: u32): u32 {
  return load<u32>((y * width + x) << 2);
}

/** Sets an output pixel in the range [s, 2*s]. */
@inline
function set(x: u32, y: u32, v: u32): void {
  store<u32>((offset + y * width + x) << 2, v);
}

/** Sets an output pixel in the range [s, 2*s] while fading it out. */
@inline
function rot(x: u32, y: u32, v: u32): void {
  var alpha = max<i32>((v >> 24) - BIT_ROT, 0);
  set(x, y, (alpha << 24) | (v & 0x00ffffff));
}

/** Initializes width and height. Called once from JS. */
export function init(w: i32, h: i32): void {
  width  = w;
  height = h;
  offset = w * h;

  // Start by filling output with random live cells.
  for (let y = 0; y < h; ++y) {
    for (let x = 0; x < w; ++x) {
      let c = Math.random() > 0.1
        ? BGR_DEAD  & 0x00ffffff
        : BGR_ALIVE | 0xff000000;
      set(x, y, c);
    }
  }
}

/** Performs one step. Called about 30 times a second from JS. */
export function step(): void {
  var w = width,
      h = height;

  var hm1 = h - 1, // h - 1
      wm1 = w - 1; // w - 1

  // The universe of the Game of Life is an infinite two-dimensional orthogonal grid of square
  // "cells", each of which is in one of two possible states, alive or dead.
  for (let y = 0; y < h; ++y) {
    let ym1 = y == 0 ? hm1 : y - 1,
        yp1 = y == hm1 ? 0 : y + 1;
    for (let x = 0; x < w; ++x) {
      let xm1 = x == 0 ? wm1 : x - 1,
          xp1 = x == wm1 ? 0 : x + 1;

      // Every cell interacts with its eight neighbours, which are the cells that are horizontally,
      // vertically, or diagonally adjacent. Least significant bit indicates alive or dead.
      let aliveNeighbors = (
        (get(xm1, ym1) & 1) + (get(x, ym1) & 1) + (get(xp1, ym1) & 1) +
        (get(xm1, y  ) & 1)                     + (get(xp1, y  ) & 1) +
        (get(xm1, yp1) & 1) + (get(x, yp1) & 1) + (get(xp1, yp1) & 1)
      );

      let self = get(x, y);
      if (self & 1) {
        // A live cell with 2 or 3 live neighbors rots on to the next generation.
        if ((aliveNeighbors & 0b1110) == 0b0010) rot(x, y, self);
        // A live cell with fewer than 2 or more than 3 live neighbors dies.
        else set(x, y, BGR_DEAD | 0xff000000);
      } else {
        // A dead cell with exactly 3 live neighbors becomes a live cell.
        if (aliveNeighbors == 3) set(x, y, BGR_ALIVE | 0xff000000);
        // A dead cell with fewer or more than 3 live neighbors just rots.
        else rot(x, y, self);
      }
    }
  }
}

/** Fills the row and column indicated by `x` and `y` with random live cells. */
export function fill(x: u32, y: u32, p: f64): void {
  for (let ix = 0; ix < width; ++ix) {
    if (Math.random() < p) set(ix, y, BGR_ALIVE | 0xff000000);
  }
  for (let iy = 0; iy < height; ++iy) {
    if (Math.random() < p) set(x, iy, BGR_ALIVE | 0xff000000);
  }
}

#!html
<canvas id="canvas" style="width: 100%; height: 100%; background: #000; cursor: crosshair"></canvas>
<script>
// Configuration
const RGB_ALIVE = 0xD392E6;
const RGB_DEAD  = 0xA61B85;
const BIT_ROT   = 10;

// Set up the canvas with a 2D rendering context
const canvas = document.getElementById("canvas");
const boundingRect = canvas.getBoundingClientRect();
const ctx = canvas.getContext("2d");

// Compute the size of the universe (2 pixels per cell)
const width = boundingRect.width >>> 1;
const height = boundingRect.height >>> 1;
const size = width * height;
const byteSize = (size + size) << 2; // input & output (4 bytes per cell)

canvas.width = width;
canvas.height = height;
canvas.style.imageRendering = "pixelated";
ctx.imageSmoothingEnabled = false;

// Compute the size of and instantiate the module's memory
const memory = new WebAssembly.Memory({ initial: ((byteSize + 0xffff) & ~0xffff) >>> 16 });

// Fetch and instantiate the module
loader.instantiate(module_wasm, {
  env: {
    memory
  },
  module: {
    BGR_ALIVE : rgb2bgr(RGB_ALIVE) | 1, // LSB set indicates alive
    BGR_DEAD  : rgb2bgr(RGB_DEAD) & ~1, // LSB not set indicates dead
    BIT_ROT
  }
}).then(({ exports }) => {
  // Initialize the module with the universe's width and height
  exports.init(width, height);

  var buffer = new Uint32Array(memory.buffer);

  // Update about 30 times a second
  (function update() {
    setTimeout(update, 1000 / 30);
    buffer.copyWithin(0, size, size + size);   // copy output to input
    exports.step();                            // perform the next step
  })();

  // Keep rendering the output at [size, 2*size]
  var imageData = ctx.createImageData(width, height);
  var argb = new Uint32Array(imageData.data.buffer);
  (function render() {
    requestAnimationFrame(render);
    argb.set(buffer.subarray(size, size + size)); // copy output to image buffer
    ctx.putImageData(imageData, 0, 0);            // apply image buffer
  })();

  // When clicked or dragged, fill the current row and column with random live cells
  var down = false;
  [ [canvas, "mousedown"],
    [canvas, "touchstart"]
  ].forEach(eh => eh[0].addEventListener(eh[1], e => down = true));
  [ [document, "mouseup"],
    [document, "touchend"]
  ].forEach(eh => eh[0].addEventListener(eh[1], e => down = false));
  [ [canvas, "mousemove"],
    [canvas, "touchmove"],
    [canvas, "mousedown"]
  ].forEach(eh => eh[0].addEventListener(eh[1], e => {
    if (!down) return;
    var loc;
    if (e.touches) {
      if (e.touches.length > 1) return;
      loc = e.touches[0];
    } else {
      loc = e;
    }
    const currentBoundingRect = canvas.getBoundingClientRect();
    exports.fill(
      ((loc.clientX - currentBoundingRect.left) / currentBoundingRect.width * boundingRect.width) >>> 1,
      ((loc.clientY - currentBoundingRect.top) / currentBoundingRect.height * boundingRect.height) >>> 1,
      0.5
    );
  }));
});

/** Bitshifts an RGB color to BGR instead (WebAssembly is little endian). */
function rgb2bgr(rgb) {
  return ((rgb >>> 16) & 0xff) | (rgb & 0xff00) | (rgb & 0xff) << 16;
}
</script>

::: tip NOTE
The example makes a couple assumptions. For instance, using the entire memory of the program as the image buffer as in this example is only possible because we know that no interferring static memory segments will be created, which is achieved by

• using JavaScript's Math instead of native libm (usually adds lookup tables),
• not using a more sophisticated runtime (typically adds bookkeeping) and
• the rest of the example being relatively simple (i.e. no strings or similar).

As soon as these conditions are no longer met, one would instead either reserve some space by specifying a suitable --memoryBase or export a dynamically instantiated chunk of memory, like an Uint32Array, and utilize it as the input and output image buffers both in WebAssembly and in JavaScript.
:::

Running locally Copy Chapter

Instructions are identical to those of the Mandelbrot example.

File: src/examples/interference.md Copy Chapter

Interference example

Colin Eberhardt's and Ben Smith's WebAssembly interference effect, if it was written in AssemblyScript.

Contents Copy Chapter

• Exporting functions and variables from a WebAssembly module.
• Calling functions and reading variables exported from WebAssembly.
• Utilizing 32-bit floating point math to speed up calculations by utilizing Mathf.
• Keeping an image buffer within the module's memory and copying it to a canvas.
• Manually growing memory depending on the size of the viewport on the browser side.
• And finally: Continuously updating and rendering the image buffer.

Example Copy Chapter

::: danger EPILEPSY WARNING
A very small percentage of individuals may experience epileptic seizures when exposed to certain light patterns or flashing lights. Exposure to certain patterns or backgrounds on a computer screen may induce an epileptic seizure in these individuals. Certain conditions may induce previously undetected epileptic symptoms even in persons who have no history of prior seizures or epilepsy.

If you experience any of the following symptoms while viewing - dizziness, altered vision, eye or muscle twitches, loss of awareness, disorientation, any involuntary movement, or convulsions - IMMEDIATELY discontinue use and consult your physician.
:::

#!optimize=speed&runtime=stub
var width  = 320;
var height = 200;

// Let's utilize the entire heap as our image buffer
export const offset = __heap_base;

/** Sets a single pixel's color. */
function set(x: i32, y: i32, v: f32): void {
  var vi = <i32>v;
  store<i32>(offset + ((width * y + x) << 2), ~vi << 24 | vi << 8);
}

/** Computes the distance between two pixels. */
function distance(x1: i32, y1: i32, x2: f32, y2: f32): f32 {
  var dx = <f32>x1 - x2;
  var dy = <f32>y1 - y2;
  return Mathf.sqrt(dx * dx + dy * dy);
}

/** Performs one tick. */
export function update(tick: f32): void {
  var w = <f32>width;
  var h = <f32>height;
  var hw = w * 0.5,
      hh = h * 0.5;
  var cx1 = (Mathf.sin(tick * 2) + Mathf.sin(tick      )) * hw * 0.3 + hw,
      cy1 = (Mathf.cos(tick)                            ) * hh * 0.3 + hh,
      cx2 = (Mathf.sin(tick * 4) + Mathf.sin(tick + 1.2)) * hw * 0.3 + hw,
      cy2 = (Mathf.sin(tick * 3) + Mathf.cos(tick + 0.1)) * hh * 0.3 + hh;
  var res = <f32>48 / Mathf.max(w, h);
  var y = 0;
  do {
    let x = 0;
    do {
      set(x, y, Mathf.abs(
        Mathf.sin(distance(x, y, cx1, cy1) * res) +
        Mathf.sin(distance(x, y, cx2, cy2) * res)
      ) * 120);
    } while (++x != width)
  } while (++y != height)
}

/** Recomputes and potentially grows memory on resize of the viewport. */
export function resize(w: i32, h: i32): void {
  width = w; height = h;
  // Pages are 64kb. Rounds up using mask 0xffff before shifting to pages.
  var needed = <i32>((offset + (w * h * sizeof<i32>() + 0xffff)) & ~0xffff) >>> 16;
  var actual = memory.size();
  if (needed > actual) memory.grow(needed - actual);
}

#!html
<canvas id="canvas" style="width: 100%; height: 100%; background: #aff"></canvas>
<script>
var step = 0.012;
loader.instantiate(module_wasm).then(({ exports }) => {
  const canvas = document.getElementById("canvas");
  const context = canvas.getContext("2d");

  // Upscale the image to speed up calculations
  const upscaleFactor = 4;

  var width, height, image;

  // Inform the module about the viewport's size, incl. on resize
  function onresize() {
    width = (canvas.offsetWidth / upscaleFactor) | 0;
    height = (canvas.offsetHeight / upscaleFactor) | 0;
    canvas.width = width;
    canvas.height = height;
    image = context.createImageData(width, height);
    exports.resize(width, height);
  }
  onresize();
  new ResizeObserver(onresize).observe(canvas);

  // Keep updating the image
  var tick = 0.0;
  (function update() {
    requestAnimationFrame(update);
    exports.update(tick += step);
    new Uint32Array(image.data.buffer).set(new Uint32Array(exports.memory.buffer, exports.offset, width * height));
    context.putImageData(image, 0, 0);
  })();
});
</script>

::: tip NOTE
The example makes one important assumption: Since we are not using a sophisticated runtime, we can instead repurpose the entire heap, starting at __heap_base, as our image buffer.

As soon as this condition is no longer met, one would instead either reserve some space by specifying a suitable --memoryBase or export a dynamically instantiated chunk of memory, like an Uint32Array, and utilize it as the image buffer both in WebAssembly and in JavaScript.
:::

Running locally Copy Chapter

Set up a new AssemblyScript project as described in Quick start and copy module.ts to assembly/index.ts and index.html to the project's top-level directory. Edit the build commands in package.json to include

--runtime none

The example can now be compiled with

npm run asbuild

To view the example, one can modify the instantiation in index.html from

loader.instantiate(module_wasm).then(({ exports }) => {

to

WebAssembly.instantiateStreaming(fetch('./build/optimized.wasm'), {
  JSMath: Math
}).then(({ exports }) => {

because using the loader is not ultimately necessary here (no managed objects are exchanged). If the loader is used instead, it will automatically provide JSMath.

Some browsers may restrict fetching local resources when just opening index.html now, but one can set up a local server as a workaround:

npm install --save-dev http-server
http-server . -o -c-1

File: src/examples/mandelbrot.md Copy Chapter

Mandelbrot example

Renders the Mandelbrot set to a canvas using 2048 discrete color values computed on the JS side.

Contents Copy Chapter

• Exporting functions from a WebAssembly module.
• Calling functions exported from WebAssembly.
• Instantiating the module's memory in JavaScript and import it using --importMemory.
• Utilizing JavaScript's Math instead of native libm to reduce module size via --use Math=JSMath.
• And finally: Reading and translating data from WebAssembly memory to colors rendered to a canvas.

Example Copy Chapter

#!optimize=speed&runtime=stub&importMemory&use=Math=JSMath
/** Number of discrete color values on the JS side. */
const NUM_COLORS = 2048;

/** Updates the rectangle `width` x `height`. */
export function update(width: u32, height: u32, limit: u32): void {
  var translateX = width  * (1.0 / 1.6);
  var translateY = height * (1.0 / 2.0);
  var scale      = 10.0 / min(3 * width, 4 * height);
  var realOffset = translateX * scale;
  var invLimit   = 1.0 / limit;

  var minIterations = min(8, limit);

  for (let y: u32 = 0; y < height; ++y) {
    let imaginary = (y - translateY) * scale;
    let yOffset   = (y * width) << 1;

    for (let x: u32 = 0; x < width; ++x) {
      let real = x * scale - realOffset;

      // Iterate until either the escape radius or iteration limit is exceeded
      let ix = 0.0, iy = 0.0, ixSq: f64, iySq: f64;
      let iteration: u32 = 0;
      while ((ixSq = ix * ix) + (iySq = iy * iy) <= 4.0) {
        iy = 2.0 * ix * iy + imaginary;
        ix = ixSq - iySq + real;
        if (iteration >= limit) break;
        ++iteration;
      }

      // Do a few extra iterations for quick escapes to reduce error margin
      while (iteration < minIterations) {
        let ixNew = ix * ix - iy * iy + real;
        iy = 2.0 * ix * iy + imaginary;
        ix = ixNew;
        ++iteration;
      }

      // Iteration count is a discrete value in the range [0, limit] here, but we'd like it to be
      // normalized in the range [0, 2047] so it maps to the gradient computed in JS.
      // see also: http://linas.org/art-gallery/escape/escape.html
      let colorIndex = NUM_COLORS - 1;
      let distanceSq = ix * ix + iy * iy;
      if (distanceSq > 1.0) {
        let fraction = Math.log2(0.5 * Math.log(distanceSq));
        colorIndex = <u32>((NUM_COLORS - 1) * clamp<f64>((iteration + 1 - fraction) * invLimit, 0.0, 1.0));
      }
      store<u16>(yOffset + (x << 1), colorIndex);
    }
  }
}

/** Clamps a value between the given minimum and maximum. */
function clamp<T>(value: T, minValue: T, maxValue: T): T {
  return min(max(value, minValue), maxValue);
}

#!html
<canvas id="canvas" style="width: 100%; height: 100%"></canvas>
<script>

// Set up the canvas with a 2D rendering context
const canvas = document.getElementById("canvas");
const boundingRect = canvas.getBoundingClientRect();
const ctx = canvas.getContext("2d");

// Compute the size of the viewport
const ratio  = window.devicePixelRatio || 1;
const width  = (boundingRect.width  | 0) * ratio;
const height = (boundingRect.height | 0) * ratio;
const size = width * height;
const byteSize = size << 1; // discrete color indices in range [0, 2047] (2 bytes per pixel)

canvas.width  = width;
canvas.height = height;

ctx.scale(ratio, ratio);

// Compute the size (in pages) of and instantiate the module's memory.
// Pages are 64kb. Rounds up using mask 0xffff before shifting to pages.
const memory = new WebAssembly.Memory({ initial: ((byteSize + 0xffff) & ~0xffff) >>> 16 });
const buffer = new Uint16Array(memory.buffer);
const imageData = ctx.createImageData(width, height);
const argb = new Uint32Array(imageData.data.buffer);

loader.instantiate(module_wasm, {
  env: {
    memory
  }
}).then(({ exports }) => {

  // Update state
  exports.update(width, height, 40);

  // Translate 16-bit color indices to colors
  for (let y = 0; y < height; ++y) {
    const yx = y * width;
    for (let x = 0; x < width; ++x) {
      argb[yx + x] = colors[buffer[yx + x]];
    }
  }

  // Render the image buffer.
  ctx.putImageData(imageData, 0, 0);
});

/** Computes a nice set of colors using a gradient. */
function computeColors() {
  const canvas = document.createElement("canvas");
  canvas.width = 2048;
  canvas.height = 1;
  const ctx = canvas.getContext("2d");
  const grd = ctx.createLinearGradient(0, 0, 2048, 0);
  grd.addColorStop(0.00, "#000764");
  grd.addColorStop(0.16, "#2068CB");
  grd.addColorStop(0.42, "#EDFFFF");
  grd.addColorStop(0.6425, "#FFAA00");
  grd.addColorStop(0.8575, "#000200");
  ctx.fillStyle = grd;
  ctx.fillRect(0, 0, 2048, 1);
  return new Uint32Array(ctx.getImageData(0, 0, 2048, 1).data.buffer);
}

const colors = computeColors();
</script>

::: tip NOTE
The example makes a couple assumptions. For instance, using the entire memory of the program as the image buffer as in this example is only possible because we know that no interferring static memory segments will be created, which is achieved by

• using JavaScript's Math instead of native libm (usually adds lookup tables),
• not using a more sophisticated runtime (typically adds bookkeeping) and
• the rest of the example being relatively simple (i.e. no strings or similar).

As soon as these conditions are no longer met, one would instead either reserve some space by specifying a suitable --memoryBase or export a dynamically instantiated chunk of memory, like an Uint16Array, and utilize it as the color index buffer both in WebAssembly and in JavaScript.
:::

Running locally Copy Chapter

Set up a new AssemblyScript project as described in Quick start and copy module.ts to assembly/index.ts and index.html to the project's top-level directory. Edit the build commands in package.json to include

--runtime none --use Math=JSMath --importMemory

The example can now be compiled with

npm run asbuild

To view the example, one can modify the instantiation in index.html from

loader.instantiate(module_wasm, {
  env: {
    memory
  }
}).then(({ exports }) => {

to

WebAssembly.instantiateStreaming(fetch('./build/optimized.wasm'), {
  env: {
    memory
  },
  JSMath: Math
}).then(({ exports }) => {

because using the loader is not ultimately necessary here (no managed objects are exchanged). If the loader is used instead, it will automatically provide JSMath.

Some browsers may restrict fetching local resources when just opening index.html now, but one can set up a local server as a workaround:

npm install --save-dev http-server
http-server . -o -c-1

File: src/examples/snippets.md Copy Chapter

Snippets

Small, copy-pastable AssemblyScript examples using common syntax and patterns.

Class Copy Chapter

An AssemblyScript snippet on using Classes, their instantiation, and their static properties.

#!runtime=stub
class Animal<T> {
  static ONE: i32 = 1;
  static add(a: i32, b: i32): i32 { return a + b + Animal.ONE; }

  two: i16 = 2; // 6
  instanceSub<T>(a: T, b: T): T { return a - b + <T>Animal.ONE; } // tsc does not allow this
}

export function staticOne(): i32 {
  return Animal.ONE;
}

export function staticAdd(a: i32, b: i32): i32 {
  return Animal.add(a, b);
}

export function instanceTwo(): i32 {
  let animal = new Animal<i32>();
  return animal.two;
}

export function instanceSub(a: f32, b: f32): f32 {
  let animal = new Animal<f32>();
  return animal.instanceSub<f32>(a, b);
}


#!html
<script>
const log = console.log;
console.log = (...args) => {
  log(...args);
  let str = '';
  args.forEach(arg => {
    if (typeof arg == 'object') {
      str += `${JSON.stringify(arg, null, 2)}<br/>`;
    } else {
      str += `${arg}<br/>`;
    }
  });
  document.body.innerHTML += `<div>Log: ${str}</div>`;
}

loader.instantiate(module_wasm, { /* imports */ })
  .then(({ exports }) => {
    console.log(exports.staticOne());
    console.log(exports.staticAdd(1, 2));
    console.log(exports.instanceTwo());
    console.log(exports.instanceSub(3.0, 1.0));
  })
</script>

Extending Classes Copy Chapter

Extending classes and general Object Orientated Programming (OOP) in AssemblyScript

#!runtime=stub

class BaseClass {
  static staticProp: i32 = 24;
  instanceProp: i32;

  constructor(value: i32) {
    this.instanceProp = value;
  }

  add(a: i32, b: i32): i32 {
    return a + b;
  }
}

class ExtendedClass extends BaseClass {

  extendedProp: i32;

  constructor(extendedValue: i32) {
    super(1);

    this.extendedProp = extendedValue;
  }

  add(a: i32): i32 {
    return super.add(a, this.extendedProp + super.instanceProp);
  }
}

export function getStaticProp(): i32 {
  return ExtendedClass.staticProp;
}

export function overloadAdd(value: i32): i32 {
  let extendedClass = new ExtendedClass(value);
  return extendedClass.add(24);
}

#!html
<script>
const log = console.log;
console.log = (...args) => {
  log(...args);
  let str = '';
  args.forEach(arg => {
    if (typeof arg === 'object') {
      str += `${JSON.stringify(arg, null, 2)}<br/>`;
    } else {
      str += `${arg}<br/>`;
    }
  });
  document.body.innerHTML += `<div>Log: ${str}</div>`;
}

loader.instantiate(module_wasm, { /* imports */ })
.then(({ exports }) => {
  console.log(`getStaticProp: ${exports.getStaticProp()}`);
  console.log(`overloadAdd: ${exports.overloadAdd(24)}`);
})
</script>

Handling Null Copy Chapter

Handling Null as a union type for optional return values and simulating try/catch for errors in AssemblyScript

#!runtime=stub
class MyValue {
  value: i32;

  constructor(value: i32) {
    this.value = value;
  }
}

// Using a class type here, as some types are not nullable
function getMyValue(isAble: boolean): MyValue | null {
  let myValue = new MyValue(24);
  if (isAble) {
    return myValue;
  } else {
    return null;
  }
}

export function positiveAddWithMyValue(a: i32): i32 {
  let myValue = getMyValue(a > 0);
  if (myValue == null) {
    return -1;
  } else {
    return a + myValue.value;
  }
}

#!html
<script>
const log = console.log;
console.log = (...args) => {
  log(...args);
  let str = '';
  args.forEach(arg => {
    if (typeof arg == 'object') {
      str += `${JSON.stringify(arg, null, 2)}<br/>`;
    } else {
      str += `${arg}<br/>`;
    }
  });
  document.body.innerHTML += `<div>Log: ${str}</div>`;
}

loader.instantiate(module_wasm, { /* imports */ })
.then(({ exports }) => {
  if(exports.positiveAddWithMyValue(24) > -1) {
    console.log("Add was successful")
  } else {
    console.log("Could not add 24");
  }

  if(exports.positiveAddWithMyValue(-1) > -1) {
  console.log("Add was successful")
  } else {
  console.log("Could not add -1");
  }
});
</script>

Switch Case Copy Chapter

Using switch case statements in AssemblyScript.

::: tip NOTE
Currently, the switch conditions (case values) are implicitly converted to u32, i.e. switching over strings or similar is not yet supported.
:::

#!runtime=stub
export function switchSurprise(a: i32): i32 {
  let response = -1;

  // Using a mix of braces and not using braces
  // to show that both syntaxes are supported here.
  switch (a) {
    case 1:
      response = 100;
      break;
    case 2: {   // Cases can also use braces
      response = 200;
      break;
    }
    case 3:
      // Fall Through to the next case
    case 4:
      response = 400;
      break;
    default: {
      response = 0;
    }
  }

  return response;
}

#!html
<script>
const log = console.log;
console.log = (...args) => {
  log(...args);
  let str = '';
  args.forEach(arg => {
    if (typeof arg == 'object') {
      str += `${JSON.stringify(arg, null, 2)}<br/>`;
    } else {
      str += `${arg}<br/>`;
    }
  });
  document.body.innerHTML += `<div>Log: ${str}</div>`;
}

loader.instantiate(module_wasm, { /* imports */ })
.then(({ exports }) => {
  console.log(`switchSurprise(1) : ${exports.switchSurprise(1)}`);
  console.log(`switchSurprise(2) : ${exports.switchSurprise(2)}`);
  console.log(`switchSurprise(3) : ${exports.switchSurprise(3)}`);
  console.log(`switchSurprise(4) : ${exports.switchSurprise(4)}`);
  console.log(`switchSurprise(57) : ${exports.switchSurprise(57)}`);
});
</script>

Ternary if-else Copy Chapter

Using Ternary if-else in AssemblyScript

#!runtime=stub
export function isTrue(a: i32): i32 {
  let response = a > 0 ? 1 : 0;
  return response;
}

#!html
<script>
const log = console.log;
console.log = (...args) => {
  log(...args);
  let str = '';
  args.forEach(arg => {
    if (typeof arg == 'object') {
      str += `${JSON.stringify(arg, null, 2)}<br/>`;
    } else {
      str += `${arg}<br/>`;
    }
  });
  document.body.innerHTML += `<div>Log: ${str}</div>`;
}

loader.instantiate(module_wasm, { /* imports */ })
.then(({ exports }) => {
  console.log(`is 24 greater than 0? ${exports.isTrue(24) > 0 ? true : false}`);
  console.log(`is -3 greater than 0? ${exports.isTrue(-3) > 0 ? true : false}`);
});
</script>

File: src/stdlib/array.md Copy Chapter

Array

A randomly accessible sequence of values of a generic type.

The Array API is very similar to JavaScript's (MDN), with the notable difference that one must make sure that there are no null values if T is a non-nullable reference type. Example:

var arr = new Array<string>(10)
// arr[0]; // would error 😢
for (let i = 0; i < arr.length; ++i) {
  arr[i] = ""
}
arr[0]; // now it works 😊

Constructor Copy Chapter

• ts Copy

  new Array<T>(capacity?: i32)

  Constructs a new array.

Static members Copy Chapter

• ts Copy

  function isArray<U>(value: U): bool

  Tests if a value is an array.

Instance members Copy Chapter

Fields Copy Section

• ts Copy

  var length: i32

  The length of this array. Setting the length to a value larger than internal capacity will automatically grow the array.

Methods Copy Section

• ts Copy

  function concat(other: Array<T>): Array<T>

  Concatenates the values of this and the other array to a new array, in this order.

• ts Copy

  function copyWithin(target: i32, start: i32, end?: i32): this

  Copies a region of an array's values over the respective values starting at the target location.

• ts Copy

  function every(fn: (value: T, index: i32, array: Array<T>) => bool): bool

  Calls the specified function with every value of the array until it finds the first value for which the function returns false. Returns true if all functions returned true or the array is empty, otherwise false.

• ts Copy

  function fill(value: T, start?: i32, end?: i32): this

  Replaces the values of the array from start inclusive to end exclusive in place with the specified value, returning the array.

• ts Copy

  function filter(fn: (value: T, index: i32, array: Array<T>) => bool): Array<T>

  Calls the specified function with every value of the array, returning a new array with all values for which the function returned true.

• ts Copy

  function findIndex(fn: (value: T, index: i32, array: Array<T>) => bool): i32

  Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning its index. Returns -1 if that's never the case.

• ts Copy

  function flat(): valueof<T>[]

  Flattens an array of arrays to a one-dimensional array. null entries are ignored.

• ts Copy

  function forEach(fn: (value: T, index: i32, array: Array<T>) => void): void

  Calls the specified function with every value of the array.

• ts Copy

  function includes(value: T, fromIndex?: i32): bool

  Tests if the array includes the specified value, optionally providing a starting index.

• ts Copy

  function indexOf(value: T, fromIndex?: i32): i32

  Gets the first index where the specified value can be found in the array. Returns -1 if not found.

• ts Copy

  function join(separator?: string): string

  Concatenates all values of the array to a string, separated by the specified separator (default: ,).

• ts Copy

  function lastIndexOf(value: T, fromIndex?: i32): i32

  Gets the last index where the specified value can be found in the array. Returns -1 if not found.

• ts Copy

  function map<U>(fn: (value: T, index: i32, array: Array<T>) => U): Array<U>

  Calls the specified function with every value of the array, returning a new array of the function's return values.

• ts Copy

  function pop(): T

  Removes and returns the last value of the array. Modifies Array#length.

• ts Copy

  function push(value: T): i32

  Adds one more value to the end of the array and returns the Array's new length. Modifies Array#length.

• ts Copy

  function reduce<U>(
    fn: (acc: U, cur: T, idx: i32, src: Array) => U,
    initialValue: U
  ): U

  Calls the specified reducer function with each value of the array, resulting in a single return value. The respective previous reducer function's return value is remembered in acc, starting with initialValue, becoming the final return value in the process.

• ts Copy

  function reduceRight<U>(
    fn: (acc: U, cur: T, idx: i32, src: Array) => U,
    initialValue: U
  ): U

  Calls the specified reducer function with each value of the array, from right to left, resulting in a single return value. See Array#reduce for the reducer function's signature.

• ts Copy

  function reverse(): this

  Reverses an array's values in place, modifying the array before returning it.

• ts Copy

  function shift(): T

  Removes and returns the first value of the array. Modifies Array#length.

• ts Copy

  function slice(start?: i32, end?: i32): Array<T>

  Returns a shallow copy of the array's values from begin inclusive to end exclusive, as a new array. If omitted, end defaults to the end of the array.

• ts Copy

  function some(fn: (value: T, index: i32, array: Array<T>) => bool): bool

  Calls the specified function with every value of the array until it finds the first value for which the function returns true, returning true. Returns false otherwise or if the array is empty.

• ts Copy

  function sort(fn?: (a: T, b: T) => i32): this

  Sorts the values of the array in place, using the specified comparator function, modifying the array before returning it. The comparator returning a negative value means a < b, a positive value means a > b and 0 means that both are equal. Unlike in JavaScript, where an implicit conversion to strings is performed, the comparator defaults to compare two values of type T.

• ts Copy

  function splice(start: i32, deleteCount?: i32): Array<T>

  Removes deleteCount (defaults to all remaining) values from the array, starting at index start, modifying the array in place, returning the removed values.

• ts Copy

  function toString(): string

  Returns the result of Array#join().

• ts Copy

  function unshift(value: T): i32

  Adds one more value to the start of the array and returns the Array's new length. Modifies Array#length.

File: src/stdlib/arraybuffer.md Copy Chapter

ArrayBuffer

A fixed-length raw binary buffer.

The ArrayBuffer API is exactly as in JavaScript (MDN).

Constructor Copy Chapter

• ts Copy

  new ArrayBuffer(length: i32)

  Constructs a new buffer of the given length in bytes.

Static members Copy Chapter

• ts Copy

  function isView<T>(value: T): bool

  Returns true if value is one of the buffer views, such as one of the typed arrays or a DataView.

Instance members Copy Chapter

Fields Copy Section

• ts Copy

  readonly byteLength: i32

  The buffer's length, in bytes.

Methods Copy Section

• ts Copy

  function slice(begin?: i32, end?: i32): ArrayBuffer

  Returns a copy of this buffer from begin, inclusive, up to end, exclusive.

• ts Copy

  function toString(): string

  Returns a string representation of this buffer.

File: src/stdlib/console.md Copy Chapter

console

An implementation of the console global on top of WASI. Requires a WASI-enabled host and opting into WASI in the entry file with

import "wasi";

Static members Copy Chapter

• ts Copy

  function assert<T>(assertion: T, message: string): void

  Logs message to console if assertion is false-ish.

• ts Copy

  function log(message: string): void

  Outputs message to the console.

• ts Copy

  function debug(message: string): void
  function info(message: string): void
  function warn(message: string): void
  function error(message: string): void

  Outputs message to the console, prefixed with "Debug:", "Info:", "Warning:" or "Error:" respectively.

• ts Copy

  function time(label: string): void

  Starts a new timer using the specified label.

• ts Copy

  function timeLog(label: string): void

  Logs the current value of a timer previously started with console.time.

• ts Copy

  function timeEnd(label: string): void

  Logs the current value of a timer previously started with console.time and discards the timer.

File: src/stdlib/crypto.md Copy Chapter

crypto

An implementation of the crypto global on top of WASI. Requires a WASI-enabled host and opting into WASI in the entry file with

import "wasi";

Static members Copy Chapter

• ts Copy

  function getRandomValues(array: Uint8Array): void

  Fills array with cryptographically strong random values.

File: src/stdlib/dataview.md Copy Chapter

DataView

An interface for working with a raw binary buffer.

The DataView API is exactly as in JavaScript (MDN).

Constructor Copy Chapter

• ts Copy

  new DataView(buffer: ArrayBuffer, byteOffset?: i32, byteLength?: i32)

  Constructs a new DataView on the specified buffer and region.

Instance members Copy Chapter

Fields Copy Section

• ts Copy

  readonly buffer: ArrayBuffer

  The backing buffer.

• ts Copy

  readonly byteLength: i32

  The length of this view from the start of its buffer.

• ts Copy

  readonly byteOffset: i32

  The offset of this view from the start of its buffer.

Methods Copy Section

• ts Copy

  function getFloat32(byteOffset: i32, littleEndian?: bool): f32

  Gets the 32-bit float value at the specified offset from the start of the view.

• ts Copy

  function getFloat64(byteOffset: i32, littleEndian?: bool): f64

  Gets the 64-bit float value at the specified offset from the start of the view.

• ts Copy

  function getInt8(byteOffset: i32): i8

  Gets the signed 8-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getInt16(byteOffset: i32, littleEndian?: bool): i16

  Gets the signed 16-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getInt32(byteOffset: i32, littleEndian?: bool): i32

  Gets the signed 32-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getInt64(byteOffset: i32, littleEndian?: bool): i64

  Gets the signed 64-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getUint8(byteOffset: i32, littleEndian?: bool): u8

  Gets the unsigned 8-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getUint16(byteOffset: i32, littleEndian?: bool): u16

  Gets the unsigned 16-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getUint32(byteOffset: i32, littleEndian?: bool): u32

  Gets the unsigned 32-bit integer value at the specified offset from the start of the view.

• ts Copy

  function getUint64(byteOffset: i32, littleEndian?: bool): u64

  Gets the unsigned 64-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setFloat32(byteOffset: i32, value: f32, littleEndian?: bool): void

  Sets the 32-bit float value at the specified offset from the start of the view.

• ts Copy

  function setFloat64(byteOffset: i32, value: f64, littleEndian?: bool): void

  Sets the 64-bit float value at the specified offset from the start of the view.

• ts Copy

  function setInt8(byteOffset: i32, value: i8): void

  Sets the signed 8-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setInt16(byteOffset: i32, value: i16, littleEndian?: bool): void

  Sets the signed 16-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setInt32(byteOffset: i32, value: i32, littleEndian?: bool): void

  Sets the signed 32-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setInt64(byteOffset: i32, value: i64, littleEndian?: bool): void

  Sets the signed 64-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setUint8(byteOffset: i32, value: u8, littleEndian?: bool): void

  Sets the unsigned 8-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setUint16(byteOffset: i32, value: u16, littleEndian?: bool): void

  Sets the unsigned 16-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setUint32(byteOffset: i32, value: u32, littleEndian?: bool): void

  Sets the unsigned 32-bit integer value at the specified offset from the start of the view.

• ts Copy

  function setUint64(byteOffset: i32, value: u64, littleEndian?: bool): void

  Sets the unsigned 64-bit integer value at the specified offset from the start of the view.

• ts Copy

  function toString(): string

  Returns a string representation of this object.

Endianness defaults to littleEndian = false.

File: src/stdlib/date.md Copy Chapter

Date

Represents timestamps.

The Date API is still preliminary and requires importing the Date object from the host (as Date).

Constructor Copy Chapter

• ts Copy

  new Date(value: i64)

  Constructs a new date object from an UTC timestamp in milliseconds.

Static members Copy Chapter

• ts Copy

  function now(): i64

  Returns the current UTC timestamp in milliseconds.

• ts Copy

  function UTC(
    year: i32,
    month?: i32,
    day?: i32,
    hour?: i32,
    minute?: i32,
    second?: i32,
    millisecond?: i64
  ): i64

  Returns the UTC timestamp in milliseconds of the specified date.

Instance members Copy Chapter

• ts Copy

  function getTime(): i64

  Gets the UTC timestamp of this date in milliseconds.

• ts Copy

  function setTime(value: i64): i64

  Sets the UTC timestamp of this date in milliseconds and returns the timestamp.

File: src/stdlib/error.md Copy Chapter

Error

Represents a runtime error.

The Error API is very similar to JavaScript's (MDN), with some properties not being implemented yet.

Variants Copy Chapter

The Errorclass can also be sub-classed by forwarding message and setting the name property in the overloaded constructor.

Constructor Copy Chapter

• ts Copy

  new Error(message?: string)

  Constructs a new error object.

Instance members Copy Chapter

Fields Copy Section

• ts Copy

  var message: string

  The message of this error.

• ts Copy

  var name: string

  The name of this error. In case of Error, this is "Error".

• ts Copy

  var stack: string

  The stack trace of this error. Not supported yet, hence an empty string.

Methods Copy Section

• ts Copy

  function toString(): string

  Returns a string representation of this error in the form name: message.

File: src/stdlib/globals.md Copy Chapter

Globals

In addition to the general environment with its WebAssembly-focused built-ins, the following global constants and functions are present alongside the standard library's classes.

Constants Copy Chapter

• ts Copy

  const NaN: auto // f32 or f64

  Not a number as a 32-bit or 64-bit float depending on context. Compiles to a constant.

• ts Copy

  const Infinity: auto // f32 or f64

  Positive infinity as a 32-bit or 64-bit float depending on context. Compiles to a constant.

Functions Copy Chapter

• ts Copy

  function isNaN<T>(value: T): bool

  Tests if a 32-bit or 64-bit float is NaN.

• ts Copy

  function isFinite<T>(value: T): bool

  Tests if a 32-bit or 64-bit float is finite, that is not NaN or +/-Infinity.

• ts Copy

  function parseInt(str: string, radix?: i32): i64

  Parses a string to a 64-bit integer. Returns 0 on invalid inputs.

• ts Copy

  function parseFloat(str: string): f64

  Parses a string to a 64-bit float. Returns NaN on invalid inputs.

File: src/stdlib/map.md Copy Chapter

Map

A mapping of generic keys to generic values.

The Map API is very similar to JavaScript's (MDN), with the notable difference that a .get with a key that does not exist results in an error, because undefined cannot be represented. Example:

var map = new Map<i32,string>()

// Because `undefined` cannot be represented if a key is not found, this will error:
var str = map.get(1) // ERROR

// The error can be avoided by first making sure that the key exists, so this works:
var str: string | null = map.has(1) ? map.get(1) : null // OK

Constructor Copy Chapter

• ts Copy

  new Map<K,V>()

  Constructs a new map mapping keys of type K to values of type V.

Instance members Copy Chapter

Fields Copy Section

• ts Copy

  readonly size: i32

  The current number of key-value pairs in this map.

Methods Copy Section

• ts Copy

  function clear(): void

  Clears the map, deleting all key-value pairs.

• ts Copy

  function delete(key: K): bool

  Deletes the key-value pair for the corresponding key. Returns true if the key did exist, otherwise false.

• ts Copy

  function get(key: K): V

  Gets the value corresponding to the specified key. Traps if the key does not exist because "not found" cannot be represented in all cases (use Map#has to check).

• ts Copy

  function has(key: K): bool

  Tests if the specified key exists.

• ts Copy

  function keys(): Array<K>

  Gets the keys contained in this map as an array, in insertion order. This is preliminary while iterators are not supported.

• ts Copy

  function set(key: K, value: V): this

  Sets the value for the specified key. Creates a new key-value pair if the key did not exist.

• ts Copy

  function values(): Array<V>

  Gets the values contained in this map as an array, in insertion order. This is preliminary while iterators are not supported.

• ts Copy

  function toString(): string

  Returns a string representation of this map.

File: src/stdlib/math.md Copy Chapter

Math

Mathematical operations as known from JavaScript.

The Math API is very much like JavaScript's (MDN), with the notable exceptions stated above and rest parameters not being supported yet.

Variants Copy Chapter

Math in AssemblyScript is available in multiple variants.

By default, the global Math object is an alias of NativeMath and Mathf is an alias of NativeMathf .

Using NativeMath Copy Section

This is the default, so no additional configuration options are required. Note, however, that Math.random needs a way to seed the random number generator in this scenario, which WebAssembly alone cannot do, hence a function env.seed() is imported from the host (see also) that must return an f64 value (the seed). The loader and import "WASI" automatically take care of providing the seed function in this scenario, but one can always implement their own, for example to make the PRNG deterministic by returning a fixed seed value.

Using JSMath Copy Section

Where small module size is more important than performance, one can opt to override the default by adding --use Math=JSMath on the command line, essentially aliasing Math with JSMath instead, which maps to an import of the browser's math implementation. Naturally, this option requires importing the browser's Math object as a whole, but does not require seeding / is not seedable. The loader automatically takes care of importing the browser's math in this scenario.

Static members Copy Chapter

The type T below substitutes either f32 or f64 depending on the implementation used.

Constants Copy Section

• ts Copy

  const E: T

  The base of natural logarithms, e, approximately 2.718.

• ts Copy

  const LN2: T

  The natural logarithm of 2, approximately 0.693.

• ts Copy

  const LN10: T

  The natural logarithm of 10, approximately 2.302.

• ts Copy

  const LOG2E: T

  The base 2 logarithm of e, approximately 1.442.

• ts Copy

  const LOG10E: T

  The base 10 logarithm of e, approximately 0.434.

• ts Copy

  const PI: T

  The ratio of the circumference of a circle to its diameter, approximately 3.14159.

• ts Copy

  const SQRT1_2: T

  The square root of 1/2, approximately 0.707.

• ts Copy

  const SQRT2: T

  The square root of 2, approximately 1.414.

Functions Copy Section

• ts Copy

  function abs(x: T): T

  Returns the absolute value of x.

• ts Copy

  function acos(x: T): T

  Returns the arccosine (in radians) of x.

• ts Copy

  function acosh(x: T): T

  Returns the hyperbolic arc-cosine of x.

• ts Copy

  function asin(x: T): T

  Returns the arcsine (in radians) of x.

• ts Copy

  function asinh(x: T): T

  Returns the hyperbolic arcsine of x.

• ts Copy

  function atan(x: T): T

  Returns the arctangent (in radians) of x.

• ts Copy

  function atan2(y: T, x: T): T

  Returns the arctangent of the quotient of its arguments.

• ts Copy

  function atanh(x: T): T

  Returns the hyperbolic arctangent of x.

• ts Copy

  function cbrt(x: T): T

  Returns the cube root of x.

• ts Copy

  function ceil(x: T): T

  Returns the smallest integer greater than or equal to x.

• ts Copy

  function clz32(x: T): T

  Returns the number of leading zero bits in the 32-bit binary representation of x.

• ts Copy

  function cos(x: T): T

  Returns the cosine (in radians) of x.

• ts Copy

  function cosh(x: T): T

  Returns the hyperbolic cosine of x.

• ts Copy

  function exp(x: T): T

  Returns e to the power of x.

• ts Copy

  function expm1(x: T): T

  Returns e to the power of x, minus 1.

• ts Copy

  function floor(x: T): T

  Returns the largest integer less than or equal to x.

• ts Copy

  function fround(x: T): T

  Returns the nearest 32-bit single precision float representation of x.

• ts Copy

  function hypot(value1: T, value2: T): T

  Returns the square root of the sum of squares of its arguments.

• ts Copy

  function imul(a: T, b: T): T

  Returns the result of the C-like 32-bit multiplication of a and b.

• ts Copy

  function log(x: T): T

  Returns the natural logarithm (base e) of x.

• ts Copy

  function log10(x: T): T

  Returns the base 10 logarithm of x.

• ts Copy

  function log1p(x: T): T

  Returns the natural logarithm (base e) of 1 + x.

• ts Copy

  function log2(x: T): T

  Returns the base 2 logarithm of x.

• ts Copy

  function max(value1: T, value2: T): T

  Returns the largest-valued number of its arguments.

• ts Copy

  function min(value1: T, value2: T): T

  Returns the lowest-valued number of its arguments.

• ts Copy

  function pow(base: T, exponent: T): T

  Returns base to the power of exponent.

• ts Copy

  function random(): T

  Returns a pseudo-random number in the range from 0.0 inclusive up to but not including 1.0.

  ::: tip
  Seeding happens automatically in common scenarios. See the notes on using NativeMath above if it doesn't.
  :::

• ts Copy

  function round(x: T): T

  Returns the value of x rounded to the nearest integer.

• ts Copy

  function sign(x: T): T

  Returns the sign of x, indicating whether the number is positive, negative or zero.

• ts Copy

  function signbit(x: T): bool

  Returns whether the sign bit of x is set.

• ts Copy

  function sin(x: T): T

  Returns the sine of x.

• ts Copy

  function sinh(x: T): T

  Returns the hyperbolic sine of x.

• ts Copy

  function sqrt(x: T): T

  Returns the square root of x.

• ts Copy

  function tan(x: T): T

  Returns the tangent of x.

• ts Copy

  function tanh(x: T): T

  Returns the hyperbolic tangent of x.

• ts Copy

  function trunc(x: T): T

  Returns the integer part of x by removing any fractional digits.

Considerations Copy Chapter

The Math implementations are meant as a drop-in replacement for JavaScript's Math so sometimes mimic special JavaScript semantics, like Math.round always rounding towards +Infinity. Also, functions like Math.fround or Math.imul do not return an f32 respectively an i32 as some might expect for the same reason. Hence, depending on the use case, using WebAssembly's math instructions directly can be a worthwhile alternative where portability is not a concern.

File: src/stdlib/number.md Copy Chapter

sidebarDepth: 2 Copy Chapter

Number

Wrappers for basic numerical values.

The Number object has been split into one class per basic WebAssembly type as well. Unlike in JavaScript, these classes cannot have actual instances, hence it works a bit different than JavaScript's (MDN).

Integers Copy Chapter

The name Number below stands for one of the wrappers I8, I16, I32, I64, U8, U16, U32 or U64 representing their respective basic integer type T.

Static members Copy Section

• ts Copy

  const MIN_VALUE: T

  The smallest representable value of the respective basic type. Differs from floating point values where it is the smallest representable positive value.

• ts Copy

  const MAX_VALUE: T

  The largest representable value of the respective basic type.

• ts Copy

  function parseInt(value: string, radix?: i32): T

  Parses a string to a value of the respective basic type.

Instance members Copy Section

• ts Copy

  function toString(radix?: i32): string

  Returns the respective basic value converted to a string.

Floats Copy Chapter

The name Number below stands for one of the wrappers F32 or F64 representing their respective basic floating point type T.

Static members Copy Section