Worker Client

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

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

✨ 特性

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

在线示例

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

🌐 立即体验： 点击访问在线演示

📦 安装

pnpm add @giszhc/worker-client

或

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

🚀 快速开始

基础用法（推荐）

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

🧠 使用方式

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

const result = await worker.heavyTask(40);

👉 等价于：

worker.call('heavyTask', 40);

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

✅ 多方法定义

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（调试用）

console.log(worker.getKey());

✅ 显式 namespace（高级用法）

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

✅ 销毁 Worker

worker.destroy();

📘 API 文档

构造函数

new WorkerClient(methods, options?)

参数说明

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

WorkerClientOptions

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

参数说明

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

💡 timeout 使用示例

// 设置 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 方法（推荐）

const res = await worker.heavyTask(40);

call(method, ...args)

底层调用方式

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

getKey()

获取当前 namespace

const key = worker.getKey();

destroy()

销毁 Worker

worker.destroy();

🔥 进阶示例

CPU 密集型任务

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

批量调用

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

数据处理

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

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

⚠️ 注意事项

1️⃣ 方法会被字符串化

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

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

2️⃣ 不支持外部依赖

import axios from 'axios'; ❌

👉 Worker 内无法访问

3️⃣ 不支持 DOM

document.querySelector() ❌

👉 Worker 无 DOM

4️⃣ 方法命名冲突

避免：

{
  destroy() ❌
}

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

支持：

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

不支持：

• ❌ Function
• ❌ DOM
• ❌ Class instance

🧠 设计理念

为什么不用原生 Worker？

worker.postMessage(...)
worker.onmessage = ...

👉 存在问题：

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

WorkerClient 的解决方案

await worker.task(data);

👉 本质：

👉 Worker RPC（远程函数调用）

🧩 与其他通信库的关系

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

👉 可以统一为：

client.call(...)

🚀 适用场景

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

❓ 常见问题 (FAQ)

Q: 为什么不用 worker.ts？

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

Q: 有类型提示吗？

A: 有，完整支持：

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

Q: 可以用 async 吗？

async task() {
  return 123;
}

👉 ✅ 完全支持

Q: 如何调试？

console.log(worker.getKey());

Q: 支持多个 Worker 吗？

👉 ✅ 支持，每个实例独立

📜 License

MIT

❤️ 总结

WorkerClient 的核心价值：

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