or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

filesystem.mdindex.mdwasi-runtime.md
tile.json

tessl/npm-wasmer--wasi

Isomorphic JavaScript library for interacting with WASI modules across Node.js, browsers, and Deno

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@wasmer/wasi@1.2.x

To install, run

npx @tessl/cli install tessl/npm-wasmer--wasi@1.2.0

index.mddocs/

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 WASI class providing WebAssembly execution environment with system interface support
  • In-Memory Filesystem: MemFS providing 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;
}

WASI Runtime

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;
}

Filesystem

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;
}