{ "type": "module", "source": "doc/api/wasi.md", "modules": [ { "textRaw": "WebAssembly System Interface (WASI)", "name": "webassembly_system_interface_(wasi)", "introduced_in": "v12.16.0", "stability": 1, "stabilityText": "Experimental", "desc": "

The WASI API provides an implementation of the WebAssembly System Interface\nspecification. WASI gives sandboxed WebAssembly applications access to the\nunderlying operating system via a collection of POSIX-like functions.

\n
'use strict';\nconst fs = require('fs');\nconst { WASI } = require('wasi');\nconst wasi = new WASI({\n  args: process.argv,\n  env: process.env,\n  preopens: {\n    '/sandbox': '/some/real/path/that/wasm/can/access'\n  }\n});\nconst importObject = { wasi_snapshot_preview1: wasi.wasiImport };\n\n(async () => {\n  const wasm = await WebAssembly.compile(fs.readFileSync('./binary.wasm'));\n  const instance = await WebAssembly.instantiate(wasm, importObject);\n\n  wasi.start(instance);\n})();\n
\n

The --experimental-wasi-unstable-preview1 and --experimental-wasm-bigint\nCLI arguments are needed for the previous example to run.

", "classes": [ { "textRaw": "Class: `WASI`", "type": "class", "name": "WASI", "meta": { "added": [ "v12.16.0" ], "changes": [] }, "desc": "

The WASI class provides the WASI system call API and additional convenience\nmethods for working with WASI-based applications. Each WASI instance\nrepresents a distinct sandbox environment. For security purposes, each WASI\ninstance must have its command line arguments, environment variables, and\nsandbox directory structure configured explicitly.

", "methods": [ { "textRaw": "`wasi.start(instance)`", "type": "method", "name": "start", "meta": { "added": [ "v12.16.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`instance` {WebAssembly.Instance}", "name": "instance", "type": "WebAssembly.Instance" } ] } ], "desc": "

Attempt to begin execution of instance as a WASI command by invoking its\n_start() export. If instance does not contain a _start() export, or if\ninstance contains an _initialize() export, then an exception is thrown.

\n

start() requires that instance exports a WebAssembly.Memory named\nmemory. If instance does not have a memory export an exception is thrown.

\n

If start() is called more than once, an exception is thrown.

" } ], "properties": [ { "textRaw": "`wasiImport` {Object}", "type": "Object", "name": "wasiImport", "meta": { "added": [ "v12.16.0" ], "changes": [] }, "desc": "

wasiImport is an object that implements the WASI system call API. This object\nshould be passed as the wasi_snapshot_preview1 import during the instantiation\nof a WebAssembly.Instance.

" } ], "signatures": [ { "params": [ { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`args` {Array} An array of strings that the WebAssembly application will see as command line arguments. The first argument is the virtual path to the WASI command itself. **Default:** `[]`.", "name": "args", "type": "Array", "default": "`[]`", "desc": "An array of strings that the WebAssembly application will see as command line arguments. The first argument is the virtual path to the WASI command itself." }, { "textRaw": "`env` {Object} An object similar to `process.env` that the WebAssembly application will see as its environment. **Default:** `{}`.", "name": "env", "type": "Object", "default": "`{}`", "desc": "An object similar to `process.env` that the WebAssembly application will see as its environment." }, { "textRaw": "`preopens` {Object} This object represents the WebAssembly application's sandbox directory structure. The string keys of `preopens` are treated as directories within the sandbox. The corresponding values in `preopens` are the real paths to those directories on the host machine.", "name": "preopens", "type": "Object", "desc": "This object represents the WebAssembly application's sandbox directory structure. The string keys of `preopens` are treated as directories within the sandbox. The corresponding values in `preopens` are the real paths to those directories on the host machine." }, { "textRaw": "`returnOnExit` {boolean} By default, WASI applications terminate the Node.js process via the `__wasi_proc_exit()` function. Setting this option to `true` causes `wasi.start()` to return the exit code rather than terminate the process. **Default:** `false`.", "name": "returnOnExit", "type": "boolean", "default": "`false`", "desc": "By default, WASI applications terminate the Node.js process via the `__wasi_proc_exit()` function. Setting this option to `true` causes `wasi.start()` to return the exit code rather than terminate the process." } ] } ] } ] } ], "type": "module", "displayName": "WebAssembly System Interface (WASI)" } ] }