npm package: @giszhc/worker-client
Description: 一个 零配置、类型安全、函数式调用 的 Web Worker 通信库，让你可以像调用普通函数一样使用 Worker。
Author: giszhc
Latest version: 0.0.1

# Worker Client

一个 **零配置、类型安全、函数式调用** 的 Web Worker 通信库，让你可以像调用普通函数一样使用 Worker。

本库专注于 **简化 Web Worker 使用体验**，无需创建单独的 worker 文件，自动完成通信封装。

---

## ✨ 特性

* 🚀 **零配置 Worker** - 无需创建 `worker.ts`
* 🧠 **函数式调用** - `worker.xxx()` 直接调用
* 🛡️ **类型安全** - 完整 TypeScript 推断（参数 + 返回值）
* 🔄 **Promise 支持** - 原生 async/await
* 📦 **自动通信封装** - 无需 postMessage
* 🔐 **namespace 隔离** - 多实例安全通信
* ⚡ **高性能** - 运行在 Worker 线程，不阻塞主线程
* 🧩 **轻量无依赖**

---

## 在线示例

我们提供了一个功能完整的在线演示页面，您可以直接在浏览器中体验所有功能：

**🌐 立即体验：** [点击访问在线演示](https://giszhc.github.io/worker-client/example)

---

## 📦 安装

```bash
pnpm add @giszhc/worker-client
```

或

```bash
npm install @giszhc/worker-client
yarn add @giszhc/worker-client
```

---

## 🚀 快速开始

### 基础用法（推荐）

```ts
import { WorkerClient } from '@giszhc/worker-client';

type WorkerMethods = {
  heavyTask(n: number): number;
};

const worker = new WorkerClient<WorkerMethods>({
  heavyTask(n) {
    function fib(x: number): number {
      return x <= 1 ? x : fib(x - 1) + fib(x - 2);
    }
    return fib(n);
  }
});

const result = await worker.heavyTask(40);

console.log('计算结果:', result);
```

---

## 🧠 使用方式

---

### ✅ 函数式调用（核心特性）

```ts
const result = await worker.heavyTask(40);
```

👉 等价于：

```ts
worker.call('heavyTask', 40);
```

但更推荐前者（类型更安全、更优雅）

---

### ✅ 多方法定义

```ts
type WorkerMethods = {
  add(a: number, b: number): number;
  greet(name: string): string;
};

const worker = new WorkerClient<WorkerMethods>({
  add(a, b) {
    return a + b;
  },
  greet(name) {
    return `Hello ${name}`;
  }
});

await worker.add(1, 2);       // number
await worker.greet('张三');   // string
```

---

### ✅ 获取 namespace（调试用）

```ts
console.log(worker.getKey());
```

---

### ✅ 显式 namespace（高级用法）

```ts
const worker = new WorkerClient(
  {
    task(n: number) {
      return n * 2;
    }
  },
  {
    namespace: 'my-worker:v1'
  }
);
```

---

### ✅ 销毁 Worker

```ts
worker.destroy();
```

---

## 📘 API 文档

---

### 构造函数

```ts
new WorkerClient(methods, options?)
```

#### 参数说明

| 参数      | 类型                       | 必填  | 说明            |
| ------- | ------------------------ | --- | ------------- |
| methods | Record<string, Function> | ✅ 是 | Worker 内执行的方法 |
| options | WorkerClientOptions      | ❌ 否 | 配置项           |

---

### WorkerClientOptions

```ts
interface WorkerClientOptions {
  namespace?: string;
  timeout?: number;
}
```

#### 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| namespace | `string` | ❌ 否 | 自动生成 | 命名空间，用于隔离不同 Worker 实例 |
| timeout | `number` | ❌ 否 | `5000` | 超时时间（毫秒），Worker 方法调用超过此时间将抛出错误 |

---

### 💡 timeout 使用示例

```ts
// 设置 3 秒超时
const worker = new WorkerClient(
  {
    heavyTask(n: number) {
      function fib(x: number): number {
        return x <= 1 ? x : fib(x - 1) + fib(x - 2);
      }
      return fib(n);
    }
  },
  {
    timeout: 3000 // 3 秒后超时
  }
);

try {
  const result = await worker.heavyTask(50);
  console.log('计算结果:', result);
} catch (error) {
  if (error.message.includes('timeout')) {
    console.error('⏱️ 计算超时，任务耗时过长');
  } else {
    console.error('❌ 其他错误:', error);
  }
}
```

👉 **注意**：超时后会抛出错误，建议配合 `try-catch` 使用

---

### 实例方法

---

#### worker.xxx(...args)

调用 Worker 方法（推荐）

```ts
const res = await worker.heavyTask(40);
```

---

#### call(method, ...args)

底层调用方式

```ts
const res = await worker.call('heavyTask', 40);
```

---

#### getKey()

获取当前 namespace

```ts
const key = worker.getKey();
```

---

#### destroy()

销毁 Worker

```ts
worker.destroy();
```

---

## 🔥 进阶示例

---

### CPU 密集型任务

```ts
const worker = new WorkerClient({
  fibonacci(n: number) {
    function fib(x: number): number {
      return x <= 1 ? x : fib(x - 1) + fib(x - 2);
    }
    return fib(n);
  }
});

await worker.fibonacci(45);
```

👉 不会阻塞 UI

---

### 批量调用

```ts
const results = await Promise.all([
  worker.heavyTask(35),
  worker.heavyTask(36),
  worker.heavyTask(37)
]);
```

---

### 数据处理

```ts
const worker = new WorkerClient({
  process(data: number[]) {
    return data.map(x => x * 2);
  }
});

const result = await worker.process([1, 2, 3]);
```

---

## ⚠️ 注意事项

---

### 1️⃣ 方法会被字符串化

```ts
methods: {
  task() {
    return externalVar; // ❌ 无法访问
  }
}
```

👉 原因：函数通过 `toString()` 注入 Worker

---

### 2️⃣ 不支持外部依赖

```ts
import axios from 'axios'; ❌
```

👉 Worker 内无法访问

---

### 3️⃣ 不支持 DOM

```ts
document.querySelector() ❌
```

👉 Worker 无 DOM

---

### 4️⃣ 方法命名冲突

避免：

```ts
{
  destroy() ❌
}
```

---

### 5️⃣ 数据必须可结构化克隆

支持：

* ✅ Object / Array
* ✅ Number / String
* ✅ ArrayBuffer / TypedArray

不支持：

* ❌ Function
* ❌ DOM
* ❌ Class instance

---

## 🧠 设计理念

---

### 为什么不用原生 Worker？

```ts
worker.postMessage(...)
worker.onmessage = ...
```

👉 存在问题：

* ❌ 使用复杂
* ❌ 无类型
* ❌ 无 request/response
* ❌ 难维护

---

### WorkerClient 的解决方案

```ts
await worker.task(data);
```

👉 本质：

# 👉 Worker RPC（远程函数调用）

---

## 🧩 与其他通信库的关系

| 库             | 作用    |
| ------------- | ----- |
| iframe-client | 跨页面通信 |
| socket-client | 网络通信  |
| worker-client | 多线程通信 |

👉 可以统一为：

```ts
client.call(...)
```

---

## 🚀 适用场景

* 大数据计算
* 图像处理
* JSON 解析
* 加密/解密
* CPU 密集型任务

---

## ❓ 常见问题 (FAQ)

---

### Q: 为什么不用 worker.ts？

A: 本库使用 **Blob Worker** 自动生成，无需额外文件。

---

### Q: 有类型提示吗？

A: 有，完整支持：

* 参数类型推断
* 返回值推断

---

### Q: 可以用 async 吗？

```ts
async task() {
  return 123;
}
```

👉 ✅ 完全支持

---

### Q: 如何调试？

```ts
console.log(worker.getKey());
```

---

### Q: 支持多个 Worker 吗？

👉 ✅ 支持，每个实例独立

---

## 📜 License

MIT

---

## ❤️ 总结

WorkerClient 的核心价值：

> 👉 **让 Web Worker 从“难用 API”变成“函数调用工具”**

---