Skip to content
Language reference

Host functions#

declare host("<module>") function declares a function that the JavaScript host provides, for a program built as a WebAssembly module for a JS host (--target wasm32-unknown-unknown: a browser, Node, Deno, Cloudflare Workers). Each declaration is the WebAssembly import (import "<module>" "<name>"), and the JS glue velt_web.mjs passes the function the embedder gives for it (WebAssembly). Any module may declare one: the standard library, a package or a program.

ts
import { HostRef } from "velt/host";

declare host("app") function greet(name: string): string;
declare host("app") function fill(buf: u8[]): u32;
declare host("app") function lookup(key: string): HostRef | null;
declare host("app") function size(value: HostRef): f64;

export function describe(key: string): string {
  const value = lookup(key);
  if (value == null) {
    return greet(key);
  }
  return `${key}: ${size(value)}`;
}

The embedder passes the functions to runVelt by import module:

js
import { runVelt } from "./velt_web.mjs";

const store = new Map([["config", new Blob(["{}"])]]);
const code = await runVelt(fetch("app.wasm"), {
  imports: {
    app: {
      greet: (name) => `hello, ${name}`,
      fill: (buf) => {
        buf.fill(7);
        return buf.length;
      },
      lookup: (key) => store.get(key) ?? null,
      size: (value) => value.size,
    },
  },
});

The glue lists every host function the module imports, and one that imports lacks stops runVelt before main runs, with an error naming it. velt run passes none, so a program that calls host functions needs an embedder.

What crosses#

The declaration's types say what crosses, and the glue converts each value:

Veltthe host function getsit returns
i8, i16, i32, u8, u16, u32a numberan integral number in the type's range
i64, u64, isize, usizea biginta bigint or an integral number, in the type's range
f64a numbera number
boola booleana boolean
stringa stringa string
u8[]a Uint8Array over the array's bytes: what the host writes changes the arraya Uint8Array or an ArrayBuffer, copied into a new array
readonly u8[]a Uint8Array copy of the bytes(as u8[])
HostRefthe JS valueany value but null and undefined (a TypeError)
HostRef | nullthe JS value, or nullany value; null and undefined are null
void(ignored)

A result that doesn't fit the declared type (300 or 1.5 for a u8, "7" for a number, 2n ** 70n for an i64, undefined for a string) is never converted or wrapped: the glue throws a TypeError naming the host function and the value (velt: host function app.small returned 300, which is not a u8), which stops the program.

Strings cross as UTF-8: a string holding a lone surrogate reaches the host with U+FFFD in its place, as TextEncoder writes it. The Uint8Array of a u8[] argument is valid only during the call: keep a copy (buf.slice()) for later, since writing it after the call corrupts the program. A buffer parameter also takes a view of bytes (a typed array, a DataView, xs.subarray(begin, end)) with no copy, as a system function's does (System functions).

Anything else is a compile error that names the parameter and lists what crosses:

tsdoes not compile
declare host("app") function each(xs: i32[]): void;
Text
error: parameter `xs` of host function `each` has type `i32[]`, which cannot cross to the host
  = note: a host function takes integers, `f64`, `bool`, `string`, `u8[]`, `readonly u8[]` (a view of bytes at the call), `HostRef` and `HostRef | null`

So are type parameters, optional, rest and destructured parameters, and a this parameter. A Promise result needs async (below): without it, the declaration is an error (host function `f` returns a `Promise` but is not `async` ). The import module is any string without control characters but velt and the names starting with velt:, which belong to the runtime (declare host("velt:…") outside the standard library is an error). Every declaration of one import (the same module and name, in any modules) has the same types, async included.

Async host functions#

An async host function returns a promise of a result that crosses. The host function returns a JS promise (or any other value, which counts as fulfilled), and await waits for it without blocking the host's thread:

ts
import { IoError } from "velt/io";

declare host("app") async function load(key: string): Promise<string>;
declare host("app") async function pause(ms: u32): Promise<void>;

export async function config(): Promise<string> {
  await pause(10);
  try {
    return await load("config");
  } catch (e) {
    const err: IoError = e;
    return `${err.code}: ${err.message}`; // e.g. "NotFoundError: no config"
  }
}
js
const code = await runVelt(fetch("app.wasm"), {
  imports: {
    app: {
      load: async (key) => {
        const res = await fetch(`/data/${key}`);
        if (!res.ok) throw new DOMException(`no ${key}`, "NotFoundError");
        return res.text();
      },
      pause: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
    },
  },
});
  • The call runs the JS function at once, with the arguments converted as for any host function. An async host function takes readonly u8[] (the host gets a copy) but not u8[], which the host could write after the call, when the program may have freed the bytes.
  • The promise fulfills with the value converted as a result of that type (the table above). It rejects with an IoError whose code is the name of what the JS promise rejected with ("Error" when that is not an object with a name) and whose message is its message (or the value as a string). So does a fulfilled value that doesn't fit the result type.
  • The promise of the call is a promise like any other: kept, it runs on, and a rejection nobody handles is reported; dropped before it settles, the program ignores the outcome.

While its tasks wait for host promises or timers, the program returns to the host: sleep and timers use the host's setTimeout, and runVelt resolves once main and the tasks it waits for are done. Velt's own promises and timers run in the same order as on native targets; a host promise settles in a later turn, as an I/O operation does natively.

HostRef#

velt/host's HostRef is a JS value the host keeps for the program: the glue holds it in a table, and the program holds the slot. Host functions make them (a HostRef result) and take them back (a HostRef parameter gets the value itself). Dropping a HostRef, or [Symbol.dispose](), frees the slot, so the host can collect the value; clone() gives a second HostRef to the same value, with a slot of its own. Passing a disposed HostRef to a host function makes the glue throw.

Targets#

Only a JS host provides host functions. A declaration is allowed for any target, and a call that a build for another target reaches (native, wasm32-wasip1) is the error, so portable code can choose by platform, for example with conditional imports:

Text
error: host function `greet` is not available on x86_64-unknown-linux-gnu
  = note: `main` calls it
  = note: only a JS host (wasm32-unknown-unknown) provides host functions

A standard-library function that calls one is reported at the program's call, as for system functions.

The glue's own modules#

The standard library declares host functions too. velt_web.mjs provides the import module velt:fetch itself, through which fetch uses the host's own fetch; an embedder doesn't pass it. imports: { "velt:fetch": … } replaces it, and fetchHost(fetch), exported by the glue, makes one over another fetch (a host that routes requests itself).

Packages and platforms#

A package for a JavaScript platform ships the JavaScript of the host modules its declare host("m") functions call, in hostModules of its package.velt. velt build --host <package> writes the glue, the platform's entry and those modules next to the program (JavaScript platforms). The cloudflare package's bindings to R2, D1, KV and the cache are such host functions:

ts
import { HostRef } from "velt/host";

/** `bucket.get(key)`: the R2 object with its body, or null. */
export declare host("cloudflare") async function r2Get(
  bucket: string,
  key: string,
): Promise<HostRef | null>;

/** The bytes of a JavaScript `ArrayBuffer` or `Uint8Array`. */
export declare host("cloudflare") function takeBytes(v: HostRef): u8[];

Errors in the host#

A host function that throws stops the program: the exception leaves runVelt (no Velt code runs after it, nothing is dropped), as a trap would. An async host function that throws rejects its promise instead, as a JS async function does.

Edit this page on GitHub