xshell 1.3.3 → 1.3.5

package/file.d.ts

@@ -115,7 +115,7 @@ export interface FListOptions {
     stats?: boolean;
     best_effort?: boolean;
 }
-/**
+/** 列出文件夹，默认返回文件名列表，也可以传入 stats 选项返回元数据
     - fpd: 文件夹完整路径 absolute path of directory
     - options?:
         - deep?: `false` 递归遍历 recursively

package/git.js

@@ -98,7 +98,7 @@ export class Git {
             '--prune'
         ], print_stdout);
         if (print)
-            console.log('更新远程分支成功');
+            console.log(`${this.cwd.fname.slice(0, -1)} 更新远程分支成功`);
     }
     async checkout(branch = 'main') {
         let create = false;

package/net.d.ts

@@ -1,7 +1,8 @@
+import net from 'node:net';
 import { type Readable } from 'node:stream';
 import type { Cookie, CookieJar, MemoryCookieStore } from 'tough-cookie';
 import type { Encoding } from './file.ts';
-import { inspect } from './utils.ts';
+import { inspect, type Deferred2 } from './utils.ts';
 import { type BasicAuth, type BearerAuth } from './net.common.ts';
 export * from './net.common.ts';
 export declare enum MyProxy {
@@ -48,7 +49,6 @@ export interface RequestOptions {
         retry: boolean;
         timeout: boolean;
     };
-    long_connection?: true;
 }
 export interface RequestFullOptions extends RequestOptions {
     full: true;
@@ -97,8 +97,7 @@ export declare class StatusCodeError extends Error {
         - decode?: `true` 根据 content-encoding: br 等解码压缩后的 response.body
         - print?:
             - retry: `true` 是否打印 "等待 1 秒后重试 request" 提示信息
-            - timeout: `true` 是否打印最后一次超时重试失败时的错误
-        - long_connection?: 用于保持长 tcp 连接，保留 nat 端口映射记录 */
+            - timeout: `true` 是否打印最后一次超时重试失败时的错误 */
 export declare function request(url: string | URL): Promise<string>;
 export declare function request(url: string | URL, options: RequestRawOptions): Promise<RawResponse>;
 export declare function request(url: string | URL, options: RequestFullOptions & {
@@ -111,3 +110,21 @@ export declare function request(url: string | URL, options: RequestOptions & {
 export declare function request(url: string | URL, options: RequestOptions): Promise<string>;
 /** 发起 http 请求并将响应体作为 json 解析 */
 export declare function request_json<T = any>(url: string | URL, options?: RequestOptions): Promise<T>;
+export interface ConnectOptions {
+    timeout?: number;
+    print?: {
+        error: boolean;
+        connect: boolean;
+    };
+}
+/** 建立 tcp 连接，超时时间为 2 秒 (timeout 选项)，返回已连接的 socket
+    连接中遇到的错误会 reject，之后取消监听 error 事件，由调用者 attach 处理
+    - hostname: 要连接到的 ip 或域名
+    - port: 要连接的端口
+    - options?:
+        - timeout?: `2000` 超时时间
+        - print?: 打印连接日志，错误日志
+            - error?: `true`
+            - connect: `false` */
+export declare function connect(hostname: string, port: number, { timeout: _timeout, print }?: ConnectOptions): Deferred2<net.Socket>;
+export declare function get_socket_ip(socket: net.Socket): string;

package/net.js

@@ -1,7 +1,9 @@
 import zlib from 'node:zlib';
+import net from 'node:net';
 import { buffer as stream_to_buffer, text as stream_to_text } from 'node:stream/consumers';
-import { isReadable } from 'node:stream';
-import { inspect, assert, delay, pipe_with_error, map_values, unique, timeout, check, colored, encode } from "./utils.js";
+import { pipeline, isReadable } from 'node:stream';
+import { noop } from "./prototype.js";
+import { inspect, assert, delay, map_values, unique, timeout, check, colored, encode, TimeoutError, set_error_message, defer2 } from "./utils.js";
 import { drop_request_headers } from "./net.common.js";
 export * from "./net.common.js";
 export var MyProxy;
@@ -32,27 +34,25 @@ async function request_retry(url, options, _timeout, retries = 0, count = 0, pri
             // 设置给 undici 设置 timeout, signal 不一定管用，还是得自己兜底
             options.signal = AbortSignal.timeout(_timeout);
             return await timeout(_timeout + 300, // 为 undici 兜底
-            undici.request(url, options), undefined, print.timeout && count >= retries // 只打印最后一次超时的错误，避免太多冗余输出
-            );
+            undici.request(url, options), undefined, print.timeout && count >= retries); // 只打印最后一次超时的错误，避免太多冗余输出
         }
         else
             return await undici.request(url, options);
     }
     catch (error) {
-        if (error.name === 'TimeoutError')
-            if (count < retries) {
-                const duration = 2 ** count;
-                if (print.retry)
-                    console.log(`${`等待 ${duration} 秒后重试请求 (已尝试 ${count + 1} 次) ··`.yellow}  ${url.toString().blue.underline}`);
-                await delay(1000 * duration);
-                return request_retry(url, options, _timeout, retries, count + 1, print);
-            }
-            else {
-                const seconds = _timeout / 1000;
-                throw Object.assign(new Error(`请求超过 ${seconds.toFixed(seconds < 1 ? 1 : 0)} 秒等待时间: ${url.toString()}`), { name: 'TimeoutError' });
-            }
-        else
+        if (error.name !== 'TimeoutError')
             throw error;
+        // 重试次数内
+        if (count < retries) {
+            const duration = 2 ** count;
+            if (print.retry)
+                console.log(`等待 ${duration} 秒后重试请求 (已尝试 ${count + 1} 次) ··`.yellow + '  ' +
+                    url.toString().blue.underline);
+            await delay(1000 * duration);
+            return request_retry(url, options, _timeout, retries, count + 1, print);
+        }
+        const seconds = _timeout / 1000;
+        throw new TimeoutError(`请求超过 ${seconds.toFixed(seconds < 1 ? 1 : 0)} 秒等待时间: ${url.toString()}`);
     }
 }
 export class StatusCodeError extends Error {
@@ -71,7 +71,7 @@ export async function request(url, options = {}) {
     const { queries, headers: _headers, body, type = 'application/json', timeout = 5 * 1000, auth, cookies: _cookies, raw = false, full = false, redirect = 'follow', decode = true, print = {
         timeout: true,
         retry: true
-    }, long_connection } = options;
+    } } = options;
     let { method, retries, encoding, proxy, } = options;
     url = new URL(url);
     if (queries)
@@ -128,7 +128,7 @@ export async function request(url, options = {}) {
         proxy = MyProxy.socks5;
     let undici_options = {
         ...method ? { method } : {},
-        dispatcher: get_dispatcher(proxy, redirect, long_connection),
+        dispatcher: get_dispatcher(proxy, redirect),
         // 下面这些 timeout 都不是总的时间
         headersTimeout: timeout,
         // 从收完 headers 开始算
@@ -155,30 +155,26 @@ export async function request(url, options = {}) {
             switch (content_encoding) {
                 case 'gzip':
                 case 'x-gzip':
-                    body = pipe_with_error(_body, zlib.createGunzip({
+                    body = pipeline(_body, zlib.createGunzip({
                         // Be less strict when decoding compressed responses, since sometimes
                         // servers send slightly invalid responses that are still accepted
                         // by common browsers.
                         // Always using Z_SYNC_FLUSH is what cURL does.
                         flush: zlib.constants.Z_SYNC_FLUSH,
                         finishFlush: zlib.constants.Z_SYNC_FLUSH
-                    }));
+                    }), noop);
                     break;
                 case 'deflate':
-                    body = pipe_with_error(_body, zlib.createInflate());
+                    body = pipeline(_body, zlib.createInflate(), noop);
                     break;
                 case 'br':
-                    body = pipe_with_error(_body, zlib.createBrotliDecompress());
+                    body = pipeline(_body, zlib.createBrotliDecompress(), noop);
                     break;
                 default:
                     throw new Error(`不支持 content-encoding: ${content_encoding.quote()} 的 http 请求`);
             }
         }
-        response = {
-            status,
-            headers,
-            body
-        };
+        response = { status, headers, body };
         if (!((200 <= status && status <= 299) || status === 304 || (redirect === 'manual' && 300 <= status && status < 400)))
             throw new StatusCodeError(status, url.toString());
     }
@@ -234,8 +230,8 @@ export async function request(url, options = {}) {
         :
             body_;
 }
-function get_dispatcher(proxy, redirect, long_connection) {
-    const key = `${proxy || (long_connection ? 'direct.long' : 'direct')}.${redirect}`;
+function get_dispatcher(proxy, redirect) {
+    const key = `${proxy || 'direct'}.${redirect}`;
     let dispatcher = dispatchers[key];
     if (dispatcher)
         return dispatcher;
@@ -243,7 +239,7 @@ function get_dispatcher(proxy, redirect, long_connection) {
         // @ts-ignore
         new undici.ProxyAgent({ uri: proxy })
         :
-            new undici.Agent({ keepAliveTimeout: long_connection ? 30_000 : undefined });
+            new undici.Agent({ allowH2: true });
     if (redirect === 'follow')
         dispatcher = dispatcher.compose(
         // todo: 强制手动处理重定向，来正确处理 cookie ?
@@ -297,4 +293,63 @@ export async function request_json(url, options) {
         throw error;
     }
 }
+/** 建立 tcp 连接，超时时间为 2 秒 (timeout 选项)，返回已连接的 socket
+    连接中遇到的错误会 reject，之后取消监听 error 事件，由调用者 attach 处理
+    - hostname: 要连接到的 ip 或域名
+    - port: 要连接的端口
+    - options?:
+        - timeout?: `2000` 超时时间
+        - print?: 打印连接日志，错误日志
+            - error?: `true`
+            - connect: `false` */
+export function connect(hostname, port, { timeout: _timeout = 2000, print = { error: true, connect: false } } = {}) {
+    let pconnected = defer2();
+    let timeouted = false;
+    function get_message(message) {
+        return `tcp://${hostname}:${port}  ${message}`;
+    }
+    let socket = net.connect({
+        host: hostname,
+        port,
+        noDelay: true
+    }, () => {
+        if (pconnected.settled) {
+            if (print)
+                console.warn(get_message('连接建立了，但是已超时'.yellow));
+            socket.resetAndDestroy();
+        }
+        else {
+            clearTimeout(timeout);
+            socket.off('error', on_error);
+            if (print.connect)
+                console.log(get_message('已连接'));
+            pconnected.resolve(socket);
+        }
+    });
+    const on_error = (error) => {
+        if (pconnected.settled) {
+            // 超时后可能会走到这里
+            if (timeouted && error.code === 'ERR_SOCKET_CLOSED')
+                return;
+            // 待观察：不太可能走到这里
+            if (print.error)
+                console.error(get_message(error.message.red));
+        }
+        else {
+            clearTimeout(timeout);
+            pconnected.reject(set_error_message(error, get_message(error.message)));
+        }
+    };
+    socket.once('error', on_error);
+    let timeout = setTimeout(() => {
+        // 执行到这里一定没有 settled
+        timeouted = true;
+        socket.resetAndDestroy();
+        pconnected.reject(new TimeoutError(get_message('超时了')));
+    }, _timeout);
+    return pconnected;
+}
+export function get_socket_ip(socket) {
+    return socket.remoteAddress.strip_if_start('::ffff:');
+}
 //# sourceMappingURL=net.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xshell",
-    "version": "1.3.3",
+    "version": "1.3.5",
     "type": "module",
     "main": "./index.js",
     "bin": {
@@ -56,19 +56,19 @@
         "@stylistic/eslint-plugin": "^5.5.0",
         "@svgr/webpack": "^8.1.0",
         "@types/sass-loader": "^8.0.10",
-        "@typescript-eslint/eslint-plugin": "^8.46.2",
-        "@typescript-eslint/parser": "^8.46.2",
-        "@typescript-eslint/utils": "^8.46.2",
+        "@typescript-eslint/eslint-plugin": "^8.46.3",
+        "@typescript-eslint/parser": "^8.46.3",
+        "@typescript-eslint/utils": "^8.46.3",
         "archiver": "^7.0.1",
         "chalk": "^5.6.2",
         "commander": "^14.0.2",
         "css-loader": "^7.1.2",
         "emoji-regex": "^10.6.0",
-        "eslint": "^9.39.0",
+        "eslint": "^9.39.1",
         "eslint-plugin-import": "^2.32.0",
         "eslint-plugin-react": "^7.37.5",
         "https-proxy-agent": "^7.0.6",
-        "i18next": "^25.6.0",
+        "i18next": "^25.6.1",
         "i18next-scanner": "^4.6.0",
         "koa": "^3.1.1",
         "koa-compress": "^5.1.1",
@@ -76,7 +76,7 @@
         "mime-types": "^3.0.1",
         "p-map": "^7.0.3",
         "react": "^19.2.0",
-        "react-i18next": "^16.2.3",
+        "react-i18next": "^16.2.4",
         "resolve-path": "^1.4.0",
         "sass": "^1.93.3",
         "sass-loader": "^16.0.6",
@@ -101,7 +101,7 @@
         "@types/koa": "^3.0.1",
         "@types/koa-compress": "^4.0.7",
         "@types/mime-types": "^3.0.1",
-        "@types/node": "^24.9.2",
+        "@types/node": "^24.10.0",
         "@types/react": "^19.2.2",
         "@types/tough-cookie": "^4.0.5",
         "@types/vscode": "^1.105.0",

package/process.d.ts

@@ -31,10 +31,10 @@ interface BaseOptions {
     envs?: Record<string, string>;
     /** 创建子进程时添加 http_proxy, https_proxy, no_proxy 环境变量以启用代理 */
     proxy?: MyProxy | true;
-    /** 控制子进程 stdin，默认为 `false` (读空设备)，除非传入了 {@link CallOptions.input} 属性
+    /** 控制子进程 stdin，默认为 `Boolean(input)` (false 时读空设备)，除非传入了 {@link CallOptions.input} 属性
         - 默认值:
             - start(): false ('ignore', 空设备)
-            - (call|launch)(): true (pipe, 作为 child.stdout 可读流)
+            - (call|launch)(): false (pipe, 作为 child.stdin)
         - `true` 设置子进程 stdin 为 'pipe'
         - `false` 设置子进程 stdin 为 'ignore' (空设备)
         - `string` 设置子进程 stdin 为某个文件路径 (打开文件，将句柄设置为子进程 stdin) */
@@ -42,8 +42,8 @@ interface BaseOptions {
     /** 控制子进程 stdout
         - 默认值:
             - start(): false ('ignore', 空设备)
-            - (call|launch)(): true (pipe, 作为 child.stdout 可读流)
-        - `true` 设置子进程 stdout 为 'pipe' (作为 child.stdout 可读流)
+            - (call|launch)(): true (pipe, 作为 child.stdout)
+        - `true` 设置子进程 stdout 为 'pipe' (作为 child.stdout)
         - `false` 设置子进程 stdout 为 'ignore' (空设备)
         - `string` 设置子进程 stdout 某个文件路径 (打开文件，将句柄设置为子进程 stdout) */
     stdout?: boolean | string;

package/server.js

@@ -1,5 +1,5 @@
-import { createServer as http_create_server, } from 'node:http';
-import { createSecureServer as http2_create_server } from 'node:http2';
+import { default as http, } from 'node:http';
+import { default as http2 } from 'node:http2';
 import { createSecureContext } from 'node:tls';
 import zlib from 'node:zlib';
 import fs from 'node:fs';
@@ -12,8 +12,8 @@ import resolve_safely from 'resolve-path';
 import { contentType as get_content_type } from 'mime-types';
 // --- my libs
 import { t } from "./i18n/instance.js";
-import { request as _request, Remote } from "./net.js";
-import { inspect, check, range_to_numbers, encode, filter_keys, filter_values, consume_stream, colored, url_width } from "./utils.js";
+import { request as _request, Remote, get_socket_ip } from "./net.js";
+import { inspect, check, range_to_numbers, encode, filter_keys, filter_values, consume_stream, colored, url_width, defer2 } from "./utils.js";
 import { flist, fread, fstat } from "./file.js";
 import { exe_nodejs, sea } from "./process.js";
 // ------------ my server
@@ -138,9 +138,8 @@ export class Server {
         app.use(this._router.bind(this));
         this.app = app;
         this.handler = this.app.callback();
-        this.http_server = http_create_server({ optimizeEmptyRequests: true }, this.handler);
-        const { http, http2 } = this;
-        if (http2) {
+        this.http_server = http.createServer({ optimizeEmptyRequests: true, noDelay: true }, this.handler);
+        if (this.http2) {
             const { fpd_certs } = this;
             let lazy_secure_ctxs = Object.fromEntries(await Promise.all(
             // fpd_certs 文件夹下面的每个 .key 对应一个证书及域名
@@ -157,7 +156,7 @@ export class Server {
             })));
             const default_ctx = lazy_secure_ctxs[this.default_hostnames.find(hostname => hostname in lazy_secure_ctxs)];
             check(default_ctx);
-            this.http2_server = http2_create_server({
+            this.http2_server = http2.createSecureServer({
                 SNICallback(servername, callback) {
                     let lazy_ctx = lazy_secure_ctxs[servername] ||
                         lazy_secure_ctxs[servername.replace(/^.*?\./, '*.')] ||
@@ -166,6 +165,7 @@ export class Server {
                     callback(null, lazy_ctx.ctx ??= createSecureContext(lazy_ctx));
                 },
                 allowHTTP1: true,
+                noDelay: true
             }, this.handler);
         }
         // websocket rpc
@@ -229,20 +229,16 @@ export class Server {
         }
         await this.init_server();
         await Promise.all([
-            http && new Promise(resolve => {
-                this.http_server.listen(this.http_port, resolve);
-            }),
-            http2 && new Promise(resolve => {
-                this.http2_server.listen(this.http2_port, resolve);
-            }),
+            this.http && listen_http_server(this.http_server, this.http_port),
+            this.http2 && listen_http_server(this.http2_server, this.http2_port)
         ]);
         if (this.print.info)
             console.log(t('{{name}} 启动成功，正在监听 {{ports}} 端口', {
                 name: this.name,
                 ports: [
-                    ...http ? [this.http_port] : [],
-                    ...http2 ? [this.http2_port] : []
-                ].join(', ')
+                    this.http && this.http_port,
+                    this.http2 && this.http2_port
+                ].filter(Boolean).join(', ')
             }));
     }
     try_write_stdio_subscribers(chunk) {
@@ -258,25 +254,25 @@ export class Server {
     }
     stop() {
         this.http_server.close();
-        if (this.http2_server)
-            this.http2_server.close();
+        this.http2_server?.close();
     }
     /** 可被子类重写定义错误处理逻辑 */
     on_error(error, ctx) {
-        if (this.print.errors) {
-            const code = error?.code;
-            if (code === 'EPIPE' || code === 'ECONNRESET')
-                console.log(`${error.code}:`, ctx?.request?.url);
-            else {
-                console.error(error);
-                if (ctx)
-                    console.log('ctx:', ctx);
-            }
+        if (!this.print.errors)
+            return;
+        const code = error?.code;
+        if (code === 'EPIPE' || code === 'ECONNRESET')
+            console.log(`${error.code}:`, ctx?.request?.url);
+        else {
+            console.error(error);
+            if (ctx)
+                console.log('ctx:', ctx);
         }
     }
     on_upgrade(request, socket, head) {
         // url 只有路径部分
         const { url, headers, headers: { host = '' }, } = request;
+        const ip = get_socket_ip(request.socket);
         if (this.print.logs) {
             let s = 
             // 时间
@@ -289,7 +285,7 @@ export class Server {
                 url;
             s = s.pad(url_width);
             // ip
-            s += `  <-  ${request.socket.remoteAddress.strip_if_start('::ffff:')}`;
+            s += `  <-  ${ip}`;
             // 客户端信息
             const client_info = this.get_client_info(headers);
             if (client_info)
@@ -327,7 +323,7 @@ export class Server {
                 console.error(error);
             response.status = error.status || 500;
             response.set('content-type', text_plain);
-            response.body = inspect(error, { colors: false });
+            response.body = inspect_error(error);
         }
     }
     /** 解析 req.body to request.body
@@ -638,7 +634,8 @@ export class Server {
                 if (this.print.errors)
                     console.log(error);
                 response.status = 500;
-                response.body = inspect(error, { colors: false });
+                response.set('content-type', text_plain);
+                response.body = inspect_error(error);
             }
         }
         return true;
@@ -800,7 +797,7 @@ export class Server {
         - reverse?: `false` 在 range 内从后往前尝试 */
     static async get_available_port(range, reverse = false) {
         for (const port of range_to_numbers(range, reverse)) {
-            let server = http_create_server();
+            let server = http.createServer();
             try {
                 await new Promise((resolve, reject) => {
                     server.once('error', reject);
@@ -825,4 +822,17 @@ export class Server {
 }
 export const text_plain = 'text/plain; charset=utf-8';
 const devtools_trash = '/.well-known/appspecific/com.chrome.devtools.json';
+function listen_http_server(server, port) {
+    let plisten = defer2();
+    server.once('error', plisten.reject);
+    server.listen(port, () => {
+        server.off('error', plisten.reject);
+        plisten.resolve();
+    });
+    return plisten;
+}
+const no_color = { colors: false };
+function inspect_error(error) {
+    return inspect(error, no_color);
+}
 //# sourceMappingURL=server.js.map

package/utils.common.d.ts

@@ -50,7 +50,7 @@ export declare function filter_values<TObj extends Record<string, any>>(obj: TOb
 /** 简单选择对象中的部分 keys, 返回新对象 */
 export declare function pick<TObject = any>(obj: TObject, keys: (keyof TObject)[]): Partial<TObject>;
 /** 忽略对象中的 keys, 返回新对象 */
-export declare function omit<TObj>(obj: TObj, omit_keys: string[]): TObj;
+export declare function omit<TObj>(obj: TObj, omit_keys: string[] | Set<string>): TObj;
 /** 拼接 TypedArrays 生成一个完整的 Uint8Array */
 export declare function concat(arrays: ArrayBufferView[]): Uint8Array<ArrayBufferLike>;
 export declare let encoder: TextEncoder;
@@ -66,11 +66,15 @@ export declare function buffer_equals(left: Uint8Array, right: Uint8Array | stri
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后抛出错误或调用 on_timeout
     - milliseconds: 限时毫秒数
     - action?: 要等待运行的任务, async function 或 promise
-    - on_timeout?: 超时后调用的函数
-        - 若传: 调用 on_timeout，参数为 TimeoutError，然后 timeout 函数正常返回 null
-        - 若不传: 抛出 TimeoutError
+    - on_timeout?: 超时后调用的函数，或者设置错误消息
+        - 若传:
+            - 传 string: 作为 TimeoutError 的 error message
+            - 传 function: 超时时调用会调用 on_timeout，参数为 TimeoutError，然后等待 on_timeout 执行完成
+                - on_timeout 函数正常运行: timeout 函数返回 null
+                - on_timeout 报错: timeout 函数最终抛出这个错误
+        - 若不传: 直接抛出 TimeoutError
     - print?: `true` 打印已超时任务的错误 */
-export declare function timeout<TReturn>(milliseconds: number, action: Promise<TReturn> | (() => Promise<TReturn>), on_timeout?: (error: TimeoutError) => void | Promise<void>, print?: boolean): Promise<TReturn>;
+export declare function timeout<TReturn>(milliseconds: number, action: Promise<TReturn> | (() => Promise<TReturn>), on_timeout?: string | ((error: TimeoutError) => void | Promise<void>), print?: boolean): Deferred2<TReturn>;
 /** 轮询尝试 action 共 times 次，每次间隔 duration
     action 返回 trusy 值时认为成功，返回 action 的结果
     如果次数用尽仍然失败，返回 null */
@@ -118,7 +122,7 @@ export type StrictArrayBuffer = ArrayBuffer & {
 };
 export interface Deferred<TValue> extends Promise<TValue> {
     resolve(value: TValue | PromiseLike<TValue>): void;
-    reject(reason?: Error): void;
+    reject(error?: Error): void;
 }
 /** 创建一个 promise，后续可调用 promise.resolve, promise.reject 方法设置其状态和值
     - initial?: `undefined` 传入非 undefined 值（包括 null）时直接设置为 resolved 状态
@@ -126,7 +130,7 @@ export interface Deferred<TValue> extends Promise<TValue> {
 export declare function defer<TValue>(initial?: TValue): Deferred<TValue>;
 export interface Deferred2<TValue> extends Promise<TValue> {
     resolve(value: TValue | PromiseLike<TValue>): void;
-    reject(reason?: Error): void;
+    reject(error?: Error): void;
     get settled(): boolean;
 }
 /** 有 settled 状态的 defer */
@@ -167,7 +171,7 @@ export declare function lowercase_first_letter(str: string): string;
 export declare function ceil2(n: number): number;
 /** 节流，最多只在时间间隔末尾调用一次，可以设置首次调用是否延后 */
 export declare function throttle(duration: number, func: Function, delay_first?: boolean): (this: any, ...args: any[]) => void;
-/** 防抖，间隔一段时间不再触发时调用 */
+/** 防抖，间隔一段时间不再触发时调用，同时大幅优化减少 setTimeout, clearTimeout 的调用次数 */
 export declare function debounce(duration: number, func: Function): (this: any, ...args: any[]) => void;
 export declare function tomorrow(date?: Date | string | number): Date;
 export declare function to_csv_field(str: string): string;
@@ -176,10 +180,3 @@ export declare function set_error_message(error: Error, message: string): Error;
 /** 比较两个数组中的元素完全相同，数组元素用引用比较 */
 export declare function array_equals(a: any[], b: any[]): boolean;
 export declare function nowstr(with_date?: boolean): string;
-interface MyTimeout {
-    clear(): void;
-    ref: NodeJS.Timeout | number;
-}
-/** 面向对象的 timeout, callback 在后的 timeout */
-export declare function set_timeout(delay: number, callback: VoidFunction): MyTimeout;
-export {};

package/utils.common.js

@@ -136,8 +136,11 @@ export function pick(obj, keys) {
 }
 /** 忽略对象中的 keys, 返回新对象 */
 export function omit(obj, omit_keys) {
-    const omit_keys_ = new Set(omit_keys);
-    return filter_keys(obj, key => !omit_keys_.has(key));
+    const set = omit_keys instanceof Set;
+    return filter_keys(obj, set ?
+        key => !(omit_keys.has(key))
+        :
+            key => !(omit_keys.includes(key)));
 }
 /** 拼接 TypedArrays 生成一个完整的 Uint8Array */
 export function concat(arrays) {
@@ -183,55 +186,52 @@ export function buffer_equals(left, right) {
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后抛出错误或调用 on_timeout
     - milliseconds: 限时毫秒数
     - action?: 要等待运行的任务, async function 或 promise
-    - on_timeout?: 超时后调用的函数
-        - 若传: 调用 on_timeout，参数为 TimeoutError，然后 timeout 函数正常返回 null
-        - 若不传: 抛出 TimeoutError
+    - on_timeout?: 超时后调用的函数，或者设置错误消息
+        - 若传:
+            - 传 string: 作为 TimeoutError 的 error message
+            - 传 function: 超时时调用会调用 on_timeout，参数为 TimeoutError，然后等待 on_timeout 执行完成
+                - on_timeout 函数正常运行: timeout 函数返回 null
+                - on_timeout 报错: timeout 函数最终抛出这个错误
+        - 若不传: 直接抛出 TimeoutError
     - print?: `true` 打印已超时任务的错误 */
-export async function timeout(milliseconds, action, on_timeout, print = true) {
-    const error = new TimeoutError();
-    return new Promise((resolve, reject) => {
-        let done = false;
-        let rejected = false;
-        (async () => {
-            await delay(milliseconds);
-            if (!done)
-                if (on_timeout)
-                    try {
-                        await on_timeout(error);
-                        resolve(null);
-                    }
-                    catch (error) {
-                        if (rejected)
-                            throw error; // 会成为 unhandled rejection
-                        else {
-                            rejected = true;
-                            reject(error);
-                        }
-                    }
-                else {
-                    rejected = true;
-                    reject(error);
-                }
-        })();
-        (async () => {
+export function timeout(milliseconds, action, on_timeout, print = true) {
+    const error = new TimeoutError(typeof on_timeout === 'string' ? on_timeout : undefined);
+    let presult = defer2();
+    let waiting_on_timeout = false;
+    let timeout = setTimeout(async () => {
+        if (typeof on_timeout === 'function')
             try {
-                resolve(await (typeof action === 'function' ? action() : action));
+                waiting_on_timeout = true;
+                await on_timeout(error);
+                presult.resolve(null);
             }
             catch (error) {
-                if (rejected) {
-                    if (print)
-                        console.log(`已超时任务的错误: ${error.message}`);
-                }
-                else {
-                    rejected = true;
-                    reject(error);
-                }
-            }
-            finally {
-                done = true;
+                presult.reject(error);
             }
-        })();
+        else
+            presult.reject(error);
+    }, milliseconds);
+    const paction = typeof action === 'function' ? action() : action;
+    paction.then(result => {
+        if (presult.settled) {
+            if (print)
+                console.log('已超时任务最终完成了');
+        }
+        else if (!waiting_on_timeout) {
+            presult.resolve(result);
+            clearTimeout(timeout);
+        }
+    }, error => {
+        if (presult.settled) {
+            if (print)
+                console.error(`已超时任务的错误: ${error.message}`);
+        }
+        else if (!waiting_on_timeout) {
+            presult.reject(error);
+            clearTimeout(timeout);
+        }
     });
+    return presult;
 }
 /** 轮询尝试 action 共 times 次，每次间隔 duration
     action 返回 trusy 值时认为成功，返回 action 的结果
@@ -382,19 +382,18 @@ export class TimeoutError extends Error {
 // eslint-disable-next-line @typescript-eslint/promise-function-async
 export function defer(initial) {
     if (initial === undefined) {
-        let resolve;
-        let reject;
-        let promise = new Promise((_resolve, _reject) => {
-            resolve = _resolve;
-            reject = _reject;
-        });
-        return Object.assign(promise, { resolve, reject });
+        let { promise, resolve, reject } = Promise.withResolvers();
+        let p = promise;
+        p.resolve = resolve;
+        p.reject = reject;
+        return p;
+    }
+    else {
+        let p = Promise.resolve(initial);
+        p.resolve = noop;
+        p.reject = noop;
+        return p;
     }
-    else
-        return Object.assign(Promise.resolve(initial), {
-            resolve: noop,
-            reject: noop
-        });
 }
 /** 有 settled 状态的 defer */
 // eslint-disable-next-line @typescript-eslint/promise-function-async
@@ -402,26 +401,29 @@ export function defer2(initial) {
     if (initial === undefined) {
         let settled = false;
         let { promise, resolve, reject } = Promise.withResolvers();
-        return Object.assign(promise, {
-            resolve(value) {
-                settled = true;
-                resolve(value);
-            },
-            reject(error) {
-                settled = true;
-                reject(error);
-            },
-            get settled() {
-                return settled;
-            }
+        let p = promise;
+        p.resolve = (value) => {
+            settled = true;
+            resolve(value);
+        };
+        p.reject = (error) => {
+            settled = true;
+            reject(error);
+        };
+        Object.defineProperty(p, 'settled', {
+            get() { return settled; },
+            enumerable: true,
+            configurable: true
         });
+        return p;
+    }
+    else {
+        let p = Promise.resolve(initial);
+        p.resolve = noop;
+        p.reject = noop;
+        p.settled = true;
+        return p;
     }
-    else
-        return Object.assign(Promise.resolve(initial), {
-            resolve: noop,
-            reject: noop,
-            settled: true
-        });
 }
 /** @example
     let lock = new Lock(redis)
@@ -508,8 +510,8 @@ export function ceil2(n) {
 export function throttle(duration, func, delay_first = false) {
     let timeout = 0;
     let last = 0;
-    let saved_this = null;
-    let saved_args = null;
+    let saved_this;
+    let saved_args;
     return function throttled(...args) {
         // 当前时间间隔已预定执行，本次调用仅更新调用参数
         if (timeout) {
@@ -539,14 +541,33 @@ export function throttle(duration, func, delay_first = false) {
         }
     };
 }
-/** 防抖，间隔一段时间不再触发时调用 */
+/** 防抖，间隔一段时间不再触发时调用，同时大幅优化减少 setTimeout, clearTimeout 的调用次数 */
 export function debounce(duration, func) {
-    let timeout = null;
+    const half = Math.floor(duration / 2);
+    let timeout;
+    let last = 0;
+    let saved_args;
+    let saved_this;
+    function debounce_callback() {
+        timeout = null;
+        func.apply(saved_this, saved_args);
+        saved_this = null;
+        saved_args = null;
+    }
     return function debounced(...args) {
+        if (!timeout) {
+            timeout = setTimeout(debounce_callback, duration);
+            last = Date.now();
+            return;
+        }
+        const now = Date.now();
+        saved_args = args;
+        saved_this = this;
+        if (now - last < half)
+            return;
         clearTimeout(timeout);
-        timeout = setTimeout(() => {
-            func.apply(this, args);
-        }, duration);
+        setTimeout(debounce_callback, duration);
+        last = now;
     };
 }
 export function tomorrow(date) {
@@ -576,17 +597,4 @@ export function nowstr(with_date = false) {
     const date = new Date();
     return with_date ? date.to_str() : date.to_time_str();
 }
-/** 面向对象的 timeout, callback 在后的 timeout */
-export function set_timeout(delay, callback) {
-    let ret = {
-        ref: setTimeout(callback, delay),
-        clear() {
-            if (!ret.ref)
-                return;
-            clearTimeout(ret.ref);
-            ret.ref = null;
-        }
-    };
-    return ret;
-}
 //# sourceMappingURL=utils.common.js.map

package/utils.d.ts

@@ -45,7 +45,6 @@ export declare function map_stream<Out, In = any>(mapper: (obj: In, cb: Function
     failures?: boolean;
 }): Duplex;
 export declare function stream_to_lines(stream: Readable): AsyncGenerator<string, void, unknown>;
-export declare function pipe_with_error<TWritable extends Writable>(readable: Readable, writable: TWritable): TWritable;
 export declare class WritableMemoryStream extends Writable {
     chunks: Uint8Array[];
     pbuffer: import("./utils.common.ts").Deferred<Buffer<ArrayBufferLike>>;

package/utils.js

@@ -225,11 +225,6 @@ export async function* stream_to_lines(stream) {
         buf = chunk.slice(j);
     }
 }
-export function pipe_with_error(readable, writable) {
-    // 不知道 transform 作为 AsyncIterable 使用时， emit error 是否会在 for await (...) 循环中触发错误
-    readable.once('error', error => { writable.emit('error', error); });
-    return readable.pipe(writable);
-}
 export class WritableMemoryStream extends Writable {
     chunks = [];
     pbuffer = defer();

package/xlint.js

@@ -787,9 +787,6 @@ export const xlint_config = {
         '@typescript-eslint/dot-notation': 'error',
         // 必须 throw Error
         '@typescript-eslint/only-throw-error': 'error',
-        // ------------ async
-        // 返回 Promise 的函数一定要标记为 async 函数
-        '@typescript-eslint/promise-function-async': 'error',
         // 不要 return await promise, 直接 return promise, 除非外面有 try catch
         '@typescript-eslint/return-await': 'error',
         // ------------ 括号