xshell 1.0.43 → 1.0.45

package/file.js

@@ -234,11 +234,11 @@ export async function fmove(src, dst, { overwrite = false, print = true } = {})
         - overwrite?: `true`  默认覆盖（不检查效率更高）  better performance without check */
 export async function frename(fp, fp_, { fpd, print = true, overwrite = true } = {}) {
     if (fpd) {
-        fp = path.join(fpd, fp);
-        fp_ = path.join(fpd, fp_);
+        assert(fpd.isdir);
+        fp = fpd + fp;
+        fp_ = fpd + fp_;
     }
-    else if (!path.isAbsolute(fp) || !path.isAbsolute(fp_))
-        throw new Error(t('fp 和 fp_ 必须是绝对路径'));
+    assert(path.isAbsolute(fp) && path.isAbsolute(fp_), t('fp 和 fp_ 必须是绝对路径'));
     if (print)
         console.log(t('重命名'), fp, '→', fp_);
     if (!overwrite && fexists(fp_))
@@ -256,8 +256,18 @@ export async function frename(fp, fp_, { fpd, print = true, overwrite = true } =
 export async function fmkdir(fpd, { print = true, mode, } = {}) {
     assert(path.isAbsolute(fpd), t('fpd 必须是绝对路径: ') + fpd);
     assert(fpd.isdir, t('fpd 必须以 / 结尾: ') + fpd);
-    // CallingfsPromises.mkdir() when path is a directory that exists results in a rejection only when recursive is false.
-    const fpd_ = (await fsp.mkdir(fpd, { recursive: true, mode }))?.replaceAll('\\', '/');
+    // 类似 D:/ 这样的根路径，调用 fsp.mkdir 会报错无权限
+    if (fpd.length === 3 &&
+        'A' <= fpd[0] && fpd[0] <= 'Z' && fpd[1] === ':' && fpd[2] === '/')
+        if (fexists(fpd)) {
+            if (print)
+                console.log(t('已存在文件夹'), fpd);
+            return fpd;
+        }
+        else
+            throw new Error(t('不存在且无法创建文件夹 {{fpd}}', { fpd }));
+    // Calling fs.promises.mkdir() when path is a directory that exists results in a rejection only when recursive is false.
+    const fpd_ = (await fsp.mkdir(fpd, { recursive: true, mode }))?.fpd;
     if (fpd_) {
         if (print)
             console.log(t('已创建文件夹'), fpd);

package/net.browser.d.ts

@@ -125,10 +125,13 @@ export interface Message<TData extends any[] = any[]> {
     bins?: number[];
 }
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
-    调用方使用 remote.call 进行调用
-    被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
-    未连接时自动连接，断开后自动重连 (保证执行 send 时已连接，否则报错)
-    从设计上与 rpc 状态与底层连接的状态无关 (通过传入 url 创建的)，底层连接断开后，只要检测到断线，会尝试重连，如果重连成功，则不影响调用的状态
+    创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
+    使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
+    使用 remote.call 进行一元 rpc
+    使用 remote.send 结合 message.id 进行复杂 rpc
+    创建后等到首个 remote.call 或 remote.send 时自动建立实际 websocket 连接
+    rpc 状态与底层连接的状态无关，如果是传入 url 创建的 remote 实例，remote.send 时检测到断线会自动建立新的 websocket 连接
+    
     @example
     // Zero 继承自 Remote 并通过 call 实现了一些方法
     let zero = new Zero({ local: true })
@@ -145,42 +148,54 @@ export interface Message<TData extends any[] = any[]> {
     
     zero.send({ id, func: 'subscribe_stdio' }) */
 export declare class Remote {
-    /** 是否为建立 rpc 连接的发起方 */
+    /** 在构造 Remote 时, this.initiator = Boolean(url || websocket)
+        - true:  作为 websocket 连接发起方
+        - false: 作为 websocket 连接接收方 */
     initiator: boolean;
-    /** websocket url */
+    /** 作为 websocket 连接发起方，对端的 url 地址 */
     url?: string;
-    /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
+    /** 作为 websocket 连接发起方有 websocket lock */
     lwebsocket?: Lock<WebSocket>;
-    /** 通过 rpc message.func 被调用的 rpc 函数 */
+    /** websocket 连接发起方，接收方，都能被对端通过 (rpc message).func 调用的 rpc 函数 */
     funcs: Record<string, MessageHandler>;
-    /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
+    /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
+        一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers: Map<number, MessageHandler>;
+    /** `false` 打印所有交互的 rpc messages */
     print: boolean;
-    pconnect: Promise<any>;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse<TData extends any[] = any[]>(buffer: Uint8Array): Message<TData>;
     static pack({ id, func, data, done, error }: Message): Uint8Array;
-    /** 作为 rpc 发起方，可以通过传入 url 或者 websocket 定义远程 Remote
-        作为 rpc 接收方，可以不传 url 和 websocket 定义本地 Remote */
-    constructor({ url, funcs, websocket, on_error }?: {
+    /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
+        作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
+    constructor({ url, funcs, print, websocket, on_error }?: {
         url?: string;
         funcs?: Remote['funcs'];
+        print?: boolean;
         websocket?: WebSocket;
         on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
     });
     on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
-    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连
-        作为接收方需要传入使用的 websocket 连接，确保这个这个连接的状态 */
+    /** 幂等，保证 websocket 已连接，否则抛出异常
+        一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
+        连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，需要传入使用的 websocket 连接，确保这个这个连接的状态 */
     connect(websocket?: WebSocket): Promise<void>;
+    /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
     disconnect(): void;
-    /** 接收 websocket 连接的本地 remote 必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket_lock.resource
+    /** 发送 message 到对端 remote
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数
         发送或连接出错时自动清理 message.id 对应的 handler */
     send(message: Message, websocket?: WebSocket): Promise<void>;
-    /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
-        如果 message.done == true 则清理 handler
-        如果 handler 返回了值，则包装为 message 发送
+    /** 处理接收到的 websocket message 并解析, 根据 message.id 或 message.func 分发到对应的 handler 进行处理
+        如果 message.done == true 则对端指示当前 remote 可以清理 handler
+        如果 handler 返回了值 (一定是数组)，则包装为 message 发送
         使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214  */
     handle(data: Uint8Array, websocket: WebSocket): Promise<void>;
-    /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
-    call<TReturn extends any[] = any[]>(func: string, args?: any[]): Promise<TReturn>;
+    /** 调用对端 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应)
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数  */
+    call<TReturn extends any[] = any[]>(func: string, args?: any[], websocket?: WebSocket): Promise<TReturn>;
 }

package/net.browser.js

@@ -235,10 +235,13 @@ export async function connect_websocket(url, { protocols, on_message, on_error,
     });
 }
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
-    调用方使用 remote.call 进行调用
-    被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
-    未连接时自动连接，断开后自动重连 (保证执行 send 时已连接，否则报错)
-    从设计上与 rpc 状态与底层连接的状态无关 (通过传入 url 创建的)，底层连接断开后，只要检测到断线，会尝试重连，如果重连成功，则不影响调用的状态
+    创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
+    使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
+    使用 remote.call 进行一元 rpc
+    使用 remote.send 结合 message.id 进行复杂 rpc
+    创建后等到首个 remote.call 或 remote.send 时自动建立实际 websocket 连接
+    rpc 状态与底层连接的状态无关，如果是传入 url 创建的 remote 实例，remote.send 时检测到断线会自动建立新的 websocket 连接
+    
     @example
     // Zero 继承自 Remote 并通过 call 实现了一些方法
     let zero = new Zero({ local: true })
@@ -255,18 +258,21 @@ export async function connect_websocket(url, { protocols, on_message, on_error,
     
     zero.send({ id, func: 'subscribe_stdio' }) */
 export class Remote {
-    /** 是否为建立 rpc 连接的发起方 */
+    /** 在构造 Remote 时, this.initiator = Boolean(url || websocket)
+        - true:  作为 websocket 连接发起方
+        - false: 作为 websocket 连接接收方 */
     initiator;
-    /** websocket url */
+    /** 作为 websocket 连接发起方，对端的 url 地址 */
     url;
-    /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
+    /** 作为 websocket 连接发起方有 websocket lock */
     lwebsocket;
-    /** 通过 rpc message.func 被调用的 rpc 函数 */
+    /** websocket 连接发起方，接收方，都能被对端通过 (rpc message).func 调用的 rpc 函数 */
     funcs;
-    /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
+    /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
+        一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers = new Map();
+    /** `false` 打印所有交互的 rpc messages */
     print = false;
-    pconnect;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse(buffer) {
         const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -287,6 +293,7 @@ export class Remote {
         return message;
     }
     static pack({ id, func, data = [], done, error }) {
+        assert('length' in data, t('message.data 必须是数组'));
         let data_ = new Array(data.length);
         let bins = [];
         let bufs = [];
@@ -300,7 +307,6 @@ export class Remote {
             else
                 data_[i] = item;
         }
-        // 有可能 data_json 含有循环引用导致 JSON.stringify 报错
         const data_json = {
             id,
             ...func ? { func } : {},
@@ -309,27 +315,36 @@ export class Remote {
             ...data_.length ? { data: data_ } : {},
             ...bins.length ? { bins } : {},
         };
+        // 有可能 data_json 含有循环引用导致 JSON.stringify 报错
         const str_json = encoder.encode(JSON.stringify(data_json));
         let dv = new DataView(new ArrayBuffer(4));
         dv.setUint32(0, str_json.length, true);
         return concat([dv, str_json, ...bufs]);
     }
-    /** 作为 rpc 发起方，可以通过传入 url 或者 websocket 定义远程 Remote
-        作为 rpc 接收方，可以不传 url 和 websocket 定义本地 Remote */
-    constructor({ url, funcs = {}, websocket, on_error } = {}) {
+    /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
+        作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
+    constructor({ url, funcs, print, websocket, on_error } = {}) {
         assert(!(url && websocket), t('构建 Remote 时 url 和 websocket 最多只能传一个'));
         this.initiator = Boolean(url || websocket);
-        this.url = url;
-        this.funcs = funcs;
+        if (url)
+            this.url = url;
+        if (funcs)
+            this.funcs = funcs;
+        if (print !== undefined)
+            this.print = print;
         if (on_error)
             this.on_error = on_error;
-        this.lwebsocket = new Lock(websocket || null);
+        if (this.initiator)
+            this.lwebsocket = new Lock(websocket || null);
     }
     on_error(error, websocket) {
         throw error;
     }
-    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连
-        作为接收方需要传入使用的 websocket 连接，确保这个这个连接的状态 */
+    /** 幂等，保证 websocket 已连接，否则抛出异常
+        一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
+        连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，需要传入使用的 websocket 连接，确保这个这个连接的状态 */
     async connect(websocket) {
         if (this.initiator)
             if (this.lwebsocket.resource?.readyState === WebSocket.OPEN)
@@ -344,8 +359,6 @@ export class Remote {
                     // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
                     if (websocket?.readyState === WebSocket.OPEN)
                         return;
-                    else if (!this.url)
-                        throw new Error(t('创建 Remote 时传入的 websocket 连接已断开'));
                     else // 重连
                         this.lwebsocket.resource = await connect_websocket(this.url, {
                             on_message: (data, websocket) => {
@@ -354,29 +367,25 @@ export class Remote {
                             on_error: this.on_error.bind(this)
                         });
                 });
-        else if (websocket.readyState === WebSocket.OPEN)
-            return;
-        else
+        else if (websocket.readyState !== WebSocket.OPEN)
             throw new Error(t('传入的 websocket 连接已断开'));
     }
+    /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
     disconnect() {
         this.lwebsocket.resource?.close(1000);
     }
-    /** 接收 websocket 连接的本地 remote 必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket_lock.resource
+    /** 发送 message 到对端 remote
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数
         发送或连接出错时自动清理 message.id 对应的 handler */
     async send(message, websocket) {
+        if (this.print)
+            console.log('remote.send:', message);
         try {
-            if (this.initiator) {
-                assert(!websocket || websocket === this.lwebsocket.resource);
-                await this.connect();
-                websocket = this.lwebsocket.resource;
-            }
-            else
-                await this.connect(websocket);
+            await this.connect(websocket);
             if (!message.id)
                 message.id = genid();
-            // 不需要独占 websocket
-            websocket.send(Remote.pack(message));
+            (websocket || this.lwebsocket.resource).send(Remote.pack(message));
         }
         catch (error) {
             if (message.id)
@@ -384,21 +393,21 @@ export class Remote {
             throw error;
         }
     }
-    /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
-        如果 message.done == true 则清理 handler
-        如果 handler 返回了值，则包装为 message 发送
+    /** 处理接收到的 websocket message 并解析, 根据 message.id 或 message.func 分发到对应的 handler 进行处理
+        如果 message.done == true 则对端指示当前 remote 可以清理 handler
+        如果 handler 返回了值 (一定是数组)，则包装为 message 发送
         使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214  */
     async handle(data, websocket) {
         const message = Remote.parse(data);
         const { id, func, done } = message;
         if (this.print)
-            console.log(message);
+            console.log('remote.handle:', message);
         let handler;
         if (func)
             handler = this.funcs[func];
         else {
             handler = this.handlers.get(id);
-            if (done)
+            if (done && handler)
                 this.handlers.delete(id);
         }
         try {
@@ -421,8 +430,10 @@ export class Remote {
             throw error;
         }
     }
-    /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
-    async call(func, args) {
+    /** 调用对端 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应)
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数  */
+    async call(func, args, websocket) {
         return new Promise(async (resolve, reject) => {
             const id = genid();
             this.handlers.set(id, (message) => {
@@ -434,7 +445,7 @@ export class Remote {
                 this.handlers.delete(id);
             });
             try {
-                await this.send({ id, func, data: args }); // 不需要 done: true, 因为对面的 remote.handlers 中不会有这个 id 的 handler
+                await this.send({ id, func, data: args }, websocket); // 不需要 done: true, 因为对面的 remote.handlers 中不会有这个 id 的 handler
             }
             catch (error) {
                 reject(error);

package/net.d.ts

@@ -173,10 +173,13 @@ export interface Message<TData extends any[] = any[]> {
     bins?: number[];
 }
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
-    调用方使用 remote.call 进行调用
-    被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
-    未连接时自动连接，断开后自动重连 (保证执行 send 时已连接，否则报错)
-    从设计上与 rpc 状态与底层连接的状态无关 (通过传入 url 创建的)，底层连接断开后，只要检测到断线，会尝试重连，如果重连成功，则不影响调用的状态
+    创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
+    使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
+    使用 remote.call 进行一元 rpc
+    使用 remote.send 结合 message.id 进行复杂 rpc
+    创建后等到首个 remote.call 或 remote.send 时自动建立实际 websocket 连接
+    rpc 状态与底层连接的状态无关，如果是传入 url 创建的 remote 实例，remote.send 时检测到断线会自动建立新的 websocket 连接
+    
     @example
     // Zero 继承自 Remote 并通过 call 实现了一些方法
     let zero = new Zero({ local: true })
@@ -193,42 +196,59 @@ export interface Message<TData extends any[] = any[]> {
     
     zero.send({ id, func: 'subscribe_stdio' }) */
 export declare class Remote {
-    /** 是否为建立 rpc 连接的发起方 */
+    /** 在构造 Remote 时, this.initiator = Boolean(url || websocket)
+        - true:  作为 websocket 连接发起方
+        - false: 作为 websocket 连接接收方 */
     initiator: boolean;
-    /** websocket url */
+    /** 作为 websocket 连接发起方，对端的 url 地址 */
     url?: string;
-    /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
+    /** 作为 websocket 连接发起方有 websocket lock */
     lwebsocket?: Lock<WebSocket>;
-    /** 通过 rpc message.func 被调用的 rpc 函数 */
+    /** websocket 连接发起方，接收方，都能被对端通过 (rpc message).func 调用的 rpc 函数 */
     funcs: Record<string, MessageHandler>;
-    /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
+    /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
+        一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers: Map<number, MessageHandler>;
+    /** `false` 打印所有交互的 rpc messages */
     print: boolean;
-    pconnect: Promise<any>;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse<TData extends any[] = any[]>(buffer: Uint8Array): Message<TData>;
     static pack({ id, func, data, done, error }: Message): Uint8Array;
-    /** 作为 rpc 发起方，可以通过传入 url 或者 websocket 定义远程 Remote
-        作为 rpc 接收方，可以不传 url 和 websocket 定义本地 Remote */
-    constructor({ url, funcs, websocket, on_error }?: {
+    /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
+        作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
+    constructor({ url, funcs, print, websocket, on_error }?: {
         url?: string;
         funcs?: Remote['funcs'];
+        print?: boolean;
         websocket?: WebSocket;
         on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
     });
     on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
-    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连
-        作为接收方需要传入使用的 websocket 连接，确保这个这个连接的状态 */
+    /** 幂等，保证 websocket 已连接，否则抛出异常
+        一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
+        连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，需要传入使用的 websocket 连接，确保这个这个连接的状态 */
     connect(websocket?: WebSocket): Promise<void>;
+    /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
     disconnect(): void;
-    /** 接收 websocket 连接的本地 remote 必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket_lock.resource
+    /** 发送 message 到对端 remote
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数
         发送或连接出错时自动清理 message.id 对应的 handler */
     send(message: Message, websocket?: WebSocket): Promise<void>;
-    /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
-        如果 message.done == true 则清理 handler
-        如果 handler 返回了值，则包装为 message 发送
+    /** 处理接收到的 websocket message 并解析, 根据 message.id 或 message.func 分发到对应的 handler 进行处理
+        如果 message.done == true 则对端指示当前 remote 可以清理 handler
+        如果 handler 返回了值 (一定是数组)，则包装为 message 发送
         使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214  */
     handle(data: Uint8Array, websocket: WebSocket): Promise<void>;
-    /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
-    call<TReturn extends any[] = any[]>(func: string, args?: any[]): Promise<TReturn>;
+    /** 调用对端 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应)
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数  */
+    call<TReturn extends any[] = any[]>(func: string, args?: any[], websocket?: WebSocket): Promise<TReturn>;
+}
+/** 通常将连接到 server 的 client 抽象为下面的结构 */
+export interface RemoteClient {
+    remote: Remote;
+    websocket: WebSocket;
 }

package/net.js

@@ -388,10 +388,13 @@ on_message, on_error, on_close }) {
     });
 }
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
-    调用方使用 remote.call 进行调用
-    被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
-    未连接时自动连接，断开后自动重连 (保证执行 send 时已连接，否则报错)
-    从设计上与 rpc 状态与底层连接的状态无关 (通过传入 url 创建的)，底层连接断开后，只要检测到断线，会尝试重连，如果重连成功，则不影响调用的状态
+    创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
+    使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
+    使用 remote.call 进行一元 rpc
+    使用 remote.send 结合 message.id 进行复杂 rpc
+    创建后等到首个 remote.call 或 remote.send 时自动建立实际 websocket 连接
+    rpc 状态与底层连接的状态无关，如果是传入 url 创建的 remote 实例，remote.send 时检测到断线会自动建立新的 websocket 连接
+    
     @example
     // Zero 继承自 Remote 并通过 call 实现了一些方法
     let zero = new Zero({ local: true })
@@ -408,18 +411,21 @@ on_message, on_error, on_close }) {
     
     zero.send({ id, func: 'subscribe_stdio' }) */
 export class Remote {
-    /** 是否为建立 rpc 连接的发起方 */
+    /** 在构造 Remote 时, this.initiator = Boolean(url || websocket)
+        - true:  作为 websocket 连接发起方
+        - false: 作为 websocket 连接接收方 */
     initiator;
-    /** websocket url */
+    /** 作为 websocket 连接发起方，对端的 url 地址 */
     url;
-    /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
+    /** 作为 websocket 连接发起方有 websocket lock */
     lwebsocket;
-    /** 通过 rpc message.func 被调用的 rpc 函数 */
+    /** websocket 连接发起方，接收方，都能被对端通过 (rpc message).func 调用的 rpc 函数 */
     funcs;
-    /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
+    /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
+        一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers = new Map();
+    /** `false` 打印所有交互的 rpc messages */
     print = false;
-    pconnect;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse(buffer) {
         const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -440,6 +446,7 @@ export class Remote {
         return message;
     }
     static pack({ id, func, data = [], done, error }) {
+        assert('length' in data, t('message.data 必须是数组'));
         let data_ = new Array(data.length);
         let bins = [];
         let bufs = [];
@@ -453,7 +460,6 @@ export class Remote {
             else
                 data_[i] = item;
         }
-        // 有可能 data_json 含有循环引用导致 JSON.stringify 报错
         const data_json = {
             id,
             ...func ? { func } : {},
@@ -462,27 +468,36 @@ export class Remote {
             ...data_.length ? { data: data_ } : {},
             ...bins.length ? { bins } : {},
         };
+        // 有可能 data_json 含有循环引用导致 JSON.stringify 报错
         const str_json = encoder.encode(JSON.stringify(data_json));
         let dv = new DataView(new ArrayBuffer(4));
         dv.setUint32(0, str_json.length, true);
         return concat([dv, str_json, ...bufs]);
     }
-    /** 作为 rpc 发起方，可以通过传入 url 或者 websocket 定义远程 Remote
-        作为 rpc 接收方，可以不传 url 和 websocket 定义本地 Remote */
-    constructor({ url, funcs = {}, websocket, on_error } = {}) {
+    /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
+        作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
+    constructor({ url, funcs, print, websocket, on_error } = {}) {
         assert(!(url && websocket), t('构建 Remote 时 url 和 websocket 最多只能传一个'));
         this.initiator = Boolean(url || websocket);
-        this.url = url;
-        this.funcs = funcs;
+        if (url)
+            this.url = url;
+        if (funcs)
+            this.funcs = funcs;
+        if (print !== undefined)
+            this.print = print;
         if (on_error)
             this.on_error = on_error;
-        this.lwebsocket = new Lock(websocket || null);
+        if (this.initiator)
+            this.lwebsocket = new Lock(websocket || null);
     }
     on_error(error, websocket) {
         throw error;
     }
-    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连
-        作为接收方需要传入使用的 websocket 连接，确保这个这个连接的状态 */
+    /** 幂等，保证 websocket 已连接，否则抛出异常
+        一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
+        连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，需要传入使用的 websocket 连接，确保这个这个连接的状态 */
     async connect(websocket) {
         if (this.initiator)
             if (this.lwebsocket.resource?.readyState === WebSocket.OPEN)
@@ -497,8 +512,6 @@ export class Remote {
                     // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
                     if (websocket?.readyState === WebSocket.OPEN)
                         return;
-                    else if (!this.url)
-                        throw new Error(t('创建 Remote 时传入的 websocket 连接已断开'));
                     else // 重连
                         this.lwebsocket.resource = await connect_websocket(this.url, {
                             on_message: (data, websocket) => {
@@ -507,29 +520,25 @@ export class Remote {
                             on_error: this.on_error.bind(this)
                         });
                 });
-        else if (websocket.readyState === WebSocket.OPEN)
-            return;
-        else
+        else if (websocket.readyState !== WebSocket.OPEN)
             throw new Error(t('传入的 websocket 连接已断开'));
     }
+    /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
     disconnect() {
         this.lwebsocket.resource?.close(1000);
     }
-    /** 接收 websocket 连接的本地 remote 必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket_lock.resource
+    /** 发送 message 到对端 remote
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数
         发送或连接出错时自动清理 message.id 对应的 handler */
     async send(message, websocket) {
+        if (this.print)
+            console.log('remote.send:', message);
         try {
-            if (this.initiator) {
-                assert(!websocket || websocket === this.lwebsocket.resource);
-                await this.connect();
-                websocket = this.lwebsocket.resource;
-            }
-            else
-                await this.connect(websocket);
+            await this.connect(websocket);
             if (!message.id)
                 message.id = genid();
-            // 不需要独占 websocket
-            websocket.send(Remote.pack(message));
+            (websocket || this.lwebsocket.resource).send(Remote.pack(message));
         }
         catch (error) {
             if (message.id)
@@ -537,21 +546,21 @@ export class Remote {
             throw error;
         }
     }
-    /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
-        如果 message.done == true 则清理 handler
-        如果 handler 返回了值，则包装为 message 发送
+    /** 处理接收到的 websocket message 并解析, 根据 message.id 或 message.func 分发到对应的 handler 进行处理
+        如果 message.done == true 则对端指示当前 remote 可以清理 handler
+        如果 handler 返回了值 (一定是数组)，则包装为 message 发送
         使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214  */
     async handle(data, websocket) {
         const message = Remote.parse(data);
         const { id, func, done } = message;
         if (this.print)
-            console.log(message);
+            console.log('remote.handle:', message);
         let handler;
         if (func)
             handler = this.funcs[func];
         else {
             handler = this.handlers.get(id);
-            if (done)
+            if (done && handler)
                 this.handlers.delete(id);
         }
         try {
@@ -574,8 +583,10 @@ export class Remote {
             throw error;
         }
     }
-    /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
-    async call(func, args) {
+    /** 调用对端 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应)
+        作为 websocket 连接发起方，不需要传入 websocket
+        作为 websocket 连接接收方，必传 websocket 参数  */
+    async call(func, args, websocket) {
         return new Promise(async (resolve, reject) => {
             const id = genid();
             this.handlers.set(id, (message) => {
@@ -587,7 +598,7 @@ export class Remote {
                 this.handlers.delete(id);
             });
             try {
-                await this.send({ id, func, data: args }); // 不需要 done: true, 因为对面的 remote.handlers 中不会有这个 id 的 handler
+                await this.send({ id, func, data: args }, websocket); // 不需要 done: true, 因为对面的 remote.handlers 中不会有这个 id 的 handler
             }
             catch (error) {
                 reject(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xshell",
-  "version": "1.0.43",
+  "version": "1.0.45",
   "type": "module",
   "main": "./index.js",
   "bin": {
@@ -45,9 +45,9 @@
     ]
   },
   "dependencies": {
-    "@babel/core": "^7.22.9",
-    "@babel/parser": "^7.22.7",
-    "@babel/traverse": "^7.22.8",
+    "@babel/core": "^7.22.10",
+    "@babel/parser": "^7.22.10",
+    "@babel/traverse": "^7.22.10",
     "@koa/cors": "^4.0.0",
     "@types/ws": "^8.5.5",
     "byte-size": "^8.1.1",
@@ -62,7 +62,7 @@
     "fs-extra": "^11.1.1",
     "gulp-sort": "^2.0.0",
     "hash-string": "^1.0.0",
-    "i18next": "^23.2.11",
+    "i18next": "^23.4.2",
     "i18next-scanner": "^4.3.0",
     "js-cookie": "^3.0.5",
     "koa": "^2.14.2",
@@ -71,44 +71,44 @@
     "lodash": "^4.17.21",
     "map-stream": "0.0.7",
     "mime-types": "^2.1.35",
-    "ora": "^6.3.1",
+    "ora": "^7.0.1",
     "qs": "^6.11.2",
     "react": "^18.2.0",
-    "react-i18next": "^13.0.2",
+    "react-i18next": "^13.0.3",
     "resolve-path": "^1.4.0",
     "strip-ansi": "^7.1.0",
     "through2": "^4.0.2",
     "tough-cookie": "^4.1.3",
     "tslib": "^2.6.1",
     "typescript": "^5.1.6",
-    "undici": "^5.22.1",
+    "undici": "^5.23.0",
     "vinyl": "^3.0.0",
     "vinyl-fs": "^4.0.0",
     "ws": "^8.13.0"
   },
   "devDependencies": {
-    "@babel/types": "^7.22.5",
+    "@babel/types": "^7.22.10",
     "@types/babel__traverse": "^7.20.1",
     "@types/byte-size": "^8.1.0",
     "@types/chardet": "^0.8.1",
     "@types/fs-extra": "^11.0.1",
     "@types/gulp-sort": "2.0.1",
     "@types/js-cookie": "^3.0.3",
-    "@types/koa": "^2.13.6",
+    "@types/koa": "^2.13.8",
     "@types/koa-compress": "^4.0.3",
-    "@types/lodash": "^4.14.195",
+    "@types/lodash": "^4.14.196",
     "@types/mime-types": "^2.1.1",
-    "@types/node": "^20.4.4",
+    "@types/node": "^20.4.8",
     "@types/qs": "^6.9.7",
-    "@types/react": "^18.2.16",
+    "@types/react": "^18.2.18",
     "@types/through2": "^2.0.38",
     "@types/tough-cookie": "^4.0.2",
     "@types/vinyl-fs": "^3.0.2",
-    "@types/vscode": "^1.80.0",
-    "@typescript-eslint/eslint-plugin": "^6.2.0",
-    "@typescript-eslint/parser": "^6.2.0",
-    "eslint": "^8.45.0",
-    "eslint-plugin-react": "^7.33.0",
+    "@types/vscode": "^1.81.0",
+    "@typescript-eslint/eslint-plugin": "^6.3.0",
+    "@typescript-eslint/parser": "^6.3.0",
+    "eslint": "^8.46.0",
+    "eslint-plugin-react": "^7.33.1",
     "eslint-plugin-xlint": "^1.0.6"
   },
   "scripts": {

package/process.d.ts

@@ -48,6 +48,7 @@ interface StartOptions {
         - detached?: `false` 是否断开和 child 的关系 (ignore stdio, unref)  whether to break the connection with child (ignore stdio, unref)
 */
 export declare function start(exe: string, args?: string[], { cwd, encoding, print, stdio, detached, env, window: _window, }?: StartOptions): Promise<ChildProcess>;
+export declare function start_nodejs(js: string, args?: string[], options?: StartOptions): Promise<ChildProcess>;
 export interface CallOptions extends StartOptions {
     throw_code?: boolean;
     input?: string;

package/process.js

@@ -80,6 +80,9 @@ export async function start(exe, args = [], { cwd, encoding = 'utf-8', print = t
     }
     return child;
 }
+export async function start_nodejs(js, args = [], options) {
+    return start(exe_nodejs, [js, ...args], options);
+}
 export async function call(exe, args = [], options = {}) {
     const { encoding = 'utf-8', throw_code = true, input, } = options;
     let { stdio = 'pipe', print = true } = options;
@@ -204,7 +207,7 @@ export async function term_nodejs(fp_js, args = [], { title, inspect, tsnode = f
         ...resolve ? ['--experimental-specifier-resolution=node'] : [],
         ...title ? [`--title=${title}`] : [],
         ...inspect ? [
-            _break ? `--inspect-brk=0.0.0.0:${inspect}` : `--inspect=0.0.0.0:${inspect}`
+            _break ? `--inspect-brk=localhost:${inspect}` : `--inspect=localhost:${inspect}`
         ] : [],
         ...tsnode ? [
             '--loader=ts-node/esm',

package/repl.d.ts

@@ -4,7 +4,7 @@ import type { Context } from 'koa';
 import './prototype.js';
 declare global {
     var __: any;
-    var started_at: Date;
+    var tstarted: Date;
     var repl_router: (ctx: Context) => Promise<boolean>;
 }
 /** 谨慎使用，webpack 打包后可能会变成 /d:/1/mod/node_modules/xshell/ 这样的编译期路径 */

package/repl.js

@@ -54,14 +54,14 @@ function trans_import_2_require(import_decl) {
     // (import_clause.namedBindings as NamedImports).elements
     return [
         // import mod from 'mod'
-        // global.mod = __importDefault(require("mod")).default
+        // globalThis.mod = __importDefault(require("mod")).default
         ...import_clause.name ? [
-            factory.createExpressionStatement(factory.createAssignment(factory.createPropertyAccessExpression(factory.createIdentifier('global'), import_clause.name), factory.createPropertyAccessExpression(factory.createCallExpression(factory.createIdentifier('__importDefault'), [], [require_module_stmt]), 'default')))
+            factory.createExpressionStatement(factory.createAssignment(factory.createPropertyAccessExpression(factory.createIdentifier('globalThis'), import_clause.name), factory.createPropertyAccessExpression(factory.createCallExpression(factory.createIdentifier('__importDefault'), [], [require_module_stmt]), 'default')))
         ] : [],
         // import * as mod from 'mod'
-        // global.mod = __importStar(require("mod"))
+        // globalThis.mod = __importStar(require("mod"))
         ...import_clause.namedBindings && isNamespaceImport(import_clause.namedBindings) ? [
-            factory.createExpressionStatement(factory.createAssignment(factory.createPropertyAccessExpression(factory.createIdentifier('global'), import_clause.namedBindings.name), factory.createCallExpression(factory.createIdentifier('__importStar'), [], [require_module_stmt])))
+            factory.createExpressionStatement(factory.createAssignment(factory.createPropertyAccessExpression(factory.createIdentifier('globalThis'), import_clause.namedBindings.name), factory.createCallExpression(factory.createIdentifier('__importStar'), [], [require_module_stmt])))
         ] : [],
         // import { element2 as element2_, element3 as element3_, other, default as mod2 } from 'mod2'
         ...import_clause.namedBindings && isNamedImports(import_clause.namedBindings) ? [
@@ -69,10 +69,10 @@ function trans_import_2_require(import_decl) {
             factory.createVariableStatement([], [factory.createVariableDeclaration(factory.createObjectBindingPattern(
                 // ImportSpecifier[] -> ObjectBindingPattern.BindingElement[]
                 import_clause.namedBindings.elements.map(import_specifier => factory.createBindingElement(undefined, import_specifier.propertyName, import_specifier.name, import_specifier.propertyName?.text === 'default' ? require_module_stmt : undefined))), undefined, undefined, require_module_stmt)]),
-            // Object.assign(global, { element2_, element3 })
+            // Object.assign(globalThis, { element2_, element3 })
             factory.createExpressionStatement(factory.createCallExpression(factory.createPropertyAccessExpression(factory.createIdentifier('Object'), 'assign'), [], 
             // ImportSpecifier[] -> ObjectBindingPattern.BindingElement[]
-            [factory.createIdentifier('global'), factory.createObjectLiteralExpression(import_clause.namedBindings.elements.map(import_specifier => factory.createShorthandPropertyAssignment(import_specifier.name)), false)])),
+            [factory.createIdentifier('globalThis'), factory.createObjectLiteralExpression(import_clause.namedBindings.elements.map(import_specifier => factory.createShorthandPropertyAssignment(import_specifier.name)), false)])),
             factory.createExpressionStatement(import_clause.namedBindings.elements.length === 1 ?
                 // (a)
                 factory.createParenthesizedExpression(import_clause.namedBindings.elements[0].name)
@@ -111,7 +111,7 @@ function trans_class_decl_2_expr(class_decl) {
         return class_decl;
     // export class C { } 这样的语句已经在 trans_export_stmt 中被去掉了 export modifier
     return factory.createVariableStatement([], factory.createVariableDeclarationList([
-        factory.createVariableDeclaration(class_decl.name, undefined, undefined, factory.createClassExpression(undefined, class_decl.name, undefined, undefined, class_decl.members))
+        factory.createVariableDeclaration(class_decl.name, undefined, undefined, factory.createClassExpression(undefined, class_decl.name, undefined, class_decl.heritageClauses, class_decl.members))
     ]));
 }
 function get_expr_of_stmt(statement) {
@@ -141,7 +141,7 @@ function trans_return_2_expr(stmt) {
         return stmt;
     return factory.createExpressionStatement(stmt.expression);
 }
-function assign_var_decl(var_decl, destination = 'global') {
+function assign_var_decl(var_decl, destination = 'globalThis') {
     if (!isVariableStatement(var_decl))
         return [var_decl];
     // VariableDeclaration[] -> ObjectLiteral[]
@@ -243,7 +243,7 @@ export async function eval_ts(code) {
 export async function repl_ts(code) {
     console.log(); // 离之前的输出有一个空行
     const timer = new Timer();
-    const __ = global.__ = await eval_ts(code);
+    const __ = globalThis.__ = await eval_ts(code);
     timer.stop();
     console.log(inspect(__, { limit: inspection_limit }));
     if (timer.get() >= 500)
@@ -292,7 +292,7 @@ export async function start_repl() {
         })(),
     ]);
     console.log(('-'.repeat(30) + '\n' +
-        t('xshell 启动成功，用时 ') + delta2str(new Date().getTime() - global.started_at.getTime()) + '\n' +
+        t('xshell 启动成功，用时 ') + delta2str(new Date().getTime() - globalThis.tstarted.getTime()) + '\n' +
         t('正在监听: http://localhost:8421\n') +
         '-'.repeat(30)).green);
 }
@@ -306,7 +306,7 @@ export async function exit() {
     process.exit();
 }
 export async function pollute_global() {
-    Object.assign(global, {
+    Object.assign(globalThis, {
         __importDefault: (mod) => ((mod?.__esModule) ? mod : { default: mod }),
         __importStar: (mod) => {
             if (mod?.__esModule)
@@ -320,7 +320,7 @@ export async function pollute_global() {
             result.default = mod;
             return result;
         },
-        exports: global
+        exports: globalThis
     });
     await Promise.all([
         pollute_module_default_export('lodash/omit.js', 'omit'),
@@ -339,9 +339,9 @@ export async function pollute_global() {
     console.log(t('所有模块加载成功'));
 }
 export async function pollute_module_exports(fp_mod) {
-    Object.assign(global, await import(fp_mod));
+    Object.assign(globalThis, await import(fp_mod));
 }
 export async function pollute_module_default_export(fp_mod, name) {
-    global[name] = (await import(fp_mod)).default;
+    globalThis[name] = (await import(fp_mod)).default;
 }
 //# sourceMappingURL=repl.js.map

package/server.js

@@ -156,7 +156,7 @@ export class Server {
         // ------------ log
         this.logger(ctx);
         // ------------ repl_router hook
-        if (await global.repl_router?.(ctx))
+        if (await globalThis.repl_router?.(ctx))
             return;
         if (await this.router(ctx))
             return;

package/utils.d.ts

@@ -89,7 +89,7 @@ export declare function has_chinese(str: string): boolean;
 export declare function escape_line_feed(str: string): string;
 /** util.inspect(obj)
     - options
-        - limit?: `10000`
+        - limit?: `10000`  传 0 时不限制
         - omit?: string[] */
 export declare function inspect(obj: any, options?: util.InspectOptions & {
     limit?: number;

package/utils.js

@@ -1,6 +1,5 @@
 import { Stream, Writable, Transform } from 'stream';
 import util from 'util';
-import omit from 'lodash/omit.js';
 import { t } from './i18n/instance.js';
 import './prototype.js';
 export const noop = () => { };
@@ -253,16 +252,20 @@ export function escape_line_feed(str) {
 }
 /** util.inspect(obj)
     - options
-        - limit?: `10000`
+        - limit?: `10000`  传 0 时不限制
         - omit?: string[] */
 export function inspect(obj, options = {}) {
-    if (options.omit)
-        obj = omit(obj, [inspect.custom, ...(options.omit || [])]);
+    if (options.omit) {
+        obj = { ...obj };
+        for (const key of options.omit)
+            delete obj[key];
+        // 改变了 obj 的引用，去掉 inspect.custom 防止无限递归 inspect
+        delete obj[inspect.custom];
+    }
     let text = util.inspect(obj, options);
-    if (!('limit' in options))
-        options.limit = 10000;
-    if (options.limit && text.length > options.limit)
-        return `${text.slice(0, options.limit)}……'\u001b[39m\n`;
+    const limit = options.limit ?? 10000;
+    if (limit && text.length > limit)
+        return `${text.slice(0, limit)}……'\u001b[39m\n`;
     else
         return text;
 }

package/xshell.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-global.started_at = new Date();
+globalThis.tstarted = new Date();
 import { start_repl } from './repl.js';
 start_repl();
 //# sourceMappingURL=xshell.js.map