# 5. JavaScript API Reference

The futhark-wasm and futhark-wasm-multicore compilers produce JavaScript wrapper code to allow JavaScript programs to invoke the generated WebAssembly code. This chapter describes the API exposed by the wrapper.

First a warning: the JavaScript API is experimental. It may change incompatibly even in minor versions of the compiler.

A Futhark program `futlib.fut` compiled with a WASM backend as a library with the `--library` command line option produces four files:

- `futlib.c`, `futlib.h`: Implementation and header C files generated by the compiler, similar to `futhark c`. You can delete these - they are not needed at run-time.

- `futlib.class.js`: An intermediate build artifact. Feel free to delete it.

- `futlib.wasm`: A compiled WebAssembly module, which must be

    present at runtime.

- `futlib.mjs`: An ES6 module that can can be imported by other JavaScript code, and implements the API given in the following.

The module exports a function, `newFutharkContext`, which is a factory function that returns a Promise producing a `FutharkContext` instance (see below). A simple usage example:

    import { newFutharkContext } from './futlib.mjs';
    var fc;
    newFutharkContext().then(x => fc = x);

## 5.1. General concerns

Memory management is completely manual, as JavaScript does not support finalizers that could let Futhark hook into the garbage collector. You are responsible for eventually freeing all objects produced by the API, using the appropriate methods.

## 5.2. FutharkContext

FutharkContext is a class that contains information about the context and configuration from the C API. It has methods for invoking the Futhark entry points and creating FutharkArrays on the WebAssembly heap.

newFutharkContext()

  Asynchronously create a new `FutharkContext` object.

class FutharkContext()

  A bookkeeping class representing an instance of a Futhark program. Do not directly invoke its constructor - always use the `newFutharkContext()` factory function.

FutharkContext.free()

  Frees all memory created by the `FutharkContext` object. Should be called when the `FutharkContext` is done being used. It is an error use a `FutharkArray` or `FutharkOpaque` after the `FutharkContext` on which they were defined has been freed.

## 5.3. Values

Numeric types `u8`, `u16`, `u32`, `i8`, `i16`, `i32`, `f32`, and `f64` are mapped to JavaScript’s standard number type. 64-bit integers `u64`, and `i64` are mapped to `BigInt`. `bool` is mapped to JavaScript’s `boolean` type. Arrays are represented by the `FutharkArray`. complex types (records, nested tuples, etc) are represented by the `FutharkOpaque` class.

## 5.4. FutharkArray

`FutharkArray` has the following API

FutharkArray.toArray()

  Returns a nested JavaScript array

FutharkArray.toTypedArray()

  Returns a flat typed array of the underlying data.

FutharkArray.shape()

  Returns the shape of the FutharkArray as an array of BigInts.

FutharkArray.free()

  Frees the memory used by the FutharkArray class

`FutharkContext` also contains two functions for creating `FutharkArrays` from JavaScript arrays, and typed arrays for each array type that appears in an entry point. All array types share similar API methods on the `FutharkContext`, which is illustrated here for the case of the type `[]i32`.

FutharkContext.new_i32_1d_from_jsarray(jsarray)

  Creates and returns a one-dimensional `i32` `FutharkArray` representing the JavaScript array jsarray

FutharkContext.new_i32_1d(array, dim1)

  Creates and returns a one-dimensional `i32` `FutharkArray` representing the typed array of array, with the size given by dim1.

## 5.5. FutharkOpaque

Complex types (records, nested tuples, etc) are represented by `FutharkOpaque`. It has no use outside of being accepted and returned by entry point functions. For this reason the method only has one function for freeing the memory when `FutharkOpaque` is no longer used.

FutharkOpaque.free()

  Frees memory used by FutharkOpaque. Should be called when Futhark Opaque is no longer used.

## 5.6. Entry Points

Each entry point in the compiled futhark program has an entry point method on the FutharkContext

FutharkContext.<entry_point_name>(in1, ..., inN)

  The entry point function taking the N arguments of the Futhark entry point function, and returns the result. If the result is a tuple the return value is an array.