@hile/message-worker-thread 1.0.0

package/README.md

@@ -0,0 +1,130 @@
+# @hile/message-worker-thread
+
+基于 `@hile/message-modem` 的 Node.js Worker Threads 通信抽象实现。让主线程与 Worker 线程之间的请求/响应通信像调用函数一样简单。
+
+## 安装
+
+```bash
+pnpm add @hile/message-worker-thread
+```
+
+## 核心特性
+
+- **双端支持** — 主线程传入 `Worker` 或 `MessagePort`，Worker 线程端零配置
+- **继承模式** — 继承 `MessageWorkerThread` 并实现 `exec` 方法
+- **请求/响应** — 继承 `MessageModem` 的全部能力
+- **超时控制** — 默认 30 秒，可按请求自定义
+- **主动中止** — `abort()` 取消等待并通知对端
+- **错误传播** — `Exception` 带 status 透传，普通 Error 映射为 500
+- **资源清理** — `dispose()` 移除监听，避免内存泄漏
+
+## 快速开始
+
+### 第一步：定义子类
+
+```typescript
+import { MessageWorkerThread } from '@hile/message-worker-thread';
+import { Exception } from '@hile/message-modem';
+
+class ComputeWorker extends MessageWorkerThread {
+  protected async exec(data: any): Promise<any> {
+    switch (data?.action) {
+      case 'compute':
+        return data.value * 2;
+      case 'restricted':
+        throw new Exception(403, 'not allowed');
+      default:
+        return data;
+    }
+  }
+}
+```
+
+### 第二步：主线程
+
+```typescript
+import { Worker } from 'node:worker_threads';
+
+class MainThread extends MessageWorkerThread {
+  protected async exec(data: any): Promise<any> {
+    return { reply: 'from main', query: data };
+  }
+}
+
+const worker = new Worker('./worker.js');
+const wt = new MainThread(worker);
+
+const result = await wt.request({ action: 'compute', value: 42 }).response();
+console.log(result); // 84
+
+wt.dispose();
+await worker.terminate();
+```
+
+### 第三步：Worker 线程（worker.js）
+
+```typescript
+const wt = new ComputeWorker(); // 无参数 → 自动使用 parentPort
+```
+
+## API
+
+### `MessageWorkerThread`（抽象类）
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `constructor` | `new SubClass(port?: Worker \| MessagePort)` | 主线程传 Worker/MessagePort；Worker 线程不传参数 |
+| `exec` | `protected abstract exec(data: any): Promise<any>` | 子类实现：处理对端请求 |
+| `request` | `request<T>(data: T, timeout?: number)` | 向对端发送请求，返回 `{ abort, response }` |
+| `dispose` | `dispose(): void` | 移除消息监听，释放资源 |
+
+### `request` 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `abort` | `() => void` | 中止请求 |
+| `response` | `<U>() => Promise<U>` | 等待对端响应 |
+
+## 也可以用 MessageChannel
+
+```typescript
+import { MessageChannel } from 'node:worker_threads';
+
+const { port1, port2 } = new MessageChannel();
+const side1 = new MySide(port1);
+const side2 = new MySide(port2);
+
+const result = await side1.request('hello').response();
+```
+
+## 超时与中止
+
+```typescript
+import { AbortException, Exception } from '@hile/message-modem';
+
+// 5 秒超时
+const result = await wt.request(data, 5000).response();
+
+// 主动中止
+const req = wt.request(data);
+setTimeout(() => req.abort(), 3000);
+try {
+  await req.response();
+} catch (e) {
+  if (e instanceof AbortException) {
+    console.log('请求被中止或超时');
+  } else if (e instanceof Exception) {
+    console.log(`远端错误 [${e.status}]: ${e.message}`);
+  }
+}
+```
+
+## 注意事项
+
+- `MessageWorkerThread` 是 **抽象类**，不能直接实例化
+- Worker 线程端不传参数时，必须在 Worker 线程内运行（`parentPort` 可用）
+- 使用完毕后务必 `dispose()` + `worker.terminate()`
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: message-worker-thread
+description: Code generation and contribution rules for @hile/message-worker-thread. Use when editing this package or when the user asks about @hile/message-worker-thread patterns or API.
+---
+
+# @hile/message-worker-thread
+
+本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+
+---
+
+## 1. 架构总览
+
+`@hile/message-worker-thread` 是 `@hile/message-modem` 的 **Node.js Worker Threads 抽象实现**，用于主线程与 Worker 线程之间的请求/响应通信。
+
+`MessageWorkerThread` 本身是 **抽象类**，实现了 `post`（通过 `postMessage` 发送），`exec` 方法留给子类实现。
+
+继承链：
+
+```
+MessageModem (abstract)              ← post + exec 均抽象
+  └── MessageWorkerThread (abstract) ← 实现 post，exec 仍抽象
+        └── 用户子类                  ← 实现 exec
+```
+
+通道类型：
+
+- 主线程端：传入 `Worker` 实例或 `MessagePort`
+- Worker 线程端：不传参数，自动使用 `parentPort`
+
+---
+
+## 2. 类型签名
+
+```typescript
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+import type { Worker, MessagePort } from 'node:worker_threads';
+
+abstract class MessageWorkerThread extends MessageModem {
+  constructor(port?: Worker | MessagePort);
+
+  // 子类必须实现
+  protected abstract exec(data: any): Promise<any>;
+
+  // 向对端发送请求
+  public request<T = any>(data: T, timeout?: number): {
+    abort: () => void;
+    response: <U = any>() => Promise<U>;
+  };
+
+  // 移除消息监听
+  public dispose(): void;
+}
+```
+
+---
+
+## 3. 代码生成模板与规则
+
+### 3.1 基本子类模板
+
+```typescript
+import { MessageWorkerThread } from '@hile/message-worker-thread';
+
+class MyWorkerThread extends MessageWorkerThread {
+  protected async exec(data: any): Promise<any> {
+    switch (data?.action) {
+      case 'ping':
+        return 'pong';
+      default:
+        return data;
+    }
+  }
+}
+```
+
+### 3.2 主线程端模板
+
+```typescript
+import { Worker } from 'node:worker_threads';
+
+class MainThread extends MessageWorkerThread {
+  protected async exec(data: any): Promise<any> {
+    return { reply: 'from main', query: data };
+  }
+}
+
+const worker = new Worker('./worker.js');
+const wt = new MainThread(worker);
+
+const result = await wt.request({ action: 'compute', value: 42 }).response();
+console.log(result);
+
+wt.dispose();
+await worker.terminate();
+```
+
+### 3.3 Worker 线程端模板
+
+```typescript
+// worker.js
+import { MessageWorkerThread } from '@hile/message-worker-thread';
+import { Exception } from '@hile/message-modem';
+
+class WorkerThread extends MessageWorkerThread {
+  protected async exec(data: any): Promise<any> {
+    if (data.action === 'compute') return data.value * 2;
+    if (data.action === 'restricted') throw new Exception(403, 'not allowed');
+    return data;
+  }
+}
+
+const wt = new WorkerThread(); // 无参数 → 使用 parentPort
+```
+
+### 3.4 MessageChannel 场景模板
+
+```typescript
+import { MessageChannel } from 'node:worker_threads';
+
+const { port1, port2 } = new MessageChannel();
+const side1 = new MySide1(port1);
+const side2 = new MySide2(port2);
+
+// 双向通信
+const res = await side1.request('hello').response();
+```
+
+### 3.5 强制规则
+
+| 规则 | 说明 |
+|------|------|
+| **必须继承并实现 `exec`** | `MessageWorkerThread` 是抽象类 |
+| **主线程端必须传入 `Worker` 或 `MessagePort`** | `new Worker()` 返回值 |
+| **Worker 线程端不传参数** | 自动使用 `parentPort` |
+| **用完必须 `dispose()`** | 避免内存泄漏 |
+| **主线程还需 `worker.terminate()`** | 关闭 Worker 线程 |
+
+### 3.6 反模式
+
+```typescript
+// ❌ 不能直接实例化
+const wt = new MessageWorkerThread(worker); // abstract
+
+// ✅ 继承并实现 exec
+class MyWT extends MessageWorkerThread {
+  protected async exec(data: any) { return data; }
+}
+
+// ❌ Worker 线程里传入 Worker 实例没有意义
+const wt = new MyWT(someWorker); // Worker 线程里没有子 Worker
+
+// ✅ Worker 线程不传参数
+const wt = new MyWT();
+
+// ❌ 忘记 dispose 和 terminate
+// ✅ 清理
+wt.dispose();
+await worker.terminate();
+```

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+import { type Worker, type MessagePort } from 'node:worker_threads';
+/**
+ * 支持主线程和 Worker 线程双端使用的 worker_threads 通信层。
+ * exec 方法由子类实现，本类不做实现。
+ *
+ * - Worker 线程端：不传参数，自动绑定 parentPort
+ * - 主线程端：传入 new Worker() 返回的 Worker 实例（或 MessagePort）
+ *
+ * @example
+ * class MyWorkerThread extends MessageWorkerThread {
+ *   protected exec(data: any): Promise<any> {
+ *     return Promise.resolve(data);
+ *   }
+ * }
+ *
+ * // 主线程
+ * const worker = new Worker('./worker.js');
+ * const wt = new MyWorkerThread(worker);
+ * const res = await wt.request('hello').response();
+ * wt.dispose();
+ * await worker.terminate();
+ *
+ * // Worker 线程
+ * const wt = new MyWorkerThread();
+ */
+export declare abstract class MessageWorkerThread extends MessageModem {
+    private readonly port;
+    private readonly listener;
+    constructor(port?: Worker | MessagePort);
+    protected post<T = any>(data: MessageTransferFormat<T>): void;
+    /**
+     * 向对端发送请求
+     */
+    request<T = any>(data: T, timeout?: number): {
+        abort: () => void;
+        response: <U = any>() => Promise<U>;
+    };
+    /**
+     * 移除消息监听，释放资源
+     */
+    dispose(): void;
+}

package/dist/index.js

@@ -0,0 +1,59 @@
+import { MessageModem } from '@hile/message-modem';
+import { parentPort } from 'node:worker_threads';
+/**
+ * 支持主线程和 Worker 线程双端使用的 worker_threads 通信层。
+ * exec 方法由子类实现，本类不做实现。
+ *
+ * - Worker 线程端：不传参数，自动绑定 parentPort
+ * - 主线程端：传入 new Worker() 返回的 Worker 实例（或 MessagePort）
+ *
+ * @example
+ * class MyWorkerThread extends MessageWorkerThread {
+ *   protected exec(data: any): Promise<any> {
+ *     return Promise.resolve(data);
+ *   }
+ * }
+ *
+ * // 主线程
+ * const worker = new Worker('./worker.js');
+ * const wt = new MyWorkerThread(worker);
+ * const res = await wt.request('hello').response();
+ * wt.dispose();
+ * await worker.terminate();
+ *
+ * // Worker 线程
+ * const wt = new MyWorkerThread();
+ */
+export class MessageWorkerThread extends MessageModem {
+    port;
+    listener;
+    constructor(port) {
+        super();
+        if (port) {
+            this.port = port;
+        }
+        else {
+            if (!parentPort) {
+                throw new Error('parentPort is not available. Ensure this code runs inside a Worker thread.');
+            }
+            this.port = parentPort;
+        }
+        this.listener = (msg) => this.receive(msg);
+        this.port.on('message', this.listener);
+    }
+    post(data) {
+        this.port.postMessage(data);
+    }
+    /**
+     * 向对端发送请求
+     */
+    request(data, timeout) {
+        return this.send(data, timeout);
+    }
+    /**
+     * 移除消息监听，释放资源
+     */
+    dispose() {
+        this.port.removeListener('message', this.listener);
+    }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hile/message-worker-thread",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/message-modem": "^1.0.1"
+  },
+  "gitHead": "426933bf98ed09d0e52b6cb63792cd3b2cf3fee1"
+}