@hile/message-ws 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @hile/message-ws
+
+基于 `@hile/message-modem` 和 `ws` 模块的 WebSocket 通信抽象实现。让客户端与服务端之间的请求/响应通信像调用函数一样简单。
+
+## 安装
+
+```bash
+pnpm add @hile/message-ws
+```
+
+## 核心特性
+
+- **双端支持** — 客户端和服务端各自包装 `WebSocket` 实例即可
+- **继承模式** — 继承 `MessageWs` 并实现 `exec` 方法
+- **JSON 传输** — 消息自动 JSON 序列化/反序列化
+- **请求/响应** — 继承 `MessageModem` 全部能力
+- **超时控制** — 默认 30 秒，可按请求自定义
+- **主动中止** — `abort()` 取消等待并通知对端
+- **错误传播** — `Exception` 带 status 透传，普通 Error 映射为 500
+- **连接状态检查** — 发送前检查 `readyState`
+- **资源清理** — `dispose()` 移除监听
+
+## 快速开始
+
+### 第一步：定义子类
+
+```typescript
+import { MessageWs } from '@hile/message-ws';
+import { Exception } from '@hile/message-modem';
+
+class AppWs extends MessageWs {
+  protected async exec(data: any): Promise<any> {
+    switch (data?.action) {
+      case 'getUser':
+        return { id: data.id, name: 'Alice' };
+      case 'restricted':
+        throw new Exception(403, 'not allowed');
+      default:
+        return data;
+    }
+  }
+}
+```
+
+### 第二步：服务端
+
+```typescript
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+wss.on('connection', (ws) => {
+  const modem = new AppWs(ws);
+  // 自动处理客户端请求
+});
+```
+
+### 第三步：客户端
+
+```typescript
+import WebSocket from 'ws';
+
+const ws = new WebSocket('ws://localhost:8080');
+ws.on('open', () => {
+  const modem = new AppWs(ws);
+
+  const user = await modem.request({ action: 'getUser', id: 1 }).response();
+  console.log(user); // { id: 1, name: 'Alice' }
+
+  modem.dispose();
+  ws.close();
+});
+```
+
+## API
+
+### `MessageWs`（抽象类）
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `constructor` | `new SubClass(ws: WebSocket)` | 传入已连接的 WebSocket 实例 |
+| `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 modem.request(data, 5000).response();
+
+// 主动中止
+const req = modem.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}`);
+  }
+}
+```
+
+## 注意事项
+
+- `MessageWs` 是 **抽象类**，不能直接实例化
+- 必须在 WebSocket 连接建立（`open` 事件）后再创建实例或发送请求
+- 消息通过 JSON 序列化传输，不支持 Buffer/Map/Set 等非 JSON 类型
+- 使用完毕后调用 `dispose()` + `ws.close()`
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: message-ws
+description: Code generation and contribution rules for @hile/message-ws. Use when editing this package or when the user asks about @hile/message-ws patterns or API.
+---
+
+# @hile/message-ws
+
+本文档是面向 AI 编码模型和人类开发者的 **代码生成规范**，阅读后应能正确地使用本库编写符合架构规则的代码。
+
+---
+
+## 1. 架构总览
+
+`@hile/message-ws` 是 `@hile/message-modem` 的 **WebSocket（ws 模块）抽象实现**，用于客户端与服务端之间的请求/响应通信。
+
+`MessageWs` 本身是 **抽象类**，实现了 `post`（通过 `ws.send` 发送 JSON），`exec` 方法留给子类实现。
+
+继承链：
+
+```
+MessageModem (abstract)     ← post + exec 均抽象
+  └── MessageWs (abstract)  ← 实现 post（JSON + ws.send），exec 仍抽象
+        └── 用户子类         ← 实现 exec
+```
+
+消息通过 JSON 序列化/反序列化传输。
+
+---
+
+## 2. 类型签名
+
+```typescript
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+import type WebSocket from 'ws';
+
+abstract class MessageWs extends MessageModem {
+  constructor(ws: WebSocket);
+
+  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 { MessageWs } from '@hile/message-ws';
+
+class MyWs extends MessageWs {
+  protected async exec(data: any): Promise<any> {
+    switch (data?.action) {
+      case 'ping': return 'pong';
+      default: return data;
+    }
+  }
+}
+```
+
+### 3.2 客户端模板
+
+```typescript
+import WebSocket from 'ws';
+
+const ws = new WebSocket('ws://localhost:8080');
+ws.on('open', () => {
+  const modem = new MyWs(ws);
+
+  modem.request({ action: 'getUser', id: 1 })
+    .response<User>()
+    .then(console.log);
+});
+```
+
+### 3.3 服务端模板
+
+```typescript
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+wss.on('connection', (ws) => {
+  const modem = new MyWs(ws);
+  // modem 自动监听 ws 消息并处理请求
+});
+```
+
+### 3.4 强制规则
+
+| 规则 | 说明 |
+|------|------|
+| **必须继承并实现 `exec`** | `MessageWs` 是抽象类 |
+| **必须传入已连接的 `WebSocket`** | 或在 `open` 事件后创建 |
+| **消息通过 JSON 传输** | `post` 内部 `JSON.stringify`，收到消息 `JSON.parse` |
+| **`readyState !== OPEN` 时 `post` 会抛错** | 确保连接已建立 |
+| **用完必须 `dispose()`** | 避免内存泄漏 |
+
+### 3.5 反模式
+
+```typescript
+// ❌ 连接未建立就创建 modem 并发送
+const ws = new WebSocket('ws://...');
+const modem = new MyWs(ws);
+modem.request('hi'); // readyState 不是 OPEN → 抛错
+
+// ✅ 等待 open 事件
+ws.on('open', () => {
+  const modem = new MyWs(ws);
+  modem.request('hi');
+});
+
+// ❌ 不能直接实例化
+const modem = new MessageWs(ws); // abstract
+
+// ✅ 继承并实现 exec
+class MyWs extends MessageWs { ... }
+
+// ❌ 传输非 JSON 安全的数据
+modem.request(new Map()); // Map 序列化会丢失
+
+// ✅ 只传 JSON 安全数据
+modem.request({ key: 'value' });
+```

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
+import type WebSocket from 'ws';
+/**
+ * 基于 `ws` 模块的 WebSocket 通信层。
+ * exec 方法由子类实现，本类不做实现。
+ *
+ * 构造时传入已连接的 WebSocket 实例，自动绑定 message 事件。
+ * 消息通过 JSON 序列化/反序列化传输。
+ *
+ * @example
+ * class MyWs extends MessageWs {
+ *   protected exec(data: any): Promise<any> {
+ *     return Promise.resolve(data);
+ *   }
+ * }
+ *
+ * const ws = new WebSocket('ws://localhost:8080');
+ * ws.on('open', () => {
+ *   const modem = new MyWs(ws);
+ *   modem.request('hello').response().then(console.log);
+ * });
+ */
+export declare abstract class MessageWs extends MessageModem {
+    private readonly ws;
+    private readonly listener;
+    constructor(ws: WebSocket);
+    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,55 @@
+import { MessageModem } from '@hile/message-modem';
+/**
+ * 基于 `ws` 模块的 WebSocket 通信层。
+ * exec 方法由子类实现，本类不做实现。
+ *
+ * 构造时传入已连接的 WebSocket 实例，自动绑定 message 事件。
+ * 消息通过 JSON 序列化/反序列化传输。
+ *
+ * @example
+ * class MyWs extends MessageWs {
+ *   protected exec(data: any): Promise<any> {
+ *     return Promise.resolve(data);
+ *   }
+ * }
+ *
+ * const ws = new WebSocket('ws://localhost:8080');
+ * ws.on('open', () => {
+ *   const modem = new MyWs(ws);
+ *   modem.request('hello').response().then(console.log);
+ * });
+ */
+export class MessageWs extends MessageModem {
+    ws;
+    listener;
+    constructor(ws) {
+        super();
+        this.ws = ws;
+        this.listener = (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                this.receive(msg);
+            }
+            catch { }
+        };
+        this.ws.on('message', this.listener);
+    }
+    post(data) {
+        if (this.ws.readyState !== this.ws.OPEN) {
+            throw new Error('WebSocket is not open. Current readyState: ' + this.ws.readyState);
+        }
+        this.ws.send(JSON.stringify(data));
+    }
+    /**
+     * 向对端发送请求
+     */
+    request(data, timeout) {
+        return this.send(data, timeout);
+    }
+    /**
+     * 移除消息监听，释放资源
+     */
+    dispose() {
+        this.ws.removeListener('message', this.listener);
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hile/message-ws",
+  "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": {
+    "@types/ws": "^8.18.1",
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/message-modem": "^1.0.1",
+    "ws": "^8.19.0"
+  },
+  "gitHead": "8f802f24910712571463865ddbe856d2cfba0786"
+}