wasi.d.ts (7118B)
1 /** 2 * The WASI API provides an implementation of the [WebAssembly System Interface](https://wasi.dev/) specification. WASI gives sandboxed WebAssembly applications access to the 3 * underlying operating system via a collection of POSIX-like functions. 4 * 5 * ```js 6 * import { readFile } from 'node:fs/promises'; 7 * import { WASI } from 'wasi'; 8 * import { argv, env } from 'node:process'; 9 * 10 * const wasi = new WASI({ 11 * args: argv, 12 * env, 13 * preopens: { 14 * '/sandbox': '/some/real/path/that/wasm/can/access' 15 * } 16 * }); 17 * 18 * // Some WASI binaries require: 19 * // const importObject = { wasi_unstable: wasi.wasiImport }; 20 * const importObject = { wasi_snapshot_preview1: wasi.wasiImport }; 21 * 22 * const wasm = await WebAssembly.compile( 23 * await readFile(new URL('./demo.wasm', import.meta.url)) 24 * ); 25 * const instance = await WebAssembly.instantiate(wasm, importObject); 26 * 27 * wasi.start(instance); 28 * ``` 29 * 30 * To run the above example, create a new WebAssembly text format file named `demo.wat`: 31 * 32 * ```text 33 * (module 34 * ;; Import the required fd_write WASI function which will write the given io vectors to stdout 35 * ;; The function signature for fd_write is: 36 * ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written 37 * (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32))) 38 * 39 * (memory 1) 40 * (export "memory" (memory 0)) 41 * 42 * ;; Write 'hello world\n' to memory at an offset of 8 bytes 43 * ;; Note the trailing newline which is required for the text to appear 44 * (data (i32.const 8) "hello world\n") 45 * 46 * (func $main (export "_start") 47 * ;; Creating a new io vector within linear memory 48 * (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string 49 * (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\n' string 50 * 51 * (call $fd_write 52 * (i32.const 1) ;; file_descriptor - 1 for stdout 53 * (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0 54 * (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one. 55 * (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written 56 * ) 57 * drop ;; Discard the number of bytes written from the top of the stack 58 * ) 59 * ) 60 * ``` 61 * 62 * Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` 63 * 64 * ```console 65 * $ wat2wasm demo.wat 66 * ``` 67 * 68 * The `--experimental-wasi-unstable-preview1` CLI argument is needed for this 69 * example to run. 70 * @experimental 71 * @see [source](https://github.com/nodejs/node/blob/v16.20.2/lib/wasi.js) 72 */ 73 declare module "wasi" { 74 interface WASIOptions { 75 /** 76 * An array of strings that the WebAssembly application will 77 * see as command line arguments. The first argument is the virtual path to the 78 * WASI command itself. 79 * @default [] 80 */ 81 args?: string[] | undefined; 82 /** 83 * An object similar to `process.env` that the WebAssembly 84 * application will see as its environment. 85 * @default {} 86 */ 87 env?: object | undefined; 88 /** 89 * This object represents the WebAssembly application's 90 * sandbox directory structure. The string keys of `preopens` are treated as 91 * directories within the sandbox. The corresponding values in `preopens` are 92 * the real paths to those directories on the host machine. 93 */ 94 preopens?: NodeJS.Dict<string> | undefined; 95 /** 96 * By default, WASI applications terminate the Node.js 97 * process via the `__wasi_proc_exit()` function. Setting this option to `true` 98 * causes `wasi.start()` to return the exit code rather than terminate the 99 * process. 100 * @default false 101 */ 102 returnOnExit?: boolean | undefined; 103 /** 104 * The file descriptor used as standard input in the WebAssembly application. 105 * @default 0 106 */ 107 stdin?: number | undefined; 108 /** 109 * The file descriptor used as standard output in the WebAssembly application. 110 * @default 1 111 */ 112 stdout?: number | undefined; 113 /** 114 * The file descriptor used as standard error in the WebAssembly application. 115 * @default 2 116 */ 117 stderr?: number | undefined; 118 } 119 /** 120 * The `WASI` class provides the WASI system call API and additional convenience 121 * methods for working with WASI-based applications. Each `WASI` instance 122 * represents a distinct sandbox environment. For security purposes, each `WASI` instance must have its command-line arguments, environment variables, and 123 * sandbox directory structure configured explicitly. 124 * @since v13.3.0, v12.16.0 125 */ 126 class WASI { 127 constructor(options?: WASIOptions); 128 /** 129 * Attempt to begin execution of `instance` as a WASI command by invoking its `_start()` export. If `instance` does not contain a `_start()` export, or if `instance` contains an `_initialize()` 130 * export, then an exception is thrown. 131 * 132 * `start()` requires that `instance` exports a [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named `memory`. If 133 * `instance` does not have a `memory` export an exception is thrown. 134 * 135 * If `start()` is called more than once, an exception is thrown. 136 * @since v13.3.0, v12.16.0 137 */ 138 start(instance: object): number; // TODO: avoid DOM dependency until WASM moved to own lib. 139 /** 140 * Attempt to initialize `instance` as a WASI reactor by invoking its `_initialize()` export, if it is present. If `instance` contains a `_start()` export, then an exception is thrown. 141 * 142 * `initialize()` requires that `instance` exports a [`WebAssembly.Memory`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory) named `memory`. 143 * If `instance` does not have a `memory` export an exception is thrown. 144 * 145 * If `initialize()` is called more than once, an exception is thrown. 146 * @since v14.6.0, v12.19.0 147 */ 148 initialize(instance: object): void; // TODO: avoid DOM dependency until WASM moved to own lib. 149 /** 150 * `wasiImport` is an object that implements the WASI system call API. This object 151 * should be passed as the `wasi_snapshot_preview1` import during the instantiation 152 * of a [`WebAssembly.Instance`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance). 153 * @since v13.3.0, v12.16.0 154 */ 155 readonly wasiImport: NodeJS.Dict<any>; // TODO: Narrow to DOM types 156 } 157 } 158 declare module "node:wasi" { 159 export * from "wasi"; 160 }