@hile/message-modem 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# @hile/message-modem
+
+传输无关的请求/响应消息通信抽象层。将底层传输机制（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 send/receive 语义。
+
+## 安装
+
+```bash
+pnpm add @hile/message-modem
+```
+
+## 核心特性
+
+- **传输无关** — 子类只需实现 `post`（如何发送）和 `exec`（如何处理），即可运行于任何通信通道
+- **请求/响应配对** — 自增 ID + Promise 栈，自动配对请求与响应
+- **超时控制** — 默认 30 秒，可按请求自定义
+- **主动中止** — 发送方可 abort 等待，接收方可取消正在执行的任务
+- **错误传播** — `Exception` 携带 status 码透传；普通 Error 映射为 500
+
+## 快速开始
+
+### 第一步：继承并实现抽象方法
+
+```typescript
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+
+class WebSocketModem extends MessageModem {
+  constructor(private ws: WebSocket) {
+    super();
+    ws.addEventListener('message', (e) => {
+      this.receive(JSON.parse(e.data));
+    });
+  }
+
+  protected post<T>(data: MessageTransferFormat<T>): void {
+    this.ws.send(JSON.stringify(data));
+  }
+
+  protected async exec(data: any): Promise<any> {
+    // 处理远端请求
+    return handleRequest(data);
+  }
+
+  // 暴露发送方法
+  public request<T>(data: T, timeout?: number) {
+    return this.send(data, timeout);
+  }
+}
+```
+
+### 第二步：发送请求
+
+```typescript
+const modem = new WebSocketModem(ws);
+
+const { abort, response } = modem.request({ action: 'getUser', id: 1 });
+
+// 等待响应
+const user = await response();
+console.log(user);
+
+// 或中止请求
+abort();
+```
+
+### 第三步：处理超时
+
+```typescript
+try {
+  // 5 秒超时
+  const result = await modem.request(data, 5000).response();
+} catch (e) {
+  if (e instanceof AbortException) {
+    console.log('请求超时或被中止');
+  }
+}
+```
+
+## API
+
+### `MessageModem`（抽象类）
+
+| 方法 | 可见性 | 说明 |
+|------|--------|------|
+| `post(data)` | `protected abstract` | 子类实现：如何将消息发送到远端 |
+| `exec(data)` | `protected abstract` | 子类实现：如何处理收到的请求，返回 Promise |
+| `send(data, timeout?)` | `protected` | 发送请求，返回 `{ abort, response }` |
+| `receive(msg)` | `public` | 接收消息入口，根据 mode 分发处理 |
+
+### `send` 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `abort` | `() => void` | 中止本次请求 |
+| `response` | `<U>() => Promise<U>` | 等待远端响应 |
+
+### 消息类型
+
+| 枚举值 | 说明 |
+|--------|------|
+| `MESSAGE_MODEM_TYPE.REQUEST` | 请求消息 |
+| `MESSAGE_MODEM_TYPE.RESPONSE` | 响应消息 |
+| `MESSAGE_MODEM_TYPE.ABORT` | 中止消息 |
+
+### 异常类
+
+| 类 | status | 默认 message | 说明 |
+|------|--------|------|------|
+| `Exception` | 自定义 | 自定义 | 基础异常，携带 status |
+| `TimeoutException` | `ETIMEDOUT` | `Timeout` | 超时异常 |
+| `AbortException` | `ECONNABORTED` | `Abort` | 中止异常 |
+
+### 消息格式
+
+```typescript
+// 传输格式
+interface MessageTransferFormat<T = any> {
+  id: number;
+  mode: MESSAGE_MODEM_TYPE;
+  twoway: boolean;
+  data?: T;
+}
+
+// 响应数据格式
+interface MessageReturnFormat<T = any> {
+  status: string | number;
+  data: T;
+  message: string;
+}
+```
+
+## 消息流转
+
+```
+发送方                        接收方
+  │                             │
+  │  send(data)                 │
+  │──── REQUEST ───────────────►│
+  │                             │ exec(data)
+  │                             │
+  │◄──── RESPONSE ──────────────│
+  │  resolve(data)              │
+  │                             │
+  │  abort()                    │
+  │──── ABORT ─────────────────►│
+  │                             │ 取消 exec
+```
+
+## 适用场景
+
+- **iframe 通信** — 父子页面 postMessage
+- **WebSocket** — 客户端与服务端双向通信
+- **Web Worker** — 主线程与 Worker 通信
+- **Electron IPC** — 主进程与渲染进程通信
+- **Node.js child_process** — 父子进程通信
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: message-modem
+description: Code generation and contribution rules for @hile/message-modem. Use when editing this package or when the user asks about @hile/message-modem patterns or API.
+---
+
+# @hile/message-modem
+
+本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+
+---
+
+## 1. 架构总览
+
+`@hile/message-modem` 是一个 **传输无关的请求/响应消息通信抽象层**。它将底层传输（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 send/receive 语义。
+
+核心职责：
+
+- 自增 ID 管理与安全重置（超过 `MAX_SAFE_INTEGER` 时归零）
+- 请求/响应配对（通过 ID + stacks Map）
+- 超时控制（基于 `AbortController` + `setTimeout`）
+- 主动中止（abort）：发送方可中止等待，接收方可取消正在执行的任务
+- 错误传播：`Exception` 携带 `status`；非 `Exception` 错误映射为 500
+
+继承关系：
+
+```
+MessageModem (abstract)
+  ├── post(data)    — 子类实现：如何发送到远端
+  └── exec(data)    — 子类实现：如何处理收到的请求
+```
+
+---
+
+## 2. 类型签名
+
+```typescript
+// ---- 枚举 ----
+enum MESSAGE_MODEM_TYPE {
+  REQUEST,    // 请求
+  RESPONSE,   // 响应
+  ABORT,      // 中止
+}
+
+// ---- 传输格式 ----
+interface MessageTransferFormat<T = any> {
+  id: number;
+  mode: MESSAGE_MODEM_TYPE;
+  twoway: boolean;
+  data?: T;
+}
+
+// ---- 响应格式 ----
+interface MessageReturnFormat<T = any> {
+  status: string | number;
+  data: T;
+  message: string;
+}
+
+// ---- 异常 ----
+class Exception extends Error {
+  readonly status: number | string;
+  constructor(status: number | string, msg: string);
+}
+
+class TimeoutException extends Exception {
+  static readonly code = 'ETIMEDOUT';
+  constructor(msg?: string);  // 默认 'Timeout'
+}
+
+class AbortException extends Exception {
+  static readonly code = 'ECONNABORTED';
+  constructor(msg?: string);  // 默认 'Abort'
+}
+
+// ---- 抽象基类 ----
+abstract class MessageModem {
+  protected abstract post<T>(data: MessageTransferFormat<T>): void;
+  protected abstract exec(data: any): Promise<any>;
+  protected send<T>(data: T, timeout?: number): {
+    abort: () => void;
+    response: <U = any>() => Promise<U>;
+  };
+  public receive(msg: MessageTransferFormat): void;
+}
+```
+
+---
+
+## 3. 代码生成模板与规则
+
+### 3.1 子类实现模板
+
+```typescript
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+
+class WebSocketModem extends MessageModem {
+  constructor(private ws: WebSocket) {
+    super();
+    ws.addEventListener('message', (e) => {
+      this.receive(JSON.parse(e.data));
+    });
+  }
+
+  protected post<T>(data: MessageTransferFormat<T>): void {
+    this.ws.send(JSON.stringify(data));
+  }
+
+  protected async exec(data: any): Promise<any> {
+    // 处理远端请求的业务逻辑
+    return handleRequest(data);
+  }
+
+  // 暴露 send 为 public
+  public request<T, U>(data: T, timeout?: number) {
+    return this.send(data, timeout);
+  }
+}
+```
+
+### 3.2 postMessage 场景模板
+
+```typescript
+class IframeModem extends MessageModem {
+  constructor(private target: Window, private origin: string) {
+    super();
+    window.addEventListener('message', (e) => {
+      if (e.origin === origin) this.receive(e.data);
+    });
+  }
+
+  protected post<T>(data: MessageTransferFormat<T>): void {
+    this.target.postMessage(data, this.origin);
+  }
+
+  protected async exec(data: any): Promise<any> {
+    return handleIframeRequest(data);
+  }
+}
+```
+
+### 3.3 强制规则
+
+| 规则 | 说明 |
+|------|------|
+| **必须实现 `post` 和 `exec`** | 两个 abstract 方法缺一不可 |
+| **`send` 是 `protected`** | 子类应自行决定暴露方式和命名 |
+| **`receive` 是 `public`** | 必须由外部消息源（事件监听器）调用 |
+| **传输格式必须保持原样** | `post` 发送的对象结构不可修改，对端的 `receive` 依赖完整的 `MessageTransferFormat` |
+| **`exec` 抛出 `Exception` 时 status 会透传** | 其他 Error 一律映射为 500 |
+| **timeout 默认 30s** | 可通过 `send(data, ms)` 覆盖 |
+| **abort 后 promise reject `AbortException`** | 不要 catch 后吞掉，保持语义清晰 |
+
+### 3.4 反模式
+
+```typescript
+// ❌ 不要在 post 中做异步操作
+protected async post(data) { await fetch(...); }
+// ✅ post 应该是同步的，异步传输应缓冲
+
+// ❌ 不要直接修改 MessageTransferFormat 结构
+this.post({ ...data, extra: 'field' });
+// ✅ 业务数据放在 data 字段内
+
+// ❌ 不要忘记连接 receive
+// ✅ 在构造函数中绑定消息事件 → this.receive(parsed)
+
+// ❌ 不要在 exec 中吞掉错误
+protected async exec(data) { try { ... } catch { return null; } }
+// ✅ 让错误冒泡，框架会处理错误响应
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hile/message-modem",
+  "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"
+  },
+  "gitHead": "41b3df4d124f88453cce2a46a3529dcd6c2480ba"
+}