WASI Runtime

/**
 * WASI execution environment for WebAssembly modules
 */
class WASI {
  /**
   * Create a new WASI instance with configuration
   * @param config - WASI configuration options
   */
  constructor(config: WasiConfig);
  
  /** Access to the in-memory filesystem */
  readonly fs: MemFS;
  
  /**
   * Get WASI imports for a WebAssembly module
   * @param module - WebAssembly module to get imports for
   * @returns Object containing WASI imports for instantiation
   */
  getImports(module: WebAssembly.Module): object;
  
  /**
   * Instantiate a WebAssembly module with WASI support
   * @param module_or_instance - WebAssembly module or existing instance
   * @param imports - Additional imports to merge with WASI imports
   * @returns WebAssembly instance ready for execution
   */
  instantiate(module_or_instance: any, imports?: object): WebAssembly.Instance;
  
  /**
   * Start WASI program execution
   * @param instance - Optional WebAssembly instance (if not provided, uses last instantiated)
   * @returns Exit code from the WASI program (0 for success)
   */
  start(instance?: WebAssembly.Instance): number;
  
  /**
   * Get stdout buffer and clear it
   * @returns Stdout content as Uint8Array
   */
  getStdoutBuffer(): Uint8Array;
  
  /**
   * Get stdout as string and clear it
   * @returns Stdout content as UTF-8 string
   */
  getStdoutString(): string;
  
  /**
   * Get stderr buffer and clear it
   * @returns Stderr content as Uint8Array
   */
  getStderrBuffer(): Uint8Array;
  
  /**
   * Get stderr as string and clear it
   * @returns Stderr content as UTF-8 string
   */
  getStderrString(): string;
  
  /**
   * Set stdin buffer for program input
   * @param buf - Input data as Uint8Array
   */
  setStdinBuffer(buf: Uint8Array): void;
  
  /**
   * Set stdin string for program input
   * @param input - Input data as UTF-8 string
   */
  setStdinString(input: string): void;
  
  /**
   * Free WebAssembly resources
   * Call when done with the WASI instance to clean up memory
   */
  free(): void;
}

import { init, WASI } from "@wasmer/wasi";

await init();

// Basic WASI execution
const wasi = new WASI({
  args: ["program", "--verbose"],
  env: { DEBUG: "1" }
});

const module = await WebAssembly.compileStreaming(fetch("program.wasm"));
await wasi.instantiate(module, {});
const exitCode = wasi.start();

if (exitCode !== 0) {
  console.error("Program failed:", wasi.getStderrString());
} else {
  console.log("Output:", wasi.getStdoutString());
}

// Advanced usage with custom imports
const customImports = {
  env: {
    custom_function: () => console.log("Called from WASM!")
  }
};

const wasiImports = wasi.getImports(module);
const instance = await WebAssembly.instantiate(module, {
  ...wasiImports,
  ...customImports
});

wasi.instantiate(instance);
wasi.start();

/**
 * Configuration options for WASI instance
 */
interface WasiConfig {
  /** 
   * Command-line arguments passed to the WASI executable
   * First argument is typically the program name
   */
  readonly args?: string[];
  
  /** 
   * Additional environment variables made available to the WASI executable
   * Merged with any existing environment
   */
  readonly env?: Record<string, string>;
  
  /** 
   * Preopened directories mapped from virtual paths to host paths
   * Currently used for configuration but may have limited host access in browser environments
   */
  readonly preopens?: Record<string, string>;
  
  /** 
   * Custom in-memory filesystem instance
   * If not provided, a new empty filesystem is created
   */
  readonly fs?: MemFS;
}

// Basic configuration
const basicConfig = {
  args: ["myprogram"],
  env: {
    HOME: "/home/user",
    PATH: "/usr/bin"
  }
};

// With custom filesystem
import { MemFS } from "@wasmer/wasi";
const fs = new MemFS();
fs.createDir("/app");
fs.createDir("/data");

const advancedConfig = {
  args: ["dataprocessor", "--input", "/data/input.txt"],
  env: {
    WORKER_THREADS: "4",
    LOG_LEVEL: "info"
  },
  fs: fs
};

const wasi = new WASI(advancedConfig);

// Output retrieval (these methods flush/clear the buffers)
getStdoutBuffer(): Uint8Array;
getStdoutString(): string;
getStderrBuffer(): Uint8Array;
getStderrString(): string;

// Input provision
setStdinBuffer(buf: Uint8Array): void;
setStdinString(input: string): void;

// Providing input to a program
wasi.setStdinString("Hello, WASI program!\nThis is input data.\n");

// Or using binary data
const binaryInput = new TextEncoder().encode("Binary input data");
wasi.setStdinBuffer(binaryInput);

// Running and capturing output
const exitCode = wasi.start();

// Get output (these calls clear the buffers)
const stdout = wasi.getStdoutString();
const stderr = wasi.getStderrString();

console.log("Program output:", stdout);
if (stderr) {
  console.error("Program errors:", stderr);
}

// For binary output handling
const stdoutBytes = wasi.getStdoutBuffer();
const stderrBytes = wasi.getStderrBuffer();

/**
 * Error class representing aborted WASI instruction execution
 */
class WasmerRuntimeError extends Error {
  // Standard Error properties available
}

try {
  await init();
  const wasi = new WASI({ args: ["program"] });
  
  const module = await WebAssembly.compileStreaming(fetch("program.wasm"));
  await wasi.instantiate(module, {});
  
  const exitCode = wasi.start();
  
  if (exitCode !== 0) {
    const stderr = wasi.getStderrString();
    throw new Error(`Program exited with code ${exitCode}: ${stderr}`);
  }
  
} catch (error) {
  if (error instanceof WasmerRuntimeError) {
    console.error("WASI runtime error:", error.message);
  } else {
    console.error("General error:", error);
  }
}