# wasmer

**Repository Path**: devoink/wasmer

## Basic Information

- **Project Name**: wasmer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-25
- **Last Updated**: 2025-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Wasmer

将流行的开源库编译为 WebAssembly，让它们能在浏览器和微信小程序中运行。提供 TypeScript 类型支持和易用的 API 封装。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)

## 🎯 项目定位

这不是一个简单的 WASM 加载器，而是一个**开源库 WASM 化工具集**。我们将常用的 C/C++ 开源库（如图片处理、压缩、加密等）编译为 WebAssembly，并提供友好的 TypeScript 接口，让你能在前端项目中直接使用这些强大的库。

## ✨ 特性

- 📚 **开源库集成** - 持续集成更多实用的开源库
- 🌐 **跨平台运行** - 浏览器、微信小程序、Node.js 全支持
- 🎯 **TypeScript 优先** - 完整的类型定义和智能提示
- 📦 **多种格式** - ESM、CommonJS、IIFE 全支持
- 🌲 **Tree-shaking** - 按需加载，减小包体积
- ⚡️ **高性能** - WASM 原生性能 + 智能缓存
- 🛠️ **易于扩展** - 清晰的项目结构，方便添加新的 WASM 模块

## 📋 已集成 / 计划集成的库

### ✅ 已完成

- **Calculator** - 简单的数学运算（示例模块，286B）

### 🚧 开发中

- **zlib** - 数据压缩/解压缩库（下一个开发目标）

### 📝 计划中

- 图片处理（PNG、JPEG 等）
- 图像编解码（WebP、AVIF）
- 加密算法库
- PDF 处理
- 音视频处理
- 更多...

## 📦 安装

```bash
npm install wasmer
# 或
yarn add wasmer
# 或
pnpm add wasmer
```

## 🚀 快速开始

### 使用已封装的业务模块（推荐）

```typescript
import { Calculator } from "wasmer";

// 创建计算器实例
const calc = new Calculator("./wasm/calculator.wasm");

// 使用封装好的方法
const sum = await calc.add(5, 3); // 8
const product = await calc.multiply(4, 6); // 24
```

### 使用工厂函数（自动预加载）

```typescript
import { createCalculator } from "wasmer";

// 工厂函数会自动预加载 WASM 模块
const calc = await createCalculator("./wasm/calculator.wasm");
const result = await calc.add(5, 3); // 更快，因为已预加载
```

### 直接使用 WASM 加载器（底层 API）

```typescript
import { loadWasm } from "wasmer";

// 直接加载并调用 WASM 导出的函数
const wasm = await loadWasm("./wasm/calculator.wasm");
const result = wasm.add(5, 3);
```

> 💡 **提示**：每个集成的开源库都会提供类似的封装类和工厂函数，隐藏底层细节，提供友好的 API。

## 📖 使用场景

### 浏览器（通过 npm）

支持现代打包工具（Webpack、Vite、Rollup 等）：

```typescript
import { loadWasm } from "wasmer";

const wasm = await loadWasm("./wasm/module.wasm");
// 使用 WASM 导出的函数
```

### 浏览器（直接引用）

通过 CDN 直接使用：

```html
<script src="https://unpkg.com/wasmer"></script>
<script>
  const { loadWasm } = Wasmer;

  loadWasm("./wasm/module.wasm").then((wasm) => {
    // 使用 WASM 导出的函数
  });
</script>
```

### 微信小程序

```javascript
const { loadWasm } = require("wasmer");

// 小程序会自动使用 WXWebAssembly
const wasm = await loadWasm("./wasm/module.wasm");
```

### Node.js

```javascript
const { loadWasm } = require("wasmer");

const wasm = await loadWasm("./wasm/module.wasm");
```

## 🛠️ API 文档

### `loadWasm(wasmPath: string): Promise<T>`

直接加载 WASM 模块并返回导出对象。

**参数：**

- `wasmPath`: WASM 文件路径

**返回：**

- Promise，resolve 为 WASM 模块的导出对象

### `WasmLoader<T>`

WASM 加载器类，提供更多控制。

**方法：**

- `load()`: 加载 WASM 模块（带缓存）
- `getExports()`: 获取导出对象
- `call(funcName, ...args)`: 调用 WASM 函数

**示例：**

```typescript
import { WasmLoader } from "wasmer";

const loader = new WasmLoader<{
  add(a: number, b: number): number;
}>("./wasm/add.wasm");

// 预加载
await loader.load();

// 调用函数
const result = await loader.call("add", 5, 3);

// 或获取导出对象直接调用
const exports = await loader.getExports();
const result = exports.add(5, 3);
```

## 📝 TypeScript 支持

完整的 TypeScript 类型定义：

```typescript
import { WasmLoader, loadWasm } from "wasmer";

// 定义你的 WASM 导出类型
interface MyWasmExports {
  add(a: number, b: number): number;
  multiply(a: number, b: number): number;
}

const loader = new WasmLoader<MyWasmExports>("./wasm/math.wasm");
const wasm = await loader.load();

// 完整的类型提示
const sum = wasm.add(1, 2); // number
```

## 🏗️ 项目结构

```
wasmer/
├── src/                      # TypeScript 源码
│   ├── core/                 # 核心基础设施
│   │   ├── loader.ts        # WASM 加载器
│   │   └── index.ts         # 核心模块入口
│   ├── modules/              # 功能模块目录
│   │   └── calculator/      # 计算器模块（完整）
│   │       ├── native/      # C/C++ 源码
│   │       │   ├── add.c
│   │       │   └── README.md
│   │       ├── calculator.ts  # TypeScript 胶水代码
│   │       ├── types.ts     # 类型定义
│   │       └── index.ts     # 模块入口
│   ├── types/                # 全局类型
│   │   └── wechat.d.ts      # 微信小程序类型
│   └── index.ts              # 主入口
├── scripts/                  # 构建脚本
│   ├── build-wasm.sh        # WASM 编译脚本
│   └── build.js             # JS 构建脚本
├── dist/                     # 构建输出
│   ├── esm/                 # ES Modules
│   ├── cjs/                 # CommonJS
│   ├── browser/             # 浏览器 IIFE
│   ├── types/               # TypeScript 类型声明
│   └── wasm/                # 编译后的 WASM 文件
├── examples/                 # 示例项目
│   ├── web/                 # Web 示例
│   └── weapp/               # 微信小程序示例
└── tests/                    # 测试文件
```

### 模块内聚设计

每个功能模块的所有代码（原生代码 + TypeScript 胶水代码 + 构建脚本）都在一个目录下，形成完整独立的功能单元：

```
src/modules/calculator/
├── native/              # C/C++ 源码（编译成 WASM）
│   ├── add.c           # 源代码
│   ├── build.sh        # 模块构建脚本 ✨
│   └── README.md       # 编译说明
├── calculator.ts       # TypeScript 封装
├── types.ts            # 类型定义
└── index.ts            # 对外接口
```

**已完成模块：**

- ✅ calculator（286B）- 基础数学运算

**开发中模块：**

- 🚧 zlib - 数据压缩/解压（开发指南见 `src/modules/zlib/README.md`）

**设计优势：**

- ✅ 模块完全自包含（代码 + 构建）
- ✅ 可以独立构建单个模块
- ✅ 主构建脚本自动发现所有模块
- ✅ 易于添加新模块（已有开发指南）

## 🔧 开发指南

### 安装依赖

```bash
npm install
```

### 构建命令

```bash
# 完整构建（WASM + JS）
npm run build

# 单独构建 WASM
npm run build:wasm

# 单独构建 JavaScript
npm run build:js

# 清理构建产物
npm run clean
```

### 路径别名

项目使用路径别名简化导入：

```typescript
// ✅ 使用别名
import { WasmLoader } from "@core/loader";
import { Calculator } from "@modules/calculator";

// ❌ 不推荐复杂的相对路径
import { WasmLoader } from "../../core/loader";
```

**可用别名：**

- `@/*` → `src/*`
- `@core/*` → `src/core/*`
- `@modules/*` → `src/modules/*`

### 添加新的 WASM 模块

#### 1. 创建模块目录

```bash
mkdir -p src/modules/新模块名/native
```

#### 2. 编写原生代码（C/C++）

在 `src/modules/新模块名/native/` 下添加源文件和构建脚本：

```c
// src/modules/新模块名/native/example.c
int someFunction(int a, int b) {
    return a + b;
}
```

```bash
# src/modules/新模块名/native/build.sh
#!/bin/bash
MODULE_NAME="新模块名"
SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SOURCE_DIR/../../../.." && pwd)"
OUTPUT_FILE="$PROJECT_ROOT/dist/wasm/$MODULE_NAME.wasm"

mkdir -p "$PROJECT_ROOT/dist/wasm"

emcc "$SOURCE_DIR/example.c" \
  -o "$OUTPUT_FILE" \
  --no-entry \
  -s EXPORTED_FUNCTIONS='["_someFunction"]' \
  -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap"]' \
  -s ALLOW_MEMORY_GROWTH=1 \
  -O3

echo "✅ $MODULE_NAME WASM 编译完成"
```

别忘了添加执行权限：

```bash
chmod +x src/modules/新模块名/native/build.sh
```

#### 3. 编写 TypeScript 封装

```typescript
// src/modules/新模块名/types.ts
export interface 新模块WasmExports {
  someFunction(a: number, b: number): number;
}

// src/modules/新模块名/handler.ts
import { WasmLoader } from "@core/loader";
import type { 新模块WasmExports } from "./types";

export class 新模块Handler {
  private loader: WasmLoader<新模块WasmExports>;

  constructor(wasmPath: string) {
    this.loader = new WasmLoader(wasmPath);
  }

  async someMethod(a: number, b: number) {
    return this.loader.call("someFunction", a, b);
  }
}

export async function create新模块Handler(wasmPath: string) {
  const handler = new 新模块Handler(wasmPath);
  await handler.preload();
  return handler;
}

// src/modules/新模块名/index.ts
export { 新模块Handler, create新模块Handler } from "./handler";
export type { 新模块WasmExports } from "./types";
```

#### 4. 导出模块

```typescript
// src/index.ts
export { 新模块Handler, create新模块Handler } from "@/modules/新模块名";
```

#### 5. 构建模块

```bash
# 单独构建这个模块
cd src/modules/新模块名/native
bash build.sh

# 或通过主构建脚本（会自动发现所有模块）
npm run build:wasm
```

主构建脚本 `scripts/build-wasm.sh` 会自动发现并执行所有模块的 `build.sh`，无需手动配置。

### 编译要求

- **Emscripten**：用于将 C/C++ 编译为 WASM
- **Node.js**：>= 14.0.0
- **TypeScript**：用于类型定义和代码编译

## 🗺️ 开发路线图

### v0.1.x - 基础设施 ✅

- [x] 项目架构设计
- [x] WASM 加载器
- [x] TypeScript 类型支持
- [x] 路径别名配置
- [x] 示例：基础计算模块

### v0.2.x - 数据压缩（进行中）

- [ ] 集成 zlib
- [ ] 数据压缩功能
- [ ] 数据解压功能
- [ ] 流式压缩支持
- [ ] TypeScript 封装和类型定义

### v0.3.x - 图片处理

- [ ] 集成图片处理库
- [ ] PNG/JPEG 编解码
- [ ] 图片格式转换
- [ ] 图片压缩和优化

### v0.4.x - 更多功能

- [ ] 图像编解码（WebP、AVIF）
- [ ] 加密算法库
- [ ] PDF 处理
- [ ] 持续扩展...

## 🤝 贡献

欢迎贡献代码！如果你想添加新的开源库集成：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/new-lib`)
3. 提交更改 (`git commit -m 'Add: 集成 XXX 库'`)
4. 推送到分支 (`git push origin feature/new-lib`)
5. 创建 Pull Request

## 📄 开源协议

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关链接

- [仓库地址](https://gitee.com/devoink/wasmer)
- [问题反馈](https://gitee.com/devoink/wasmer/issues)
- [Emscripten 文档](https://emscripten.org/)
- [WebAssembly 官网](https://webassembly.org/)

---

**Made with ❤️ for the WebAssembly community**