@hile/message-modem 1.0.0 → 1.0.1

package/README.md

@@ -62,15 +62,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}`);
   }
 }
 ```

package/SKILL.md

@@ -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';
+```
+
 继承关系：
 
 ```

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,71 @@
+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 msg - 消息数据
+     */
+    private onRequest;
+    /**
+     * 处理响应消息
+     * @param msg - 消息数据
+     */
+    private onResponse;
+    /**
+     * 接收消息
+     * @param msg - 消息数据
+     */
+    receive(msg: MessageTransferFormat): void;
+}

package/dist/index.js

@@ -0,0 +1,219 @@
+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) {
+        const id = this.createIncrementId();
+        const state = {
+            id, twoway: true, data, mode,
+        };
+        if (mode === MESSAGE_MODEM_TYPE.ABORT) {
+            state.twoway = false;
+        }
+        return state;
+    }
+    /**
+     * 发送消息
+     * @param data - 消息数据
+     * @param timeout - 超时时间
+     * @returns 消息响应
+     */
+    send(data, timeout = 30000) {
+        const controller = new AbortController();
+        // 创建请求消息数据
+        const state = this.createPostData(MESSAGE_MODEM_TYPE.REQUEST, data);
+        // 发送消息
+        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.1",
   "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": "b0adcecda8429e48dc29bc4658280954e837330b"
 }