tessl/npm-wasmer--wasi
Isomorphic JavaScript library for interacting with WASI modules across Node.js, browsers, and Deno
—
Wasmer WASI
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.
Package Information
- Package Name: @wasmer/wasi
- Package Type: npm
- Language: TypeScript
- Installation:
npm install @wasmer/wasi
Core Imports
Basic imports for most use cases:
import { init, WASI } from "@wasmer/wasi";Complete imports including filesystem classes:
import { init, WASI, MemFS, JSVirtualFile, WasmerRuntimeError } from "@wasmer/wasi";For CommonJS:
const { init, WASI } = require("@wasmer/wasi");
// Or with filesystem classes:
const { init, WASI, MemFS, JSVirtualFile, WasmerRuntimeError } = require("@wasmer/wasi");For Deno:
import { init, WASI } from "https://deno.land/x/wasm/wasi.ts";
// Or with filesystem classes:
import { init, WASI, MemFS, JSVirtualFile, WasmerRuntimeError } from "https://deno.land/x/wasm/wasi.ts";Basic Usage
import { init, WASI } from "@wasmer/wasi";
// Initialize the WASI library first (required)
await init();
// Create a WASI instance with configuration
const wasi = new WASI({
env: {
HELLO: "world"
},
args: ["program", "arg1", "arg2"]
});
// Load and compile WebAssembly module
const moduleBytes = fetch("https://example.com/program.wasm");
const module = await WebAssembly.compileStreaming(moduleBytes);
// Instantiate the WASI module
await wasi.instantiate(module, {});
// Run the WASI program
const exitCode = wasi.start();
const stdout = wasi.getStdoutString();
console.log(`Output: ${stdout}`);
console.log(`Exit code: ${exitCode}`);Architecture
Wasmer WASI is built around several key components:
- WASI Runtime: Core
WASIclass providing WebAssembly execution environment with system interface support - In-Memory Filesystem:
MemFSproviding sandboxed file operations without requiring host filesystem access - I/O Management: Standard input/output/error handling with both string and binary interfaces
- Cross-Platform Support: Single API working across Node.js, browsers, and Deno environments
- Configuration System: Flexible setup for environment variables, command-line arguments, and filesystem presets
Capabilities
Initialization
Library initialization required before using any WASI functionality. Supports both automatic and manual WebAssembly module loading with async and sync variants.
/**
* Initialize the WASI WebAssembly module asynchronously
* @param input - Optional WebAssembly module input
* @param force - Force re-initialization if already initialized
*/
function init(input?: InitInput | Promise<InitInput>, force?: boolean): Promise<void>;
/**
* Initialize the WASI WebAssembly module synchronously
* @param module - WebAssembly module or bytes
* @returns InitOutput with memory and exported functions
*/
function initSync(module: SyncInitInput): InitOutput;
type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
type SyncInitInput = BufferSource | WebAssembly.Module;
interface InitOutput {
readonly memory: WebAssembly.Memory;
// Additional low-level WebAssembly exports available
}WASI Runtime
Core runtime management for executing WebAssembly modules with WASI support. Handles program lifecycle, I/O operations, and system interface integration.
class WASI {
constructor(config: WasiConfig);
readonly fs: MemFS;
getImports(module: WebAssembly.Module): object;
instantiate(module_or_instance: any, imports?: object): WebAssembly.Instance;
start(instance?: WebAssembly.Instance): number;
getStdoutBuffer(): Uint8Array;
getStdoutString(): string;
getStderrBuffer(): Uint8Array;
getStderrString(): string;
setStdinBuffer(buf: Uint8Array): void;
setStdinString(input: string): void;
free(): void;
}
interface WasiConfig {
args?: string[];
env?: Record<string, string>;
preopens?: Record<string, string>;
fs?: MemFS;
}In-Memory Filesystem
Sandboxed filesystem operations enabling WASI programs to work with files and directories without requiring host filesystem access.
class MemFS {
constructor();
static from_js(jso: any): MemFS;
readDir(path: string): Array<any>;
createDir(path: string): void;
removeDir(path: string): void;
removeFile(path: string): void;
rename(path: string, to: string): void;
metadata(path: string): object;
open(path: string, options: any): JSVirtualFile;
free(): void;
}
class JSVirtualFile {
lastAccessed(): bigint;
lastModified(): bigint;
createdTime(): bigint;
size(): bigint;
setLength(new_size: bigint): void;
read(): Uint8Array;
readString(): string;
write(buf: Uint8Array): number;
writeString(buf: string): number;
flush(): void;
seek(position: number): number;
free(): void;
}Error Handling
/**
* Error class representing aborted WASI instruction execution
*/
class WasmerRuntimeError {
// Error details and message available through standard Error interface
}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.
Types
type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
type SyncInitInput = BufferSource | WebAssembly.Module;
interface InitOutput {
readonly memory: WebAssembly.Memory;
// Additional low-level WebAssembly exports for advanced usage
}
interface WasiConfig {
/** Command-line arguments passed to the WASI executable */
readonly args?: string[];
/** Additional environment variables made available to the WASI executable */
readonly env?: Record<string, string>;
/** Preopened directories mapped from virtual paths to host paths */
readonly preopens?: Record<string, string>;
/** Custom in-memory filesystem instance */
readonly fs?: MemFS;
}Install with Tessl CLI
npx tessl i tessl/npm-wasmer--wasi- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
