@hile/message-modem 1.0.7 → 2.0.1

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Readable } from 'node:stream';
 export * from './exception.js';
 export declare enum MESSAGE_MODEM_TYPE {
     REQUEST = 0,
@@ -8,6 +9,7 @@ export interface MessageTransferFormat<T = any> {
     id: number;
     mode: MESSAGE_MODEM_TYPE;
     twoway: boolean;
+    stream?: boolean;
     data?: T;
 }
 export interface MessageReturnFormat<T = any> {
@@ -15,10 +17,17 @@ export interface MessageReturnFormat<T = any> {
     data: T;
     message: string;
 }
+export interface MessageStreamChunk<T = any> {
+    status: string | number;
+    seq: number;
+    payload: T;
+    final: boolean;
+}
 export declare abstract class MessageModem {
     private id;
     private readonly aborts;
     private readonly stacks;
+    private readonly streams;
     protected _dispose(): void;
     /**
      * 创建自增 ID
@@ -36,7 +45,7 @@ export declare abstract class MessageModem {
      * @param data - 消息数据
      * @returns
      */
-    protected abstract exec(data: any): Promise<any>;
+    protected abstract exec(data: any, signal?: AbortSignal): Promise<any>;
     /**
      * 创建发送消息数据
      * @param mode - 消息类型
@@ -48,19 +57,27 @@ export declare abstract class MessageModem {
      * 发送消息
      * @param data - 消息数据
      * @param timeout - 超时时间
+     * @param signal - 中止信号
      * @returns 消息响应
      */
-    protected _send<T = any>(data: T, timeout?: number): {
-        abort: () => void;
-        response: <U = any>() => Promise<U>;
-    };
+    protected _send<T = any>(data: any, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
     /**
      * 推送消息
      * @param data - 消息数据
      * @param timeout - 超时时间
+     * @param signal - 中止信号
      * @returns 消息响应
      */
-    protected _push<T = any>(data: T, timeout?: number): void;
+    protected _push<T = any>(data: T, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): void;
+    protected _stream(data: any, options?: {
+        signal?: AbortSignal;
+    }): Readable;
     /**
      * 写入消息
      * @param data - 消息数据
@@ -78,6 +95,8 @@ export declare abstract class MessageModem {
      * @param msg - 消息数据
      */
     private onResponse;
+    private onStreamRequest;
+    private onStreamResponse;
     /**
      * 接收消息
      * @param msg - 消息数据

package/dist/index.js

@@ -1,4 +1,5 @@
 import { AbortException, Exception, TimeoutException } from "./exception.js";
+import { Readable } from 'node:stream';
 export * from './exception.js';
 export var MESSAGE_MODEM_TYPE;
 (function (MESSAGE_MODEM_TYPE) {
@@ -10,15 +11,20 @@ export class MessageModem {
     id = 0;
     aborts = new Map();
     stacks = new Map();
+    streams = new Map();
     _dispose() {
         for (const { reject } of this.stacks.values()) {
             reject(new AbortException());
         }
-        for (const reject of this.aborts.values()) {
-            reject(new AbortException());
+        for (const controller of this.aborts.values()) {
+            controller.abort();
+        }
+        for (const stream of this.streams.values()) {
+            stream.destroy(new AbortException());
         }
         this.aborts.clear();
         this.stacks.clear();
+        this.streams.clear();
     }
     /**
      * 创建自增 ID
@@ -38,13 +44,14 @@ export class MessageModem {
      * @param data - 消息数据
      * @returns 消息数据
      */
-    createPostData(mode, data, twoway = true) {
+    createPostData(mode, data, twoway = true, stream = false) {
         const id = this.createIncrementId();
         const state = {
-            id, twoway, data, mode,
+            id, twoway, data, mode, stream,
         };
         if (mode === MESSAGE_MODEM_TYPE.ABORT) {
             state.twoway = false;
+            state.stream = false;
         }
         return state;
     }
@@ -52,19 +59,50 @@ export class MessageModem {
      * 发送消息
      * @param data - 消息数据
      * @param timeout - 超时时间
+     * @param signal - 中止信号
      * @returns 消息响应
      */
-    _send(data, timeout = 30000) {
-        return this._write(data, timeout, true);
+    _send(data, options) {
+        return this._write(data, {
+            timeout: options?.timeout ?? 30000,
+            twoway: true,
+            signal: options?.signal,
+        });
     }
     /**
      * 推送消息
      * @param data - 消息数据
      * @param timeout - 超时时间
+     * @param signal - 中止信号
      * @returns 消息响应
      */
-    _push(data, timeout = 30000) {
-        this._write(data, timeout, false);
+    _push(data, options) {
+        this._write(data, {
+            timeout: options?.timeout ?? 30000,
+            twoway: false,
+            signal: options?.signal,
+        });
+    }
+    _stream(data, options) {
+        const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, true, true);
+        const stream = new Readable({ objectMode: true, read() { } });
+        this.streams.set(state.id, stream);
+        this.post(state);
+        const onAbort = () => {
+            this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+            stream.destroy(new AbortException());
+            this.streams.delete(state.id);
+        };
+        if (options?.signal) {
+            options.signal.addEventListener('abort', onAbort);
+        }
+        stream.on('close', () => {
+            if (this.streams.has(state.id)) {
+                this.streams.delete(state.id);
+            }
+            options?.signal?.removeEventListener('abort', onAbort);
+        });
+        return stream;
     }
     /**
      * 写入消息
@@ -72,7 +110,10 @@ export class MessageModem {
      * @param timeout - 超时时间
      * @returns 消息响应
      */
-    _write(data, timeout = 30000, twoway = false) {
+    _write(data, options) {
+        const timeout = options?.timeout ?? 30000;
+        const twoway = !!options?.twoway;
+        const signal = options?.signal;
         // 创建请求消息数据
         const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data, twoway);
         // 发送消息
@@ -80,135 +121,101 @@ export class MessageModem {
         // 如果消息是单向的，则直接返回
         if (!twoway)
             return;
-        const controller = new AbortController();
-        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);
+        return new Promise((resolve, reject) => {
+            const clear = () => {
+                if (this.stacks.has(state.id)) {
+                    this.stacks.delete(state.id);
+                }
+            };
+            const clean = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+                clear();
+            };
+            const onAbort = () => {
+                clearTimeout(timer);
+                try {
+                    this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
+                }
+                catch {
+                    /* 例如 WebSocket 已关闭时 send 可能抛错 */
+                }
+                finally {
+                    signal?.removeEventListener('abort', onAbort);
                     clear();
-                };
-                // Abort 处理函数（post 失败时仍须 reject，否则调用方会一直挂起）
-                const aborthandler = () => {
-                    clearTimeout(timer);
-                    try {
-                        this.post(this.createPostData(MESSAGE_MODEM_TYPE.ABORT, state.id));
-                    }
-                    catch {
-                        /* 例如 WebSocket 已关闭时 send 可能抛错 */
-                    }
-                    finally {
-                        controller.signal.removeEventListener('abort', aborthandler);
-                        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).unref();
-                // 添加 Abort 处理函数
-                controller.signal.addEventListener('abort', aborthandler);
-                // 添加栈
-                this.stacks.set(state.id, {
-                    resolve: _resolve,
-                    reject: _reject,
-                });
-            })
-        };
+                    reject(new AbortException());
+                }
+            };
+            // 成功处理
+            const _resolve = (data) => {
+                clean();
+                resolve(data);
+            };
+            // 失败处理
+            const _reject = (e) => {
+                clean();
+                reject(e);
+            };
+            const timer = setTimeout(() => _reject(new TimeoutException()), timeout).unref();
+            signal?.addEventListener('abort', onAbort);
+            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,
-                        }
-                    });
-                }
+        const controller = new AbortController();
+        this.aborts.set(msg.id, controller);
+        controller.signal.addEventListener('abort', () => {
+            if (this.aborts.has(msg.id)) {
+                this.aborts.delete(msg.id);
             }
-            else {
-                // 如果消息是双向的，则发送响应消息
-                if (msg.twoway) {
-                    this.post({
-                        id: msg.id,
-                        mode: MESSAGE_MODEM_TYPE.RESPONSE,
-                        twoway: false,
-                        data: {
-                            status: 200,
-                            data: value,
-                        }
-                    });
-                }
+        });
+        this.exec(msg.data, controller.signal)
+            .then(value => {
+            if (controller.signal.aborted)
+                return;
+            if (isAsyncIterable(value)) {
+                throw new Exception(500, 'Async iterable is not supported');
+            }
+            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)
+        })
+            .catch(e => {
+            if (controller.signal.aborted)
                 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,
+                        status: e instanceof Exception ? e.status : 500,
                         data: null,
                         message: e.message,
                     }
                 });
             }
-        }).finally(() => {
+        })
+            .finally(() => {
             // 删除 Abort 处理函数
             if (this.aborts.has(msg.id)) {
                 this.aborts.delete(msg.id);
             }
-            // 清理栈
-            if (this.stacks.has(msg.id)) {
-                this.stacks.delete(msg.id);
-            }
         });
     }
     /**
@@ -230,6 +237,99 @@ export class MessageModem {
             }
         }
     }
+    onStreamRequest(msg) {
+        const controller = new AbortController();
+        this.aborts.set(msg.id, controller);
+        controller.signal.addEventListener('abort', () => {
+            if (this.aborts.has(msg.id)) {
+                this.aborts.delete(msg.id);
+            }
+        });
+        this.exec(msg.data, controller.signal)
+            .then(async (value) => {
+            if (!isAsyncIterable(value)) {
+                throw new Exception(500, 'Invalid async iterable');
+            }
+            let i = 0;
+            for await (const chunk of value) {
+                if (controller.signal.aborted)
+                    return;
+                this.post({
+                    id: msg.id,
+                    mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                    stream: true,
+                    data: {
+                        status: 200,
+                        seq: i++,
+                        payload: chunk,
+                        final: false,
+                    },
+                    twoway: false,
+                });
+            }
+            if (controller.signal.aborted)
+                return;
+            this.post({
+                id: msg.id,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                data: {
+                    status: 200,
+                    seq: i++,
+                    payload: undefined,
+                    final: true,
+                },
+                twoway: false,
+            });
+        })
+            .catch(e => {
+            if (controller.signal.aborted)
+                return;
+            this.post({
+                id: msg.id,
+                mode: MESSAGE_MODEM_TYPE.RESPONSE,
+                stream: true,
+                data: {
+                    status: e instanceof Exception ? e.status : 500,
+                    seq: 0,
+                    payload: e instanceof Exception ? e.message : 'Unknown error',
+                    final: true,
+                },
+                twoway: false,
+            });
+        })
+            .finally(() => {
+            if (this.aborts.has(msg.id)) {
+                this.aborts.delete(msg.id);
+            }
+        });
+    }
+    onStreamResponse(msg) {
+        const id = msg.id;
+        const res = msg.data;
+        // 如果栈中存在该消息，则处理响应消息
+        if (this.streams.has(id)) {
+            const stream = this.streams.get(id);
+            if (res) {
+                if (res.status === 200) {
+                    if (res.final) {
+                        stream.push(null);
+                    }
+                    else {
+                        stream.push(res.payload);
+                    }
+                }
+                else {
+                    const err = new Exception(res.status, res.payload);
+                    setImmediate(() => stream.destroy(err));
+                }
+            }
+            else {
+                const err = new Exception(404, 'Empty chunk data');
+                setImmediate(() => stream.destroy(err));
+            }
+        }
+    }
     /**
      * 接收消息
      * @param msg - 消息数据
@@ -239,20 +339,35 @@ export class MessageModem {
         switch (msg.mode) {
             // 处理请求消息
             case MESSAGE_MODEM_TYPE.REQUEST:
-                this.onRequest(msg);
+                if (msg.stream) {
+                    this.onStreamRequest(msg);
+                }
+                else {
+                    this.onRequest(msg);
+                }
                 break;
             // 处理响应消息
             case MESSAGE_MODEM_TYPE.RESPONSE:
-                this.onResponse(msg);
+                if (msg.stream) {
+                    this.onStreamResponse(msg);
+                }
+                else {
+                    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;
+                    const controller = this.aborts.get(id);
+                    if (!controller.signal.aborted) {
+                        controller.abort();
+                    }
                 }
+                break;
         }
     }
 }
+function isAsyncIterable(value) {
+    return value != null && typeof value[Symbol.asyncIterator] === 'function';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-modem",
-  "version": "1.0.7",
+  "version": "2.0.1",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -21,5 +21,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "4549afb84d25e8dffdfab2e27ed05e52828c368d"
+  "gitHead": "8e0fd1f78b5a8abd21218d1f596ada2533a0c8e7"
 }

package/SKILL.md

@@ -1,180 +0,0 @@
----
-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
-
-导出方式：
-
-主入口 `index.ts` 通过 `export * from './exception'` 重新导出所有异常类，因此使用者可以从 `@hile/message-modem` 统一导入所有类型：
-
-```typescript
-import { MessageModem, Exception, AbortException, TimeoutException, MESSAGE_MODEM_TYPE } from '@hile/message-modem';
-```
-
-继承关系：
-
-```
-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>;
-  };
-  protected _push<T>(data: T, timeout?: number): void;
-  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>(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`** | 子类应自行决定暴露方式和命名 |
-| **`_push` 是 `protected`** | 单向推送（`twoway: false`），接收方不回复 RESPONSE |
-| **`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; } }
-// ✅ 让错误冒泡，框架会处理错误响应
-```