Built ins

To provide direct (compile to opcode) access to native WebAssembly operations, the following functions plus a few TS/JS-like constants are provided in the global scope:

Context-sensitive constants

• NaN: f32 | f64
  NaN (not a number) as a 32-bit or 64-bit float depending on context. Compiles to a constant.

• Infinity: f32 | f64
  Positive infinity as a 32-bit or 64-bit float depending on context. Compiles to a constant.

Compile-time type checks

• isInteger<T>(value?: T): bool
  Tests if the specified type or expression is of an integer type and not a reference. Compiles to a constant.

• isFloat<T>(value?: T): bool
  Tests if the specified type or expression is of a float type. Compiles to a constant.

• isSigned<T>(value?: T): bool
  Tests if the specified type or expression can represent negative numbers. Compiles to a constant.

• isReference<T>(value?: T): bool
  Tests if the specified type or expression is of a reference type. Compiles to a constant.

• isString<T>(value?: T): bool
  Tests if the specified type or expression can be used as a string. Compiles to a constant.

• isArray<T>(value?: T): bool
  Tests if the specified type or expression can be used as an array. Compiles to a constant.

• isFunction<T>(value?: T): bool
  Tests if the specified type or expression is of a function type. Compiles to a constant.

• isNullable<T>(value?: T): bool
  Tests if the specified type or expression is of a nullable reference type. Compiles to a constant.

• isDefined(expression: *): bool
  Tests if the specified expression resolves to a defined element. Compiles to a constant.

• isConstant(expression: *): bool
  Tests if the specified expression evaluates to a constant value. Compiles to a constant.

• isManaged<T>(expression: *): bool
  Tests if the specified type or expression is of a managed type. Compiles to a constant. Usually only relevant when implementing custom collection-like classes.

• sizeof<T>(): usize
  Determines the byte size of the specified core or class type. Compiles to a constant.

• offsetof<T>(fieldName?: string): usize
  Determines the offset of the specified field within the given class type. Returns the class type's end offset if field name has been omitted. Compiles to a constant.

• alignof<T>(): usize
  Determines the alignment (log2) of the specified underlying core type. Compiles to a constant.

• idof<T>(): u32
  Obtains the computed unique id of a class type. Usually only relevant when allocating objects or dealing with RTTI externally.

Note that imm* arguments must be compile-time constants (const global or local). Similarly, fieldName arguments must be string literals.

Note that whenever the compiler spots a constant condition, it will automatically eliminate untaken branches and not attempt to compile them. For example, if a generic function is intended to work with both integers and strings with just a few statements differing, a compile-time type check with a constant condition on an if-then-else statement can be utilized to make it behave differently in parts depending on the actual type argument:

function doSomething<T>(a: T): T {
  if (isString<T>()) {
    ... // eliminated if T is not a string
  } else {
    ... // eliminated if T is a string
  }
}

Math

• isNaN<T = f32 | f64>(value: T): bool
  Tests if a 32-bit or 64-bit float is NaN.

• isFinite<T = f32 | f64>(value: T): bool
  Tests if a 32-bit or 64-bit float is finite, that is not NaN or +/-Infinity.

• clz<T = i32 | i64>(value: T): T
  Performs the sign-agnostic count leading zero bits operation on a 32-bit or 64-bit integer. All zero bits are considered leading if the value is zero.

• ctz<T = i32 | i64>(value: T): T
  Performs the sign-agnostic count tailing zero bits operation on a 32-bit or 64-bit integer. All zero bits are considered trailing if the value is zero.

• popcnt<T = i32 | i64>(value: T): T
  Performs the sign-agnostic count number of one bits operation on a 32-bit or 64-bit integer.

• rotl<T = i32 | i64>(value: T, shift: T): T
  Performs the sign-agnostic rotate left operation on a 32-bit or 64-bit integer.

• rotr<T = i32 | i64>(value: T, shift: T): T
  Performs the sign-agnostic rotate right operation on a 32-bit or 64-bit integer.

• abs<T = i32 | i64 | f32 | f64>(value: T): T
  Computes the absolute value of an integer or float.

• max<T = i32 | i64 | f32 | f64>(left: T, right: T): T
  Determines the maximum of two integers or floats. If either operand is NaN, returns NaN.

• min<T = i32 | i64 | f32 | f64>(left: T, right: T): T
  Determines the minimum of two integers or floats. If either operand is NaN, returns NaN.

• ceil<T = f32 | f64>(value: T): T
  Performs the ceiling operation on a 32-bit or 64-bit float.

• floor<T = f32 | f64>(value: T): T
  Performs the floor operation on a 32-bit or 64-bit float.

• copysign<T = f32 | f64>(x: T , y: T): T
  Composes a 32-bit or 64-bit float from the magnitude of x and the sign of y.

• nearest<T = f32 | f64>(value: T): T
  Rounds to the nearest integer tied to even of a 32-bit or 64-bit float.

• reinterpret<T = i32 | i64 | f32 | f64>(value: *): T
  Reinterprets the bits of the specified value as type T. Valid reinterpretations are u32/i32 to/from f32 and u64/i64 to/from f64.

• sqrt<T = f32 | f64>(value: T): T
  Calculates the square root of a 32-bit or 64-bit float.

• trunc<T = f32 | f64>(value: T): T
  Rounds to the nearest integer towards zero of a 32-bit or 64-bit float.

Atomics 🦄

Must be supported by the host and enabled with --enable threads.

• atomic.load<T>(offset: usize, immOffset?: usize): T
  Atomically loads an integer value from memory and returns it.

• atomic.store<T>(offset: usize, value: T, immOffset?: usize): void
  Atomically stores an integer value to memory.

• atomic.add<T>(ptr: usize, value: T, immOffset?: usize): T
  Atomically adds an integer value in memory.

• atomic.sub<T>(ptr: usize, value: T, immOffset?: usize): T
  Atomically subtracts an integer value in memory.

• atomic.and<T>(ptr: usize, value: T, immOffset?: usize): T
  Atomically performs a bitwise AND operation on an integer value in memory.

• atomic.or<T>(ptr: usize, value: T, immOffset?: usize): T
  Atomically performs a bitwise OR operation on an integer value in memory.

• atomic.xor<T>(ptr: usize, value: T, immOffset?: usize): T
  Atomically performs a bitwise XOR operation on an integer value in memory.

• atomic.xchg<T>(ptr: usize, value: T, immOffset?: usize): T
  Atomically exchanges an integer value in memory.

• atomic.cmpxchg<T>(ptr: usize, expected: T, replacement: T, immOffset?: usize): T
  Atomically compares and exchanges an integer value in memory if the condition is met.

• atomic.wait<T>(ptr: usize, expected: T, timeout: i64): AtomicWaitResult
  Performs a wait operation on an address in memory suspending this agent if the integer condition is met. Return values are

  Value	Description
  0	OK: Woken by another agent.
  1	NOT_EQUAL: Loaded value did not match the expected value.
  2	TIMED_OUT: Not woken before the timeout expired.

• atomic.notify(ptr: usize, count: i32): i32
  Performs a notify operation on an address in memory waking up suspended agents.

Memory access

• load<T>(ptr: usize, immOffset?: usize): T
  Loads a value of the specified type from memory. Equivalent to dereferencing a pointer in other languages.

• store<T>(ptr: usize, value: T, immOffset?: usize): void
  Stores a value of the specified type to memory. Equivalent to dereferencing a pointer in other languages when assigning a value.

Control flow

• select<T>(ifTrue: T, ifFalse: T, condition: bool): T
  Selects one of two pre-evaluated values depending on the condition.

• unreachable(): *
  Emits an unreachable operation that results in a runtime error when executed. Both a statement and an expression of any type.

Host operations

• memory.size(): i32
  Returns the current size of the memory in units of pages. One page is 64kb.

• memory.grow(value: i32): i32
  Grows linear memory by a given unsigned delta of pages. One page is 64kb. Returns the previous size of the memory in units of pages or -1 on failure. Note that calling memory.grow where a memory manager is present might break it.

Other

• parseInt(str: string, radix?: i32): i64
  Parses a string to a 64-bit integer. Returns 0 on invalid inputs unlike NaN in JS.

• parseFloat(str: string): f64
  Parses a string to a 64-bit float. Returns NaN on invalid inputs.

• changetype<T>(value: *): T
  Changes the type of a value to another one. Useful for casting class instances to their pointer values and vice-versa.

• assert<T>(isTrueish: T, message?: string): T
  Traps if the specified value is not true-ish, otherwise returns the non-nullable value.

• unchecked(expr: *): *
  Explicitly requests no bounds checks on the provided expression. Useful for array accesses.

• call_indirect<T>(target: u32, ...args: *[]): T
  Emits a call_indirect instruction, calling the specified function in the function table by index with the specified arguments. Does result in a runtime error if the arguments do not match the called function.

• instantiate<T>(...args: *[]): T
  Instantiates a new instance of T using the specified constructor arguments.

Decorators

The following WebAssembly-specific operators can be used to annotate non-TS behavior:

• @global
  Adds an element to the global scope.

• @inline
  Forces inlining of a function.

• @external([moduleName: string,] elementName: string)
  Changes the external name of a declared global or function.

• @operator(token: string)
  Annotates a binary operator overload.

  • @operator.binary(token: string)
    Same as @operator.

  • @operator.prefix(token: string)
    Annotates a unary prefix operator overload.

  • @operator.postfix(token: string)
    Annotates a unary postfix operator overload.