0
# Wasmer WASI
1

2
Wasmer WASI is an isomorphic JavaScript library for interacting with WASI (WebAssembly System Interface) modules across Node.js, browsers, and Deno environments. It provides a unified API for running WebAssembly modules with WASI support, including command-line arguments, environment variables, standard I/O operations, and an in-memory filesystem for sandboxed file operations.
3

4
## Package Information
5

6
- **Package Name**: @wasmer/wasi
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @wasmer/wasi`
10

11
## Core Imports
12

13
Basic imports for most use cases:
14

15
```typescript
16
import { init, WASI } from "@wasmer/wasi";
17
```
18

19
Complete imports including filesystem classes:
20

21
```typescript
22
import { init, WASI, MemFS, JSVirtualFile, WasmerRuntimeError } from "@wasmer/wasi";
23
```
24

25
For CommonJS:
26

27
```javascript
28
const { init, WASI } = require("@wasmer/wasi");
29
// Or with filesystem classes:
30
const { init, WASI, MemFS, JSVirtualFile, WasmerRuntimeError } = require("@wasmer/wasi");
31
```
32

33
For Deno:
34

35
```typescript
36
import { init, WASI } from "https://deno.land/x/wasm/wasi.ts";
37
// Or with filesystem classes:
38
import { init, WASI, MemFS, JSVirtualFile, WasmerRuntimeError } from "https://deno.land/x/wasm/wasi.ts";
39
```
40

41
## Basic Usage
42

43
```typescript
44
import { init, WASI } from "@wasmer/wasi";
45

46
// Initialize the WASI library first (required)
47
await init();
48

49
// Create a WASI instance with configuration
50
const wasi = new WASI({
51
  env: {
52
    HELLO: "world"
53
  },
54
  args: ["program", "arg1", "arg2"]
55
});
56

57
// Load and compile WebAssembly module
58
const moduleBytes = fetch("https://example.com/program.wasm");
59
const module = await WebAssembly.compileStreaming(moduleBytes);
60

61
// Instantiate the WASI module
62
await wasi.instantiate(module, {});
63

64
// Run the WASI program
65
const exitCode = wasi.start();
66
const stdout = wasi.getStdoutString();
67

68
console.log(`Output: ${stdout}`);
69
console.log(`Exit code: ${exitCode}`);
70
```
71

72
## Architecture
73

74
Wasmer WASI is built around several key components:
75

76
- **WASI Runtime**: Core `WASI` class providing WebAssembly execution environment with system interface support
77
- **In-Memory Filesystem**: `MemFS` providing sandboxed file operations without requiring host filesystem access
78
- **I/O Management**: Standard input/output/error handling with both string and binary interfaces
79
- **Cross-Platform Support**: Single API working across Node.js, browsers, and Deno environments
80
- **Configuration System**: Flexible setup for environment variables, command-line arguments, and filesystem presets
81

82
## Capabilities
83

84
### Initialization
85

86
Library initialization required before using any WASI functionality. Supports both automatic and manual WebAssembly module loading with async and sync variants.
87

88
```typescript { .api }
89
/**
90
 * Initialize the WASI WebAssembly module asynchronously
91
 * @param input - Optional WebAssembly module input
92
 * @param force - Force re-initialization if already initialized
93
 */
94
function init(input?: InitInput | Promise<InitInput>, force?: boolean): Promise<void>;
95

96
/**
97
 * Initialize the WASI WebAssembly module synchronously
98
 * @param module - WebAssembly module or bytes
99
 * @returns InitOutput with memory and exported functions
100
 */
101
function initSync(module: SyncInitInput): InitOutput;
102

103
type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
104
type SyncInitInput = BufferSource | WebAssembly.Module;
105

106
interface InitOutput {
107
  readonly memory: WebAssembly.Memory;
108
  // Additional low-level WebAssembly exports available
109
}
110
```
111

112
### WASI Runtime
113

114
Core runtime management for executing WebAssembly modules with WASI support. Handles program lifecycle, I/O operations, and system interface integration.
115

116
```typescript { .api }
117
class WASI {
118
  constructor(config: WasiConfig);
119
  readonly fs: MemFS;
120
  
121
  getImports(module: WebAssembly.Module): object;
122
  instantiate(module_or_instance: any, imports?: object): WebAssembly.Instance;
123
  start(instance?: WebAssembly.Instance): number;
124
  
125
  getStdoutBuffer(): Uint8Array;
126
  getStdoutString(): string;
127
  getStderrBuffer(): Uint8Array;
128
  getStderrString(): string;
129
  setStdinBuffer(buf: Uint8Array): void;
130
  setStdinString(input: string): void;
131
  free(): void;
132
}
133

134
interface WasiConfig {
135
  args?: string[];
136
  env?: Record<string, string>;
137
  preopens?: Record<string, string>;
138
  fs?: MemFS;
139
}
140
```
141

142
[WASI Runtime](./wasi-runtime.md)
143

144
### In-Memory Filesystem
145

146
Sandboxed filesystem operations enabling WASI programs to work with files and directories without requiring host filesystem access.
147

148
```typescript { .api }
149
class MemFS {
150
  constructor();
151
  static from_js(jso: any): MemFS;
152
  
153
  readDir(path: string): Array<any>;
154
  createDir(path: string): void;
155
  removeDir(path: string): void;
156
  removeFile(path: string): void;
157
  rename(path: string, to: string): void;
158
  metadata(path: string): object;
159
  open(path: string, options: any): JSVirtualFile;
160
  free(): void;
161
}
162

163
class JSVirtualFile {
164
  lastAccessed(): bigint;
165
  lastModified(): bigint;
166
  createdTime(): bigint;
167
  size(): bigint;
168
  setLength(new_size: bigint): void;
169
  read(): Uint8Array;
170
  readString(): string;
171
  write(buf: Uint8Array): number;
172
  writeString(buf: string): number;
173
  flush(): void;
174
  seek(position: number): number;
175
  free(): void;
176
}
177
```
178

179
[Filesystem](./filesystem.md)
180

181
## Error Handling
182

183
```typescript { .api }
184
/**
185
 * Error class representing aborted WASI instruction execution
186
 */
187
class WasmerRuntimeError {
188
  // Error details and message available through standard Error interface
189
}
190
```
191

192
WASI programs may exit with non-zero exit codes to indicate errors. Always check the return value of `wasi.start()` and examine stderr output for diagnostic information.
193

194
## Types
195

196
```typescript { .api }
197
type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
198
type SyncInitInput = BufferSource | WebAssembly.Module;
199

200
interface InitOutput {
201
  readonly memory: WebAssembly.Memory;
202
  // Additional low-level WebAssembly exports for advanced usage
203
}
204

205
interface WasiConfig {
206
  /** Command-line arguments passed to the WASI executable */
207
  readonly args?: string[];
208
  /** Additional environment variables made available to the WASI executable */
209
  readonly env?: Record<string, string>;
210
  /** Preopened directories mapped from virtual paths to host paths */
211
  readonly preopens?: Record<string, string>;
212
  /** Custom in-memory filesystem instance */
213
  readonly fs?: MemFS;
214
}
215
```