JavaScript interop

1 min read

Use js.global to access browser or Node APIs. Read properties, call methods, and assign values with ordinary Dream syntax. No binding declarations or imports are needed.

fun main(): void {
    let console = js.global.console;
    console.log("Hello from Dream!");
}

Compile for Node with dream --node main.dream, or for the browser with dream --web main.dream. Load the output using the emitted runtime:

import { run } from "./main.node.runtime.js";
await run("./main.wasm");

For a browser, import main.web.runtime.js instead and load it from a page served over HTTP. JavaScript APIs require the corresponding host: browser DOM APIs are unavailable in Node.

Working with values

Dynamic operations return js. Assign a result to a typed variable to convert it to a Dream value.

fun main(): void {
    let text: string = js.global.JSON.stringify(js.object());
    System.println(text);
}

Member names are checked by JavaScript when the operation runs. A missing function, JavaScript exception, or failed conversion is a runtime failure; use try/catch in a JavaScript function when an external API needs recoverable exception handling, and return an explicit result to Dream. For promises, use the async facilities described in The js type.

Pass Dream functions directly as callbacks. See Callbacks for callback identity and supported signatures. The js type covers arrays, objects, conversion, and promises.

Explicit JS extern bindings are internal implementation facilities. Application-facing APIs use js syntax or ordinary Dream functions with bodies. Compiler contributors can read Internal JavaScript bindings.

Native library integration uses C interop or C++ interop.

Use Standalone WASI commands to run command components in a WASI host.