@hile/message-ipc 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# @hile/message-ipc
+
+基于 `@hile/message-modem` 的 Node.js IPC 通信抽象实现。让父子进程间的请求/响应通信像调用函数一样简单。
+
+## 安装
+
+```bash
+pnpm add @hile/message-ipc
+```
+
+## 核心特性
+
+- **双端支持** — 父进程端传入 `ChildProcess`，子进程端零配置
+- **继承模式** — 继承 `MessageIpc` 并实现 `exec` 方法定义请求处理逻辑
+- **请求/响应** — 继承 `MessageModem` 的全部能力
+- **超时控制** — 默认 30 秒，可按请求自定义
+- **主动中止** — `abort()` 取消等待并通知对端
+- **错误传播** — `Exception` 带 status 透传，普通 Error 映射为 500
+- **资源清理** — `dispose()` 移除监听，避免内存泄漏
+
+## 快速开始
+
+### 第一步：定义子类
+
+`MessageIpc` 是抽象类，需继承并实现 `exec` 方法：
+
+```typescript
+import { MessageIpc } from '@hile/message-ipc';
+import { Exception } from '@hile/message-modem';
+
+class WorkerIpc extends MessageIpc {
+  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; // echo
+    }
+  }
+}
+```
+
+### 第二步：父进程
+
+```typescript
+import { fork } from 'node:child_process';
+
+class ParentIpc extends MessageIpc {
+  protected async exec(data: any): Promise<any> {
+    return { reply: 'from parent', query: data };
+  }
+}
+
+const child = fork('./worker.js');
+const ipc = new ParentIpc(child);
+
+const result = await ipc.request({ action: 'compute', value: 42 }).response();
+console.log(result); // 84
+
+ipc.dispose();
+child.kill();
+```
+
+### 第三步：子进程（worker.js）
+
+```typescript
+const ipc = new WorkerIpc(); // 无参数 → 自动使用 process
+```
+
+## API
+
+### `MessageIpc`（抽象类）
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `constructor` | `new SubClass(channel?: ChildProcess)` | 父进程传 `fork()` 返回值；子进程不传参数 |
+| `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>` | 等待对端响应 |
+
+## 超时与中止
+
+```typescript
+import { AbortException, Exception } from '@hile/message-modem';
+
+// 5 秒超时
+const result = await ipc.request(data, 5000).response();
+
+// 主动中止
+const req = ipc.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}`);
+  }
+}
+```
+
+## 注意事项
+
+- `MessageIpc` 是 **抽象类**，不能直接实例化，必须继承并实现 `exec`
+- 子进程必须通过 `fork()` 启动，`spawn()` 没有 IPC 通道
+- 使用完毕后务必调用 `dispose()` + `child.kill()` 清理资源
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: message-ipc
+description: Code generation and contribution rules for @hile/message-ipc. Use when editing this package or when the user asks about @hile/message-ipc patterns or API.
+---
+
+# @hile/message-ipc
+
+本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+
+---
+
+## 1. 架构总览
+
+`@hile/message-ipc` 是 `@hile/message-modem` 的 **Node.js IPC 抽象实现**，用于父子进程间的请求/响应通信。
+
+`MessageIpc` 本身是 **抽象类**，只实现了 `post`（通过 IPC 通道发送）和消息监听，`exec` 方法留给子类实现具体的请求处理逻辑。
+
+继承链：
+
+```
+MessageModem (abstract)        ← post + exec 均抽象
+  └── MessageIpc (abstract)    ← 实现 post，exec 仍抽象
+        └── 用户子类            ← 实现 exec
+```
+
+---
+
+## 2. 类型签名
+
+```typescript
+import type { ChildProcess } from 'node:child_process';
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+
+type IpcExecHandler = (data: any) => Promise<any>;
+
+abstract class MessageIpc extends MessageModem {
+  constructor(channel?: ChildProcess);
+
+  // 子类必须实现
+  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 { MessageIpc } from '@hile/message-ipc';
+
+class MyIpc extends MessageIpc {
+  protected async exec(data: any): Promise<any> {
+    // 处理对端发来的请求
+    switch (data?.action) {
+      case 'ping':
+        return 'pong';
+      default:
+        return data;
+    }
+  }
+}
+```
+
+### 3.2 父进程端模板
+
+```typescript
+import { fork } from 'node:child_process';
+
+class ParentIpc extends MessageIpc {
+  protected async exec(data: any): Promise<any> {
+    // 处理子进程发来的请求
+    return { reply: 'from parent', query: data };
+  }
+}
+
+const child = fork('./worker.js');
+const ipc = new ParentIpc(child);
+
+const result = await ipc.request({ action: 'compute', value: 42 }).response();
+console.log(result);
+
+ipc.dispose();
+child.kill();
+```
+
+### 3.3 子进程端模板
+
+```typescript
+// worker.js
+import { MessageIpc } from '@hile/message-ipc';
+import { Exception } from '@hile/message-modem';
+
+class WorkerIpc extends MessageIpc {
+  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 ipc = new WorkerIpc(); // 无参数 → 使用 process
+```
+
+### 3.4 强制规则
+
+| 规则 | 说明 |
+|------|------|
+| **必须继承 `MessageIpc` 并实现 `exec`** | `MessageIpc` 是抽象类，不能直接实例化 |
+| **父进程端必须传入 `ChildProcess`** | `fork()` 返回值 |
+| **子进程端不传参数** | 自动使用 `process`，要求进程通过 `fork()` 启动 |
+| **用完必须 `dispose()`** | 避免内存泄漏 |
+| **`request` 返回 `{ abort, response }`** | 继承 `send` 语义 |
+
+### 3.5 反模式
+
+```typescript
+// ❌ 不能直接实例化 MessageIpc
+const ipc = new MessageIpc(child); // TypeError: Cannot construct abstract class
+
+// ✅ 继承并实现 exec
+class MyIpc extends MessageIpc {
+  protected async exec(data: any) { return data; }
+}
+const ipc = new MyIpc(child);
+
+// ❌ 不要用 spawn
+const child = spawn('node', ['worker.js']);
+// ✅ 用 fork
+const child = fork('./worker.js');
+
+// ❌ 不要忘记 dispose
+// ✅ 用完清理
+ipc.dispose();
+child.kill();
+```

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+import type { ChildProcess } from 'node:child_process';
+export type IpcExecHandler = (data: any) => Promise<any>;
+/**
+ * 支持父进程和子进程双端使用的 IPC 通信层。
+ * exec方法实现由子类实现，本实例不做实现
+ *
+ * - 子进程端：不传参数，自动绑定 process.on('message') / process.send()
+ * - 父进程端：传入 fork() 返回的 ChildProcess 实例
+ *
+ * @example
+ * class MyIpc extends MessageIpc {
+ *   protected exec(data: any): Promise<any> {
+ *     return Promise.resolve(data);
+ *   }
+ * }
+ *
+ * const ipc = new MyIpc();
+ * ipc.request('hello').then((res) => {
+ *   console.log(res);
+ * });
+ * ipc.dispose();
+ */
+export declare abstract class MessageIpc extends MessageModem {
+    private readonly channel;
+    private readonly listener;
+    constructor(channel?: ChildProcess);
+    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,50 @@
+import { MessageModem } from '@hile/message-modem';
+/**
+ * 支持父进程和子进程双端使用的 IPC 通信层。
+ * exec方法实现由子类实现，本实例不做实现
+ *
+ * - 子进程端：不传参数，自动绑定 process.on('message') / process.send()
+ * - 父进程端：传入 fork() 返回的 ChildProcess 实例
+ *
+ * @example
+ * class MyIpc extends MessageIpc {
+ *   protected exec(data: any): Promise<any> {
+ *     return Promise.resolve(data);
+ *   }
+ * }
+ *
+ * const ipc = new MyIpc();
+ * ipc.request('hello').then((res) => {
+ *   console.log(res);
+ * });
+ * ipc.dispose();
+ */
+export class MessageIpc extends MessageModem {
+    channel;
+    listener;
+    constructor(channel) {
+        super();
+        this.channel = channel ?? process;
+        this.listener = (msg) => this.receive(msg);
+        this.channel.on('message', this.listener);
+    }
+    post(data) {
+        const ch = this.channel;
+        if (typeof ch.send !== 'function') {
+            throw new Error('IPC channel is not available. Ensure the process was forked with an IPC channel.');
+        }
+        ch.send(data);
+    }
+    /**
+     * 向对端发送请求
+     */
+    request(data, timeout) {
+        return this.send(data, timeout);
+    }
+    /**
+     * 移除消息监听，释放资源
+     */
+    dispose() {
+        this.channel.removeListener('message', this.listener);
+    }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hile/message-ipc",
+  "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": "f8add8c808b4c0a4e51ee97f49557ca189e1471c"
+}