@hile/message-modem 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # @hile/message-modem
 
-传输无关的请求/响应消息通信抽象层。将底层传输机制（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 send/receive 语义。
+传输无关的请求/响应消息通信抽象层。将底层传输机制（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 _send/receive 语义。
 
 ## 安装
 
@@ -11,6 +11,8 @@ pnpm add @hile/message-modem
 ## 核心特性
 
 - **传输无关** — 子类只需实现 `post`（如何发送）和 `exec`（如何处理），即可运行于任何通信通道
+- **双向请求/响应** — `_send` 发送请求并等待对端响应（`twoway: true`）
+- **单向推送** — `_push` 发送消息无需对端响应（`twoway: false`）
 - **请求/响应配对** — 自增 ID + Promise 栈，自动配对请求与响应
 - **超时控制** — 默认 30 秒，可按请求自定义
 - **主动中止** — 发送方可 abort 等待，接收方可取消正在执行的任务
@@ -42,7 +44,7 @@ class WebSocketModem extends MessageModem {
 
   // 暴露发送方法
   public request<T>(data: T, timeout?: number) {
-    return this.send(data, timeout);
+    return this._send(data, timeout);
   }
 }
 ```
@@ -62,15 +64,21 @@ console.log(user);
 abort();
 ```
 
-### 第三步：处理超时
+### 第三步：处理超时与异常
+
+所有异常类均从主入口导出，无需单独引入：
 
 ```typescript
+import { AbortException, Exception } from '@hile/message-modem';
+
 try {
   // 5 秒超时
   const result = await modem.request(data, 5000).response();
 } catch (e) {
   if (e instanceof AbortException) {
     console.log('请求超时或被中止');
+  } else if (e instanceof Exception) {
+    console.log(`远端错误 [${e.status}]: ${e.message}`);
   }
 }
 ```
@@ -83,10 +91,11 @@ try {
 |------|--------|------|
 | `post(data)` | `protected abstract` | 子类实现：如何将消息发送到远端 |
 | `exec(data)` | `protected abstract` | 子类实现：如何处理收到的请求，返回 Promise |
-| `send(data, timeout?)` | `protected` | 发送请求，返回 `{ abort, response }` |
+| `_send(data, timeout?)` | `protected` | 发送双向请求（`twoway: true`），返回 `{ abort, response }` |
+| `_push(data, timeout?)` | `protected` | 发送单向推送（`twoway: false`），接收方不回复 RESPONSE |
 | `receive(msg)` | `public` | 接收消息入口，根据 mode 分发处理 |
 
-### `send` 返回值
+### `_send` 返回值
 
 | 属性 | 类型 | 说明 |
 |------|------|------|
@@ -130,11 +139,13 @@ interface MessageReturnFormat<T = any> {
 
 ## 消息流转
 
+### 双向模式（`_send`）
+
 ```
 发送方                        接收方
   │                             │
-  │  send(data)                 │
-  │──── REQUEST ───────────────►│
+  │  _send(data)                │
+  │──── REQUEST (twoway) ──────►│
   │                             │ exec(data)
   │                             │
   │◄──── RESPONSE ──────────────│
@@ -145,6 +156,17 @@ interface MessageReturnFormat<T = any> {
   │                             │ 取消 exec
 ```
 
+### 单向模式（`_push`）
+
+```
+发送方                        接收方
+  │                             │
+  │  _push(data)                │
+  │──── REQUEST (!twoway) ─────►│
+  │                             │ exec(data)
+  │                             │ （不回复 RESPONSE）
+```
+
 ## 适用场景
 
 - **iframe 通信** — 父子页面 postMessage

package/SKILL.md

@@ -11,7 +11,7 @@ description: Code generation and contribution rules for @hile/message-modem. Use
 
 ## 1. 架构总览
 
-`@hile/message-modem` 是一个 **传输无关的请求/响应消息通信抽象层**。它将底层传输（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 send/receive 语义。
+`@hile/message-modem` 是一个 **传输无关的请求/响应消息通信抽象层**。它将底层传输（WebSocket、postMessage、IPC 等）与业务逻辑解耦，提供统一的 _send/receive 语义。
 
 核心职责：
 
@@ -21,6 +21,14 @@ description: Code generation and contribution rules for @hile/message-modem. Use
 - 主动中止（abort）：发送方可中止等待，接收方可取消正在执行的任务
 - 错误传播：`Exception` 携带 `status`；非 `Exception` 错误映射为 500
 
+导出方式：
+
+主入口 `index.ts` 通过 `export * from './exception'` 重新导出所有异常类，因此使用者可以从 `@hile/message-modem` 统一导入所有类型：
+
+```typescript
+import { MessageModem, Exception, AbortException, TimeoutException, MESSAGE_MODEM_TYPE } from '@hile/message-modem';
+```
+
 继承关系：
 
 ```
@@ -76,7 +84,11 @@ class AbortException extends Exception {
 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): {
+  protected _send<T>(data: T, timeout?: number): {
+    abort: () => void;
+    response: <U = any>() => Promise<U>;
+  };
+  protected _push<T>(data: T, timeout?: number): {
     abort: () => void;
     response: <U = any>() => Promise<U>;
   };
@@ -110,9 +122,9 @@ class WebSocketModem extends MessageModem {
     return handleRequest(data);
   }
 
-  // 暴露 send 为 public
-  public request<T, U>(data: T, timeout?: number) {
-    return this.send(data, timeout);
+  // 暴露 _send 为 public
+  public request<T>(data: T, timeout?: number) {
+    return this._send(data, timeout);
   }
 }
 ```
@@ -143,11 +155,12 @@ class IframeModem extends MessageModem {
 | 规则 | 说明 |
 |------|------|
 | **必须实现 `post` 和 `exec`** | 两个 abstract 方法缺一不可 |
-| **`send` 是 `protected`** | 子类应自行决定暴露方式和命名 |
+| **`_send` 是 `protected`** | 子类应自行决定暴露方式和命名 |
+| **`_push` 是 `protected`** | 单向推送（`twoway: false`），接收方不回复 RESPONSE |
 | **`receive` 是 `public`** | 必须由外部消息源（事件监听器）调用 |
 | **传输格式必须保持原样** | `post` 发送的对象结构不可修改，对端的 `receive` 依赖完整的 `MessageTransferFormat` |
 | **`exec` 抛出 `Exception` 时 status 会透传** | 其他 Error 一律映射为 500 |
-| **timeout 默认 30s** | 可通过 `send(data, ms)` 覆盖 |
+| **timeout 默认 30s** | 可通过 `_send(data, ms)` 覆盖 |
 | **abort 后 promise reject `AbortException`** | 不要 catch 后吞掉，保持语义清晰 |
 
 ### 3.4 反模式

package/dist/exception.d.ts

@@ -0,0 +1,12 @@
+export declare class Exception extends Error {
+    readonly status: number | string;
+    constructor(status: number | string, msg: string);
+}
+export declare class TimeoutException extends Exception {
+    static readonly code = "ETIMEDOUT";
+    constructor(msg?: string);
+}
+export declare class AbortException extends Exception {
+    static readonly code = "ECONNABORTED";
+    constructor(msg?: string);
+}

package/dist/exception.js

@@ -0,0 +1,19 @@
+export class Exception extends Error {
+    status;
+    constructor(status, msg) {
+        super(msg);
+        this.status = status;
+    }
+}
+export class TimeoutException extends Exception {
+    static code = 'ETIMEDOUT';
+    constructor(msg = 'Timeout') {
+        super(TimeoutException.code, msg);
+    }
+}
+export class AbortException extends Exception {
+    static code = 'ECONNABORTED';
+    constructor(msg = 'Abort') {
+        super(AbortException.code, msg);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+export * from './exception.js';
+export declare enum MESSAGE_MODEM_TYPE {
+    REQUEST = 0,
+    RESPONSE = 1,
+    ABORT = 2
+}
+export interface MessageTransferFormat<T = any> {
+    id: number;
+    mode: MESSAGE_MODEM_TYPE;
+    twoway: boolean;
+    data?: T;
+}
+export interface MessageReturnFormat<T = any> {
+    status: string | number;
+    data: T;
+    message: string;
+}
+export declare abstract class MessageModem {
+    private id;
+    private readonly aborts;
+    private readonly stacks;
+    /**
+     * 创建自增 ID
+     * 超过最大安全整数时重置为 0
+     * @returns
+     */
+    private createIncrementId;
+    /**
+     * 如何发送消息到远端
+     * @param data - 消息数据
+     */
+    protected abstract post<T = any>(data: MessageTransferFormat<T>): void;
+    /**
+     * 如何执行消息
+     * @param data - 消息数据
+     * @returns
+     */
+    protected abstract exec(data: any): Promise<any>;
+    /**
+     * 创建发送消息数据
+     * @param mode - 消息类型
+     * @param data - 消息数据
+     * @returns 消息数据
+     */
+    private createPostData;
+    /**
+     * 发送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    protected _send<T = any>(data: T, timeout?: number): {
+        abort: () => void;
+        response: <U = any>() => Promise<U>;
+    };
+    /**
+     * 推送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    protected _push<T = any>(data: T, timeout?: number): {
+        abort: () => void;
+        response: <U = any>() => Promise<U>;
+    };
+    /**
+     * 写入消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    private _write;
+    /**
+     * 处理请求消息
+     * @param msg - 消息数据
+     */
+    private onRequest;
+    /**
+     * 处理响应消息
+     * @param msg - 消息数据
+     */
+    private onResponse;
+    /**
+     * 接收消息
+     * @param msg - 消息数据
+     */
+    receive(msg: MessageTransferFormat): void;
+}

package/dist/index.js

@@ -0,0 +1,237 @@
+import { AbortException, Exception, TimeoutException } from "./exception.js";
+export * from './exception.js';
+export var MESSAGE_MODEM_TYPE;
+(function (MESSAGE_MODEM_TYPE) {
+    MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["REQUEST"] = 0] = "REQUEST";
+    MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["RESPONSE"] = 1] = "RESPONSE";
+    MESSAGE_MODEM_TYPE[MESSAGE_MODEM_TYPE["ABORT"] = 2] = "ABORT";
+})(MESSAGE_MODEM_TYPE || (MESSAGE_MODEM_TYPE = {}));
+export class MessageModem {
+    id = 0;
+    aborts = new Map();
+    stacks = new Map();
+    /**
+     * 创建自增 ID
+     * 超过最大安全整数时重置为 0
+     * @returns
+     */
+    createIncrementId() {
+        let id = this.id++;
+        if (this.id >= Number.MAX_SAFE_INTEGER) {
+            id = this.id = 0;
+        }
+        return id;
+    }
+    /**
+     * 创建发送消息数据
+     * @param mode - 消息类型
+     * @param data - 消息数据
+     * @returns 消息数据
+     */
+    createPostData(mode, data, twoway = true) {
+        const id = this.createIncrementId();
+        const state = {
+            id, twoway, data, mode,
+        };
+        if (mode === MESSAGE_MODEM_TYPE.ABORT) {
+            state.twoway = false;
+        }
+        return state;
+    }
+    /**
+     * 发送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    _send(data, timeout = 30000) {
+        return this._write(data, timeout, true);
+    }
+    /**
+     * 推送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    _push(data, timeout = 30000) {
+        return this._write(data, timeout, false);
+    }
+    /**
+     * 写入消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    _write(data, timeout = 30000, twoway = false) {
+        const controller = new AbortController();
+        // 创建请求消息数据
+        const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, twoway);
+        // 发送消息
+        this.post(state);
+        return {
+            // 终止请求
+            abort: () => controller.abort(),
+            // 等待响应
+            response: () => new Promise((resolve, reject) => {
+                // 清理 stacks
+                const clear = () => {
+                    if (this.stacks.has(state.id)) {
+                        this.stacks.delete(state.id);
+                    }
+                };
+                const clean = () => {
+                    clearTimeout(timer);
+                    controller.signal.removeEventListener('abort', aborthandler);
+                    clear();
+                };
+                // Abort 处理函数
+                const aborthandler = () => {
+                    clearTimeout(timer);
+                    this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+                    clear();
+                    reject(new AbortException());
+                };
+                // 成功处理
+                const _resolve = (data) => {
+                    clean();
+                    resolve(data);
+                };
+                // 失败处理
+                const _reject = (e) => {
+                    clean();
+                    reject(e);
+                };
+                // 超时处理
+                const timer = setTimeout(() => {
+                    if (!controller.signal.aborted) {
+                        controller.abort();
+                    }
+                    else {
+                        _reject(new TimeoutException());
+                    }
+                }, timeout);
+                // 添加 Abort 处理函数
+                controller.signal.addEventListener('abort', aborthandler);
+                // 添加栈
+                this.stacks.set(state.id, {
+                    resolve: _resolve,
+                    reject: _reject,
+                });
+            })
+        };
+    }
+    /**
+     * 处理请求消息
+     * @param msg - 消息数据
+     */
+    onRequest(msg) {
+        // 执行消息
+        // 使用 Promise.race 处理消息执行和 Abort 处理
+        Promise.race([
+            this.exec(msg.data).catch(e => ({ e })),
+            new Promise((_, reject) => this.aborts.set(msg.id, reject)),
+        ]).then(value => {
+            // 如果消息执行失败
+            if (value?.e) {
+                // 如果消息是双向的，则发送响应消息
+                if (msg.twoway) {
+                    this.post({
+                        id: msg.id,
+                        mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                        twoway: false,
+                        data: {
+                            status: value.e instanceof Exception ? value.e.status : 500,
+                            data: null,
+                            message: value.e.message,
+                        }
+                    });
+                }
+            }
+            else {
+                // 如果消息是双向的，则发送响应消息
+                if (msg.twoway) {
+                    this.post({
+                        id: msg.id,
+                        mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                        twoway: false,
+                        data: {
+                            status: 200,
+                            data: value,
+                        }
+                    });
+                }
+            }
+        }).catch(e => {
+            if (e instanceof AbortException)
+                return;
+            // 如果消息是双向的，则发送响应消息
+            if (msg.twoway) {
+                // 发送响应消息
+                const code = e instanceof Exception ? e.status : 500;
+                this.post({
+                    id: msg.id,
+                    mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                    twoway: false,
+                    data: {
+                        status: code,
+                        data: null,
+                        message: e.message,
+                    }
+                });
+            }
+        }).finally(() => {
+            // 删除 Abort 处理函数
+            if (this.aborts.has(msg.id)) {
+                this.aborts.delete(msg.id);
+            }
+            // 清理栈
+            if (this.stacks.has(msg.id)) {
+                this.stacks.delete(msg.id);
+            }
+        });
+    }
+    /**
+     * 处理响应消息
+     * @param msg - 消息数据
+     */
+    onResponse(msg) {
+        const id = msg.id;
+        const res = msg.data;
+        // 如果栈中存在该消息，则处理响应消息
+        if (this.stacks.has(id)) {
+            const { resolve, reject } = this.stacks.get(id);
+            // 如果响应状态码不是 200，则拒绝响应
+            if (res?.status !== 200) {
+                reject(new Exception(res?.status, res?.message));
+            }
+            else {
+                resolve(res?.data);
+            }
+        }
+    }
+    /**
+     * 接收消息
+     * @param msg - 消息数据
+     */
+    receive(msg) {
+        // 根据消息类型处理消息
+        switch (msg.mode) {
+            // 处理请求消息
+            case MESSAGE_MODEM_TYPE.REQUEST:
+                this.onRequest(msg);
+                break;
+            // 处理响应消息
+            case MESSAGE_MODEM_TYPE.RESPONSE:
+                this.onResponse(msg);
+                break;
+            // 处理终止消息
+            case MESSAGE_MODEM_TYPE.ABORT:
+                const id = msg.data;
+                if (this.aborts.has(id)) {
+                    const reject = this.aborts.get(id);
+                    reject(new AbortException());
+                    break;
+                }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -21,5 +21,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "41b3df4d124f88453cce2a46a3529dcd6c2480ba"
+  "gitHead": "86b1ce38e9eeb069acb2188834a0ff5b466a050a"
 }