@hile/message-modem 1.0.1 → 1.0.3

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);
   }
 }
 ```
@@ -89,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` 返回值
 
 | 属性 | 类型 | 说明 |
 |------|------|------|
@@ -136,11 +139,13 @@ interface MessageReturnFormat<T = any> {
 
 ## 消息流转
 
+### 双向模式（`_send`）
+
 ```
 发送方                        接收方
   │                             │
-  │  send(data)                 │
-  │──── REQUEST ───────────────►│
+  │  _send(data)                │
+  │──── REQUEST (twoway) ──────►│
   │                             │ exec(data)
   │                             │
   │◄──── RESPONSE ──────────────│
@@ -151,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 语义。
 
 核心职责：
 
@@ -84,10 +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): void;
   public receive(msg: MessageTransferFormat): void;
 }
 ```
@@ -118,9 +119,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);
   }
 }
 ```
@@ -151,11 +152,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/index.d.ts

@@ -49,10 +49,24 @@ export declare abstract class MessageModem {
      * @param timeout - 超时时间
      * @returns 消息响应
      */
-    protected send<T = any>(data: T, timeout?: number): {
+    protected _send<T = any>(data: T, timeout?: number): {
         abort: () => void;
         response: <U = any>() => Promise<U>;
-    };
+    } | undefined;
+    /**
+     * 推送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    protected _push<T = any>(data: T, timeout?: number): void;
+    /**
+     * 写入消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    private _write;
     /**
      * 处理请求消息
      * @param msg - 消息数据

package/dist/index.js

@@ -28,10 +28,10 @@ export class MessageModem {
      * @param data - 消息数据
      * @returns 消息数据
      */
-    createPostData(mode, data) {
+    createPostData(mode, data, twoway = true) {
         const id = this.createIncrementId();
         const state = {
-            id, twoway: true, data, mode,
+            id, twoway, data, mode,
         };
         if (mode === MESSAGE_MODEM_TYPE.ABORT) {
             state.twoway = false;
@@ -44,12 +44,33 @@ export class MessageModem {
      * @param timeout - 超时时间
      * @returns 消息响应
      */
-    send(data, timeout = 30000) {
-        const controller = new AbortController();
+    _send(data, timeout = 30000) {
+        return this._write(data, timeout, true);
+    }
+    /**
+     * 推送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    _push(data, timeout = 30000) {
+        this._write(data, timeout, false);
+    }
+    /**
+     * 写入消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    _write(data, timeout = 30000, twoway = false) {
         // 创建请求消息数据
-        const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data);
+        const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, twoway);
         // 发送消息
         this.post(state);
+        // 如果消息是单向的，则直接返回
+        if (!twoway)
+            return;
+        const controller = new AbortController();
         return {
             // 终止请求
             abort: () => controller.abort(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -21,5 +21,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "b0adcecda8429e48dc29bc4658280954e837330b"
+  "gitHead": "0e351166b8351d21e1a97543bc8583ef9513fb67"
 }