适用于神岛的 Wasm 文件便捷解析器

一个轻量且易于使用的工具，用于从各种来源（如 URL、Base64 data URI）加载和运行 WebAssembly (Wasm) 模块。为 JavaScript 和 TypeScript 提供了简单的异步 API。

安装

npm install @dao3fun/wasm-runner

使用方法

首先，请确保你有一个 WebAssembly 模块。

1. 定义导出类型 (TypeScript)

为了在使用 TypeScript 时获得最佳的类型安全体验，建议为你的 Wasm 模块的导出定义一个接口。

// src/types.ts
interface MyWasmExports extends WebAssembly.Exports {
  add(a: number, b: number): number;
}

2. 从 URL 加载

这是从远程服务器加载 Wasm 模块的常用方法。

import WasmRunner from "./WasmRunner";
import { MyWasmExports } from "./types";

async function run() {
  const wasmUrl = "https://cdn.com/my-module.wasm";
  const wasmRunner = await WasmRunner.createFromUrl<MyWasmExports>(wasmUrl);

  const result = wasmRunner.exports.add(5, 10);
  console.log("从 URL 加载的 Wasm 结果:", result); // 输出: 15
}

run();

3. 从 Base64 Data URI 加载 (通过 Webpack)

此方法对于将 Wasm 模块作为 Base64 字符串直接嵌入到你的代码包中非常有用，可以避免额外的网络请求。

a. Webpack 配置

为了让 Webpack 将 .wasm 文件作为 Base64 字符串导入，你需要在 webpack.config.js 中添加一个规则。

// webpack.config.js
module.exports = {
  // ... 其他配置
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: "ts-loader",
        exclude: /node_modules/,
      },
      {
        // 将 .wasm 文件作为 asset/inline 模块处理
        test: /\.wasm$/,
        type: "asset/inline",
      },
    ],
  },
  // ... 其他配置
};

b. 代码实现

配置好 Webpack 后，你就可以直接导入 .wasm 文件了。

// @ts-ignore
import wasmDataSource from "./rust.wasm"; // Webpack 会将此转换为 Base64 data URI
import WasmRunner from "./WasmRunner";
import { MyWasmExports } from "./types";

async function run() {
  const wasmRunner = await WasmRunner.createFromDataURI<MyWasmExports>(
    wasmDataSource
  );

  const result = wasmRunner.exports.add(20, 22);
  console.log("从 Base64 加载的 Wasm 结果:", result); // 输出: 42
}

run();

API 参考

WasmRunner<T>

持有 Wasm 实例及其导出的主类。

WasmRunner.exports: T

从你的 Wasm 模块导出的函数和值，类型为 T。

静态创建方法

WasmRunner.createFromUrl<T>(url: string, importObject?: WebAssembly.Imports): Promise<WasmRunner<T>>

从 URL 获取 Wasm 模块，实例化它，然后返回一个 WasmRunner。

WasmRunner.createFromDataURI<T>(wasmDataSource: string, importObject?: WebAssembly.Imports): Promise<WasmRunner<T>>

解码 base64 data URI，实例化 Wasm 模块，然后返回一个 WasmRunner。